---

CFData Reference

Overview

CFData and its derived mutable type, CFMutableData, provide support for data objects, object-oriented wrappers for byte buffers. Data objects let simple allocated buffers (that is, data with no embedded pointers) take on the behavior of Core Foundation objects. CFData creates static data objects, and CFMutableData creates dynamic data objects. Data objects are typically used for raw data storage.

You use the CFDataCreate and CFDataCreateCopy functions to create static data objects. These functions make a new copy of the supplied data. To create a data object that uses the supplied buffer instead of making a separate copy, use the CFDataCreateWithBytesNoCopy function. You use the CFDataGetBytes function to retrieve the bytes and the CFDataGetLength function to get the length of the bytes.

CFData is “toll-free bridged” with its Cocoa Foundation counterpart, NSData. What this means is that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. In other words, in a method where you see an NSData * parameter, you can pass in a CFDataRef, and in a function where you see a CFDataRef parameter, you can pass in an NSData instance. This also applies to concrete subclasses of NSData. See Interchangeable Data Types for more information on toll-free bridging.

Functions by Task

Creating a CFData Object

• CFDataCreate
• CFDataCreateCopy
• CFDataCreateWithBytesNoCopy

Examining a CFData Object

• CFDataGetBytePtr
• CFDataGetBytes
• CFDataGetLength

Getting the CFData Type ID

Functions

CFDataGetTypeID

Returns the type identifier for the CFData opaque type.

CFTypeID CFDataGetTypeID (
   void
);

Return Value

The type identifier for the CFData opaque type.

Discussion

CFMutableData objects have the same type identifier as CFData objects.

Availability

• Available in CarbonLib v1.0 and later.
• Available in Mac OS X v10.0 and later.

Related Sample Code

• CFLocalServer
• MoreSCF
• RecentItems

Declared In

CFData.h

CFDataCreate

Creates an immutable CFData object using data copied from a specified byte buffer.

CFDataRef CFDataCreate (
   CFAllocatorRef allocator,
   const UInt8 *bytes,
   CFIndex length
);

Parameters

allocator

The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

bytes

A pointer to the byte buffer that contains the raw data to be copied into theData.

length

The number of bytes in the buffer (bytes).

Return Value

A new CFData object, or NULL if there was a problem creating the object. Ownership follows the Create Rule.

Discussion

You must supply a count of the bytes in the buffer. This function always copies the bytes in the provided buffer into internal storage.

Availability

• Available in CarbonLib v1.0 and later.
• Available in Mac OS X v10.0 and later.

Related Sample Code

• BackgroundExporter
• BasicInputMethod
• CFHostSample
• DTSCarbonShell
• TypeServicesForUnicode

Declared In

CFData.h

CFDataCreateCopy

Creates an immutable copy of a CFData object.

CFDataRef CFDataCreateCopy (
   CFAllocatorRef allocator,
   CFDataRef theData
);

Parameters

allocator

The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

theData

The CFData object to copy.

Return Value

An immutable copy of theData, or NULL if there was a problem creating the object. Ownership follows the Create Rule.

Discussion

The resulting object has the same byte contents as the original object, but it is always immutable. If the specified allocator and the allocator of the original object are the same, and the string is already immutable, this function may simply increment the retain count without making a true copy. To the caller, however, the resulting object is a true immutable copy, except the operation was more efficient.

Use this function when you need to pass a CFData object into another function by value (not reference).

Availability

• Available in CarbonLib v1.0 and later.
• Available in Mac OS X v10.0 and later.

Related Sample Code

• BackgroundExporter

Declared In

CFData.h

CFDataCreateWithBytesNoCopy

Creates an immutable CFData object from an external (client-owned) byte buffer.

CFDataRef CFDataCreateWithBytesNoCopy (
   CFAllocatorRef allocator,
   const UInt8 *bytes,
   CFIndex length,
   CFAllocatorRef bytesDeallocator
);

Parameters

allocator

The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

bytes

A pointer to the byte buffer to be used as the backing store of the CFData object.

length

The number of bytes in the buffer bytes.

bytesDeallocator

The allocator to use to deallocate the external buffer when the CFData object is deallocated. If the default allocator is suitable for this purpose, pass NULL or kCFAllocatorDefault. If you do not want the created CFData object to deallocate the buffer (that is, you assume responsibility for freeing it yourself), pass kCFAllocatorNull.

Return Value

A new CFData object, or NULL if there was a problem creating the object. Ownership follows the Create Rule.

Discussion

This function creates an immutable CFData object from a buffer of unstructured bytes. Unless the situation warrants otherwise, the created object does not copy the external buffer to internal storage but instead uses the buffer as its backing store. However, you should never count on the object using the external buffer since it could copy the buffer to internal storage or might even dump the buffer altogether and use alternative means for storing the bytes.

Availability

• Available in CarbonLib v1.0 and later.
• Available in Mac OS X v10.0 and later.

Related Sample Code

• BSDLLCTest
• MoreIsBetter
• QISA

Declared In

CFData.h

CFDataGetBytePtr

Returns a read-only pointer to the bytes of a CFData object.

const UInt8 * CFDataGetBytePtr (
   CFDataRef theData
);

Parameters

theData

The CFData object to examine.

Return Value

A read-only pointer to the bytes associated with theData.

Discussion

This function is guaranteed to return a pointer to a CFData object's internal bytes. CFData, unlike CFString, does not hide its internal storage.

Availability

• Available in CarbonLib v1.0 and later.
• Available in Mac OS X v10.0 and later.

Related Sample Code

• BackgroundExporter
• CFHostSample
• CFLocalServer
• MoreSCF
• TypeServicesForUnicode

Declared In

CFData.h

CFDataGetBytes

Copies the byte contents of a CFData object to an external buffer.

void CFDataGetBytes (
   CFDataRef theData,
   CFRange range,
   UInt8 *buffer
);

Parameters

theData

The CFData object to examine.

range

The range of bytes in theData to get. To get all of the contents, pass CFRangeMake(0,CFDataGetLength(theData)).

buffer

A pointer to the byte buffer of length range.length that is allocated on the stack or heap. On return, the buffer contains the requested range of bytes.

Availability

• Available in CarbonLib v1.0 and later.
• Available in Mac OS X v10.0 and later.

Related Sample Code

• BasicInputMethod
• DTSCarbonShell
• MoreIsBetter
• QISA
• QTCarbonShell

Declared In

CFData.h

CFDataGetLength

Returns the number of bytes contained by a CFData object.

CFIndex CFDataGetLength (
   CFDataRef theData
);

Parameters

theData

The CFData object to examine.

Return Value

An index that specifies the number of bytes in theData.

Availability

• Available in CarbonLib v1.0 and later.
• Available in Mac OS X v10.0 and later.

Related Sample Code

• CFLocalServer
• MoreIsBetter
• QISA
• RecentItems
• TypeServicesForUnicode

Declared In

CFData.h

Data Types

CFDataRef

A reference to an immutable CFData object.

typedef const struct __CFData *CFDataRef;

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFData.h

---