iOS Developer Library

Developer

CoreFoundation Framework Reference CFData Reference

Options
Deployment Target:

On This Page
Language:

CFData Reference

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

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

    Declaration

    Swift

    func CFDataCreate(_ allocator: CFAllocator!, _ bytes: UnsafePointer<UInt8>, _ length: CFIndex) -> CFData!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Creates an immutable copy of a CFData object.

    Declaration

    Swift

    func CFDataCreateCopy(_ allocator: CFAllocator!, _ theData: CFData!) -> CFData!

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func CFDataCreateWithBytesNoCopy(_ allocator: CFAllocator!, _ bytes: UnsafePointer<UInt8>, _ length: CFIndex, _ bytesDeallocator: CFAllocator!) -> CFData!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func CFDataGetBytePtr(_ theData: CFData!) -> UnsafePointer<UInt8>

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func CFDataGetBytes(_ theData: CFData!, _ range: CFRange, _ buffer: UnsafeMutablePointer<UInt8>)

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the number of bytes contained by a CFData object.

    Declaration

    Swift

    func CFDataGetLength(_ theData: CFData!) -> CFIndex

    Objective-C

    CFIndex CFDataGetLength ( CFDataRef theData );

    Parameters

    theData

    The CFData object to examine.

    Return Value

    An index that specifies the number of bytes in theData.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func CFDataFind(_ theData: CFData!, _ dataToFind: CFData!, _ searchRange: CFRange, _ compareOptions: CFDataSearchFlags) -> CFRange

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 4.0 and later.

  • Returns the type identifier for the CFData opaque type.

    Declaration

    Swift

    func CFDataGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CFDataGetTypeID ( void );

    Return Value

    The type identifier for the CFData opaque type.

    Discussion

    CFMutableData objects have the same type identifier as CFData objects.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

Data Types

Miscellaneous

  • A reference to an immutable CFData object.

    Declaration

    Swift

    typealias CFDataRef = CFData

    Objective-C

    typedef const struct __CFData *CFDataRef;

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • A CFOptionFlags type for specifying options for searching.

    Declaration

    Swift

    struct CFDataSearchFlags : RawOptionSetType { init(_ rawValue: CFOptionFlags) init(rawValue rawValue: CFOptionFlags) static var Backwards: CFDataSearchFlags { get } static var Anchored: CFDataSearchFlags { get } }

    Objective-C

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

    Constants

    • Backwards

      kCFDataSearchBackwards

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

      Available in iOS 4.0 and later.

    • Anchored

      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 iOS 4.0 and later.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 4.0 and later.