CMAttachment Reference

Framework	CoreMedia.framework
Declared in	CMAttachment.h

Overview

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

CMCopyDictionaryOfAttachments

Returns all attachments of a CMAttachmentBearer.

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 CMAttachmentBearer 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 buffer 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 CFDictionary that the caller must dispose by calling CFRelease. Given a CVBufferRef, CMCopyDictionaryOfAttachments is similar to CVBufferGetAttachments, except that the CFDictionary returned by CMCopyDictionaryOfAttachments is not updated for later changes to the attachments.

Availability

Available in iOS 4.0 and later.

Related Sample Code

SquareCam

Declared In

CMAttachment.h

CMGetAttachment

Returns a specific attachment of a CMAttachmentBearer

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

Parameters

target: Specifies the CMAttachmentBearer whose attachment you want to obtain.
key: Key in 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. If the attachment mode is not defined, this parameter returns 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.

Availability

Available in iOS 4.0 and later.

Declared In

CMAttachment.h

CMPropagateAttachments

Copies all propagatable attachments from one buffer to another.

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.

Availability

Available in iOS 4.0 and later.

Declared In

CMAttachment.h

CMRemoveAllAttachments

Removes all attachments of a CMAttachmentBearer.

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 buffer and decrements their retain counts. Given a CVBufferRef, CMRemoveAllAttachments is equivalent to CVBufferRemoveAllAttachments.

Availability

Available in iOS 4.0 and later.

Declared In

CMAttachment.h

CMRemoveAttachment

Removes a specific attachment of a CMAttachmentBearer.

void CMRemoveAttachment (
   CMAttachmentBearerRef target,
   CFStringRef key
);

Parameters

target: The CMAttachmentBearer containing the attachment to remove.
key: Key in 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.

Availability

Available in iOS 4.0 and later.

Declared In

CMAttachment.h

CMSetAttachment

Sets or adds an attachment of a CMAttachmentBearer.

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 af 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 nil has no defined behavior. Given a CVBufferRef, CMSetAttachment is equivalent to CVBufferSetAttachment.

Availability

Available in iOS 4.0 and later.

Declared In

CMAttachment.h

CMSetAttachments

Sets a set of attachments for a CMAttachmentBearer.

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 array.
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.

Availability

Available in iOS 4.0 and later.

Declared In

CMAttachment.h

Data Types

CMAttachmentBearerRef

Type for objects that can bear attachments.

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.)

Availability

Available in iOS 4.0 and later.

Declared In

CMAttachment.h

CMAttachmentMode

Type to specify attachment modes.

typedef uint32_t CMAttachmentMode;

Discussion

For possible values, see “Attachment Modes.”

Availability

Available in iOS 4.0 and later.

Declared In

CMAttachment.h

Constants

Attachment Modes

The propagation modes of a Core Media buffer attachment..

enum {
   kCMAttachmentMode_ShouldNotPropagate    = 0,
   kCMAttachmentMode_ShouldPropagate       = 1
};

Constants

kCMAttachmentMode_ShouldNotPropagate

Do not propagate this attachment.

Available in iOS 4.0 and later.

Declared in CMAttachment.h.

kCMAttachmentMode_ShouldPropagate

Copy this attachment when using the CMPropagateAttachments function.

Available in iOS 4.0 and later.

Declared in CMAttachment.h.

Discussion

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

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.