CFData Reference

Derived from
Framework
CoreFoundation/CoreFoundation.h
Declared in
CFData.h
Companion guides

Overview

CFData and its derived mutable type, CFMutableData Reference, 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 “Toll-Free Bridged Types” for more information on toll-free bridging.

Functions by Task

Creating a CFData Object

Examining a CFData Object

Getting the CFData Type ID

Functions

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 OS X v10.0 and later.
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 OS X v10.0 and later.
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. On a NULL return, the bytes buffer is left intact. 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 OS X v10.0 and later.
Related Sample Code
Declared In
CFData.h

CFDataFind

Finds and returns the range within a data object of the first occurrence of the given data, within a given range, subject to any given options.

CFRange CFDataFind(
   CFDataRef theData,
   CFDataRef dataToFind,
   CFRange searchRange,
   CFDataSearchFlags compareOptions
);
Parameters
theData

The data object within which to search.

dataToFind

The data to find. Must not be NULL.

searchRange

The range within theData to be searched.

compareOptions

A bit mask specifying search options. The CFDataSearchFlags options can be specified singly or combined with the C bitwise OR operator

Return Value

The range representing the location and length of dataToFind within searchRange, modulo the options in compareOptions. The range returned is relative to the start of the searched data, not the passed-in search range. Returns {kCFNotFound, 0} if dataToFind is not found.

Availability
  • Available in OS X v10.6 and later.
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 OS X v10.0 and later.
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 OS X v10.0 and later.
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 OS X v10.0 and later.
Declared In
CFData.h

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 OS X v10.0 and later.
Declared In
CFData.h

Data Types

CFDataRef

A reference to an immutable CFData object.

typedef const struct __CFData *CFDataRef;
Availability
  • Available in OS X v10.0 and later.
Declared In
CFData.h

CFDataSearchFlags

A CFOptionFlags type for specifying options for searching.

typedef enum : CFOptionFlags {
   kCFDataSearchBackwards = 1UL << 0,
   kCFDataSearchAnchored = 1UL << 1
} CFDataSearchFlags;
Constants
kCFDataSearchBackwards

Performs searching from the end of the range toward the beginning.

Available in OS X v10.6 and later.

Declared in CFData.h.

kCFDataSearchAnchored

Performs searching only on bytes at the beginning or, if kCFDataSearchBackwards is also specified, at the end of the search range. No match at the beginning or end means nothing is found, even if a matching sequence of bytes occurs elsewhere in the data object.

Available in OS X v10.6 and later.

Declared in CFData.h.

Availability
  • Available in OS X v10.6 and later.
Declared In
CFData.h