Mac Developer Library

Developer

OSData Class Reference

Options
Deployment Target:

On This Page
Language:

OSData

OSData wraps an array of bytes in a C++ object for use in Libkern collections. More...

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable @import Kernel;

Availability


Available in OS X v10.0 and later.
  • Appends a single byte value to the OSData object's internal data buffer a specified number of times.

    Declaration

    C++

    virtual bool appendByte( unsigned charbyte, unsigned intnumBytes);

    Parameters

    byte

    The byte value to append.

    numBytes

    The number of copies of byte to append.

    Return Value

    true if the new data was successfully added, false if not.

    Discussion

    This function immediately resizes the OSData's buffer, if necessary, to accommodate the new total size.

    An OSData object created "NoCopy" does not allow bytes to be appended.

    Import Statement

  • Appends the data contained in another OSData object.

    Declaration

    C++

    virtual bool appendBytes( const OSData *aDataObj);

    Parameters

    aDataObj

    The OSData object whose contents will be appended.

    Return Value

    true if the new data was successfully added, false on failure.

    Discussion

    This function immediately resizes the OSData's buffer, if necessary, to accommodate the new total size.

    An OSData object created "NoCopy" does not allow bytes to be appended.

    Import Statement

  • Appends a buffer of bytes to the OSData object's internal data buffer.

    Declaration

    C++

    virtual bool appendBytes( const void *bytes, unsigned intnumBytes);

    Parameters

    bytes

    A pointer to the data to append. If bytes is NULL then a zero-filled buffer of length numBytes is appended.

    numBytes

    The number of bytes from bytes to append.

    Return Value

    true if the new data was successfully added, false on failure.

    Discussion

    This function immediately resizes the OSData's buffer, if necessary, to accommodate the new total size.

    An OSData object created "NoCopy" does not allow bytes to be appended.

    Import Statement

  • Ensures the array has enough space to store the requested number of bytes.

    Declaration

    C++

    virtual unsigned int ensureCapacity( unsigned intnewCapacity);

    Parameters

    newCapacity

    The total number of bytes the OSData object should be able to store.

    Return Value

    Returns the new capacity of the OSData object, which may be different from the number requested (if smaller, reallocation of storage failed).

    Discussion

    This function immediately resizes the OSData's buffer, if necessary, to accommodate at least newCapacity bytes. If newCapacity is not greater than the current capacity, or if an allocation error occurs, the original capacity is returned.

    There is no way to reduce the capacity of an OSData.

    An OSData object created "NoCopy" does not allow resizing.

    Import Statement

  • Deallocates or releases any resources used by the OSDictionary instance.

    Declaration

    C++

    virtual void free();

    Discussion

    This function should not be called directly; use release instead.

    Import Statement

  • Returns a pointer to the OSData object's internal data buffer.

    Declaration

    C++

    virtual const void * getBytesNoCopy() const;

    Return Value

    A pointer to the OSData object's internal data buffer.

    Discussion

    You can modify the existing contents of an OSData object via this function. It works with OSData objects that have their own data buffers as well as with OSData objects that have shared buffers.

    If you append bytes or characters to an OSData object, it may have to reallocate its internal storage, rendering invalid an extrated pointer to that storage.

    Import Statement

  • Returns a pointer into the OSData object's internal data buffer with a given offset and length.

    Declaration

    C++

    virtual const void * getBytesNoCopy( unsigned intstart, unsigned intnumBytes) const;

    Parameters

    start

    The offset from the base of the internal data buffer.

    numBytes

    The length of the window.

    Return Value

    A pointer to the bytes in the specified range within the OSData object, or 0 if that range does not lie completely within the object's buffer.

    Discussion

    You can modify the existing contents of an OSData object via this function. It works with OSData objects that have their own data buffers as well as with OSData objects that have shared buffers.

    If you append bytes or characters to an OSData object, it may have to reallocate its internal storage, rendering invalid an extrated pointer to that storage.

    Import Statement

  • Returns the total number of bytes the OSData can store without reallocating.

    Declaration

    C++

    virtual unsigned int getCapacity() const;

    Return Value

    The total number bytes the OSData can store without reallocating.

    Discussion

    OSData objects grow when full to accommodate additional bytes. See getCapacityIncrement and ensureCapacity.

    OSData objects created or initialized to use a shared buffer do not make use of this attribute, and return -1 from this function.

    Import Statement

  • Returns the storage increment of the OSData object.

    Declaration

    C++

    virtual unsigned int getCapacityIncrement() const;

    Return Value

    The storage increment of the OSData object.

    Discussion

    An OSData object allocates storage for bytes in multiples of the capacity increment.

    OSData objects created or initialized to use a shared buffer do not make use of this attribute.

    Import Statement

  • Returns the number of bytes in or referenced by the OSData object.

    Declaration

    C++

    virtual unsigned int getLength() const;

    Return Value

    The number of bytes in or referenced by the OSData object.

    Import Statement

  • Initializes an instance of OSData with a copy of the provided data buffer.

    Declaration

    C++

    virtual bool initWithBytes( const void *bytes, unsigned intnumBytes);

    Parameters

    bytes

    The buffer of data to copy.

    numBytes

    The length of bytes.

    Return Value

    true on success, false on failure.

    Discussion

    Not for general use. Use the static instance creation method withBytes instead.

    The new OSData object will grow as needed to accommodate more bytes (unlike CFMutableData, for which a nonzero initial capacity is a hard limit).

    Import Statement

  • Initializes an instance of OSData to share the provided data buffer.

    Declaration

    C++

    virtual bool initWithBytesNoCopy( void *bytes, unsigned intnumBytes);

    Parameters

    bytes

    The buffer of data to represent.

    numBytes

    The length of bytes.

    Return Value

    true on success, false on failure.

    Discussion

    Not for general use. Use the static instance creation method withBytesNoCopy instead.

    An OSData object initialized with this function does not claim ownership of the data buffer, but merely shares it with the caller.

    An OSData object created with shared external data cannot append bytes, but you can get the byte pointer and modify bytes within the shared buffer.

    Import Statement

  • Initializes an instance of OSData.

    Declaration

    C++

    virtual bool initWithCapacity( unsigned intcapacity);

    Parameters

    capacity

    The initial capacity of the OSData object in bytes.

    Return Value

    true on success, false on failure.

    Discussion

    Not for general use. Use the static instance creation method withCapacity instead.

    capacity may be zero. The OSData object will allocate a buffer internally when necessary, and will grow as needed to accommodate more bytes (unlike CFMutableData, for which a nonzero initial capacity is a hard limit).

    Import Statement

  • Creates and initializes an instance of OSData with contents copied from another OSData object.

    Declaration

    C++

    virtual bool initWithData( const OSData *inData);

    Parameters

    inData

    An OSData object that provides the initial data.

    Return Value

    true on success, false on failure.

    Discussion

    Not for general use. Use the static instance creation method withData(OSData *) instead.

    The new OSData object will grow as needed to accommodate more bytes (unlike CFMutableData, for which a nonzero initial capacity is a hard limit).

    Import Statement

  • Initializes an instance of OSData with contents copied from a range within another OSData object.

    Declaration

    C++

    virtual bool initWithData( const OSData *inData, unsigned intstart, unsigned intnumBytes);

    Parameters

    inData

    An OSData object that provides the initial data.

    start

    The starting index from which bytes will be copied.

    numBytes

    The number of bytes to be copied from start.

    Return Value

    Returns true on success, false on failure.

    Discussion

    Not for general use. Use the static instance creation method withData(OSData *, unsigned int, unsigned int) instead.

    The new OSData object will grow as needed to accommodate more bytes (unlike CFMutableData, for which a nonzero initial capacity is a hard limit).

    Import Statement

  • Tests the equality of two OSData objects.

    Declaration

    C++

    virtual bool isEqualTo( const OSData *aDataObj) const;

    Parameters

    aDataObj

    The OSData object being compared against the receiver.

    Return Value

    true if the two OSData objects are equivalent, false otherwise.

    Discussion

    Two OSData objects are considered equal if they have same length and if their byte buffers hold the same contents.

    Import Statement

  • Tests the equality of an OSData object to an arbitrary object.

    Declaration

    C++

    virtual bool isEqualTo( const OSMetaClassBase *anObject) const;

    Parameters

    anObject

    The object to be compared against the receiver.

    Return Value

    true if the two objects are equivalent, false otherwise.

    Discussion

    An OSData is considered equal to another object if that object is derived from OSData and contains the equivalent bytes of the same length.

    Import Statement

  • Tests the equality of an OSData object to an OSString.

    Declaration

    C++

    virtual bool isEqualTo( const OSString *aString) const;

    Parameters

    aString

    The string object to be compared against the receiver.

    Return Value

    true if the two objects are equivalent, false otherwise.

    Discussion

    This function compares the bytes of the OSData object against those of the OSString, accounting for the possibility that an OSData might explicitly include a nul character as part of its total length. Thus, for example, an OSData object containing either the bytes <'u', 's', 'b', '\0'> or <'u', 's', 'b'> will compare as equal to the OSString containing "usb".

    Import Statement

  • Tests the equality of an OSData object's contents to a C array of bytes.

    Declaration

    C++

    virtual bool isEqualTo( const void *bytes, unsigned intnumBytes) const;

    Parameters

    bytes

    A pointer to the bytes to compare.

    numBytes

    The number of bytes to compare.

    Return Value

    true if the data buffers are equal over the given length, false otherwise.

    Import Statement

  • Archives the receiver into the provided OSSerialize object.

    Declaration

    C++

    virtual bool serialize( OSSerialize *serializer) const;

    Parameters

    serializer

    The OSSerialize object.

    Return Value

    true if serialization succeeds, false if not.

    Import Statement

  • Sets the storage increment of the array.

    Declaration

    C++

    virtual unsigned int setCapacityIncrement( unsigned increment);

    Return Value

    The original storage increment of the array.

    Discussion

    An OSArray allocates storage for objects in multiples of the capacity increment.

    OSData objects created or initialized to use a shared buffer do not make use of this attribute.

    Import Statement

  • Creates and initializes an instance of OSData with a copy of the provided data buffer.

    Declaration

    C++

    static OSData * withBytes( const void *bytes, unsigned intnumBytes);

    Parameters

    bytes

    The buffer of data to copy.

    numBytes

    The length of bytes.

    Return Value

    An instance of OSData containing a copy of the provided byte array, with a reference count of 1; NULL on failure.

    Discussion

    The new OSData object will grow as needed to accommodate more bytes (unlike CFMutableData, for which a nonzero initial capacity is a hard limit).

    Import Statement

  • Creates and initializes an instance of OSData that shares the provided data buffer.

    Declaration

    C++

    static OSData * withBytesNoCopy( void *bytes, unsigned intnumBytes);

    Parameters

    bytes

    The buffer of data to represent.

    numBytes

    The length of bytes.

    Return Value

    A instance of OSData that shares the provided byte array, with a reference count of 1; NULL<coe> on failure.

    Discussion

    An OSData object created with this function does not claim ownership of the data buffer, but shares it with the caller. When the caller determines that the OSData object has actually been freed, it can safely dispose of the data buffer. Conversely, if it frees the shared data buffer, it must not attempt to use the OSData object and should release it.

    An OSData object created with shared external data cannot append bytes, but you can get the byte pointer and modify bytes within the shared buffer.

    Import Statement

  • Creates and initializes an empty instance of OSData.

    Declaration

    C++

    static OSData * withCapacity( unsigned intcapacity);

    Parameters

    capacity

    The initial capacity of the OSData object in bytes.

    Return Value

    An instance of OSData with a reference count of 1; NULL on failure.

    Discussion

    capacity may be zero. The OSData object will allocate a buffer internally when necessary, and will grow as needed to accommodate more bytes (unlike CFMutableData, for which a nonzero initial capacity is a hard limit).

    Import Statement

  • Creates and initializes an instance of OSData with contents copied from another OSData object.

    Declaration

    C++

    static OSData * withData( const OSData *inData);

    Parameters

    inData

    An OSData object that provides the initial data.

    Return Value

    An instance of OSData containing a copy of the data in inData, with a reference count of 1; NULL on failure.

    Discussion

    The new OSData object will grow as needed to accommodate more bytes (unlike CFMutableData, for which a nonzero initial capacity is a hard limit).

    Import Statement

  • Creates and initializes an instance of OSData with contents copied from a range within another OSData object.

    Declaration

    C++

    static OSData * withData( const OSData *inData, unsigned intstart, unsigned intnumBytes);

    Parameters

    inData

    An OSData object that provides the initial data.

    start

    The starting index from which bytes will be copied.

    numBytes

    The number of bytes to be copied from start.

    Return Value

    An instance of OSData containing a copy of the specified data range from inData, with a reference count of 1; NULL on failure.

    Discussion

    The new OSData object will grow as needed to accommodate more bytes (unlike CFMutableData, for which a nonzero initial capacity is a hard limit).

    Import Statement