Mac Developer Library

Developer

CoreMedia Framework Reference CMAttachment Reference

Options
Deployment Target:

On This Page
Language:

CMAttachment Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import CoreMedia

Objective-C

@import CoreMedia;

This document describes the Core Media attachment protocol. A CMAttachmentBearer is a CF-based object that supports the suite of key/value/mode attachment APIs. You can attach any CF object to a CMAttachmentBearer object to store additional information.

Functions

  • Returns all attachments of a CMAttachmentBearer.

    Declaration

    Swift

    func CMCopyDictionaryOfAttachments(_ allocator: CFAllocator!, _ target: CMAttachmentBearer!, _ attachmentMode: CMAttachmentMode) -> Unmanaged<CFDictionary>!

    Objective-C

    CFDictionaryRef CMCopyDictionaryOfAttachments ( CFAllocatorRef allocator, CMAttachmentBearerRef target, CMAttachmentMode attachmentMode );

    Parameters

    allocator

    Allocator for the new dictionary; pass kCFAllocatorDefault or NULL to use the default allocator.

    target

    Specifies the CMAttachmentBearerRef whose attachments you want to obtain.

    attachmentMode

    The mode of the attachments you want to obtain. See Attachment Modes for possible values.

    Return Value

    A Core Foundation dictionary with all attachments identified by their keys. If no attachment is present, the dictionary is empty. Returns NULL for an invalid attachment mode.

    Discussion

    CMCopyDictionaryOfAttachments is a convenience call that returns all attachments with their corresponding keys in a new CFDictionaryRef. Given a CVBufferRef, CMCopyDictionaryOfAttachments is similar to CVBufferGetAttachments, except that the CFDictionary returned by CMCopyDictionaryOfAttachments is not updated for later changes to the attachments.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Returns a specific attachment of a CMAttachmentBearer.

    Declaration

    Swift

    func CMGetAttachment(_ target: CMAttachmentBearer!, _ key: CFString!, _ attachmentModeOut: UnsafeMutablePointer<CMAttachmentMode>) -> Unmanaged<AnyObject>!

    Objective-C

    CFTypeRef CMGetAttachment ( CMAttachmentBearerRef target, CFStringRef key, CMAttachmentMode *attachmentModeOut );

    Parameters

    target

    Specifies the CMAttachmentBearer whose attachment you want to obtain.

    key

    Key in the form of a CFString identifying the desired attachment.

    attachmentModeOut

    On output, attachmentMode points to the mode of the attachment. See Attachment Modes for possible values. May be NULL.

    Return Value

    If found, the specified attachment object; else NULL.

    Discussion

    You can attach any Core Foundation object to a CMAttachmentBearer to store additional information. CMGetAttachment retrieves an attachment identified by a key. Given a CVBufferRef, CMGetAttachment is equivalent to CVBufferGetAttachment.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Copies all attachments that can be propagated from one CMAttachmentBearer to another.

    Declaration

    Swift

    func CMPropagateAttachments(_ source: CMAttachmentBearer!, _ destination: CMAttachmentBearer!)

    Objective-C

    void CMPropagateAttachments ( CMAttachmentBearerRef source, CMAttachmentBearerRef destination );

    Parameters

    source

    CMAttachmentBearer to copy attachments from.

    destination

    CMAttachmentBearer to copy attachments to.

    Discussion

    CMPropagateAttachments is a convenience call that copies all attachments with a mode of kCMAttachmentMode_ShouldPropagate from one buffer to another. Given a CVBufferRef, CMPropagateAttachments is equivalent to CVBufferPropagateAttachments.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Removes all attachments of a CMAttachmentBearer.

    Declaration

    Swift

    func CMRemoveAllAttachments(_ target: CMAttachmentBearer!)

    Objective-C

    void CMRemoveAllAttachments ( CMAttachmentBearerRef target );

    Parameters

    target

    The CMAttachmentBearer whose attachment you want to remove.

    Discussion

    While CMRemoveAttachment removes a specific attachment identified by a key, CMRemoveAllAttachments removes all attachments of a CMAttachmentBearer and decrements their retain counts. Given a CVBufferRef, CMRemoveAllAttachments is equivalent to CVBufferRemoveAllAttachments.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Removes a specific attachment of a CMAttachmentBearer.

    Declaration

    Swift

    func CMRemoveAttachment(_ target: CMAttachmentBearer!, _ key: CFString!)

    Objective-C

    void CMRemoveAttachment ( CMAttachmentBearerRef target, CFStringRef key );

    Parameters

    target

    The CMAttachmentBearer containing the attachment to remove.

    key

    Key in the form of a Core Foundation string identifying the desired attachment.

    Discussion

    CMRemoveAttachment removes an attachment identified by a key. If found, the attachment is removed and the retain count decremented. Given a CVBufferRef, CMRemoveAttachment is equivalent to CVBufferRemoveAttachment.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Sets or adds an attachment of a CMAttachmentBearer.

    Declaration

    Swift

    func CMSetAttachment(_ target: CMAttachmentBearer!, _ key: CFString!, _ value: AnyObject!, _ attachmentMode: CMAttachmentMode)

    Objective-C

    void CMSetAttachment ( CMAttachmentBearerRef target, CFStringRef key, CFTypeRef value, CMAttachmentMode attachmentMode );

    Parameters

    target

    A CMAttachmentBearer object to add or set the attachments to.

    key

    The key, in the form of a Core Foundation string, identifying the desired attachment.

    value

    The attachment in the form of a Core Foundation object. If this parameter is NULL, the function returns an error.

    attachmentMode

    Specifies the attachment mode for this attachment. Any given attachment key may exist in only one mode at a time.

    Discussion

    You can attach any Core Foundation object to a CMAttachmentBearer object to store additional information. CMSetAttachment stores an attachment identified by a key. If the key doesn't currently exist for the CMAttachmentBearer object when you call this function, the new attachment is added. If the key does exist, the existing attachment is replaced. In both cases the retain count of the attachment is incremented. The value can be any CFType but a NULL value will result in an error. Given a CVBufferRef, CMSetAttachment is equivalent to CVBufferSetAttachment.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Sets a set of attachments for a CMAttachmentBearer.

    Declaration

    Swift

    func CMSetAttachments(_ target: CMAttachmentBearer!, _ theAttachments: CFDictionary!, _ attachmentMode: CMAttachmentMode)

    Objective-C

    void CMSetAttachments ( CMAttachmentBearerRef target, CFDictionaryRef theAttachments, CMAttachmentMode attachmentMode );

    Parameters

    target

    The target CMAttachmentBearer to set the attachement to.

    theAttachments

    The attachments to set, in the form of a Core Foundation dictionary.

    attachmentMode

    Specifies the attachment mode for this attachment. A particular attachment key may only exist in a single mode at a time.

    Discussion

    CMSetAttachments is a convenience call that in turn calls CMSetAttachment for each key and value in the given dictionary. All key value pairs must be in the root level of the dictionary. Given a CVBufferRef, CMSetAttachments is equivalent to CVBufferSetAttachments.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

Data Types

Miscellaneous

  • Type for objects that can bear attachments.

    Declaration

    Swift

    typealias CMAttachmentBearerRef = CMAttachmentBearer

    Objective-C

    typedef CFTypeRef CMAttachmentBearerRef;

    Discussion

    A CMAttachmentBearer is a Core Foundation-based object that supports the suite of key/value/mode attachment APIs. Since “plain” C has no type subclassing, CFType is used as the basis for the CMAttachmentBearer type. (Not all CFTypes support CMAttachmentBearer methods; if a CMAttachmentBearer method is called on a CF object that does not support it, it will fail.)

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Type to specify attachment modes.

    Declaration

    Swift

    typealias CMAttachmentMode = UInt32

    Objective-C

    typedef uint32_t CMAttachmentMode;

    Discussion

    For possible values, see Attachment Modes.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

Constants

  • The propagation modes of a CMAttachmentBearerRef attachment.

    Declaration

    Swift

    var kCMAttachmentMode_ShouldNotPropagate: Int { get } var kCMAttachmentMode_ShouldPropagate: Int { get }

    Objective-C

    enum { kCMAttachmentMode_ShouldNotPropagate = 0, kCMAttachmentMode_ShouldPropagate = 1 };

    Constants

    • kCMAttachmentMode_ShouldNotPropagate

      kCMAttachmentMode_ShouldNotPropagate

      Do not propagate this attachment.

      Available in OS X v10.7 and later.

    • kCMAttachmentMode_ShouldPropagate

      kCMAttachmentMode_ShouldPropagate

      Copy this attachment when using the CMPropagateAttachments function.

      Available in OS X v10.7 and later.

    Discussion

    You set these attributes when adding attachments to a CMAttachmentBearerRef object.