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

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
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 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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMAttachment.h

CMPropagateAttachments

Copies all attachments that can be propagated from one CMAttachmentBearer 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 CMAttachmentBearer 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 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.

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

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.

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 CMAttachmentBearerRef 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 CMAttachmentBearerRef object.