OSData

Overview

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

Discussion

OSData represents an array of bytes as a Libkern C++ object. OSData objects are mutable: You can add bytes to them and overwrite portions of the byte array.

Use Restrictions

With very few exceptions in the I/O Kit, all Libkern-based C++ classes, functions, and macros are unsafe to use in a primary interrupt context. Consult the I/O Kit documentation related to primary interrupts for more information.

OSData provides no concurrency protection; it's up to the usage context to provide any protection necessary. Some portions of the I/O Kit, such as IORegistryEntry, handle synchronization via defined member functions for setting properties.

Functions

appendByte

Appends a single byte value to the OSData object's internal data buffer a specified number of times.

appendBytes(const OSData *)

Appends the data contained in another OSData object.

appendBytes(const void *, unsigned int)

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

ensureCapacity

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

free

Deallocates or releases any resources used by the OSDictionary instance.

getBytesNoCopy()

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

getBytesNoCopy(unsigned int, unsigned int)

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

getCapacity

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

getCapacityIncrement

Returns the storage increment of the OSData object.

getLength

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

initWithBytes

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

initWithBytesNoCopy

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

initWithCapacity

Initializes an instance of OSData.

initWithData(const OSData *)

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

initWithData(const OSData *, unsigned int, unsigned int)

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

isEqualTo(const OSData *)

Tests the equality of two OSData objects.

isEqualTo(const OSMetaClassBase *)

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

isEqualTo(const OSString *)

Tests the equality of an OSData object to an OSString.

isEqualTo(const void *, unsigned int)

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

serialize

Archives the receiver into the provided OSSerialize object.

setCapacityIncrement

Sets the storage increment of the array.

withBytes

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

withBytesNoCopy

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

withCapacity

Creates and initializes an empty instance of OSData.

withData(const OSData *)

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

withData(const OSData *, unsigned int, unsigned int)

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

Appends a single byte value to the OSData object's internal data buffer a specified number of times.

public

virtual bool appendByte( 
    unsigned char byte, 
    unsigned int numBytes); 

Parameters

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.

Appends the data contained in another OSData object.

public

virtual bool appendBytes(
    const OSData * aDataObj); 

Parameters

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.

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

public

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

Parameters

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.

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

public

virtual unsigned int ensureCapacity(
    unsigned int newCapacity); 

Parameters

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.

Deallocates or releases any resources used by the OSDictionary instance.

public

virtual void free(); 

Discussion

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

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

public

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.

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

public

virtual const void * getBytesNoCopy( unsigned int start, unsigned int numBytes) const; 

Parameters

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.

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

public

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.

Returns the storage increment of the OSData object.

public

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.

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

public

virtual unsigned int getLength() const; 

Return Value

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

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

public

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

Parameters

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

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

public

virtual bool initWithBytesNoCopy( 
    void *bytes, 
    unsigned int numBytes); 

Parameters

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.

Initializes an instance of OSData.

public

virtual bool initWithCapacity(
    unsigned int capacity); 

Parameters

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

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

public

virtual bool initWithData(
    const OSData * inData); 

Parameters

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

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

public

virtual bool initWithData( 
    const OSData * inData, 
    unsigned int start, 
    unsigned int numBytes); 

Parameters

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

Tests the equality of two OSData objects.

public

virtual bool isEqualTo(
    const OSData * aDataObj) const; 

Parameters

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.

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

public

virtual bool isEqualTo(
    const OSMetaClassBase * anObject) const; 

Parameters

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.

Tests the equality of an OSData object to an OSString.

public

virtual bool isEqualTo(
    const OSString * aString) const; 

Parameters

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 or will compare as equal to the OSString containing "usb".

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

public

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

Parameters

Return Value

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

Archives the receiver into the provided OSSerialize object.

public

virtual bool serialize(
    OSSerialize *serializer) const; 

Parameters

Return Value

true if serialization succeeds, false if not.

Sets the storage increment of the array.

public

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.

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

public

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

Parameters

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

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

public

static OSData * withBytesNoCopy( 
    void *bytes, 
    unsigned int numBytes); 

Parameters

Return Value

A instance of OSData that shares the provided byte array, with a reference count of 1; NULL 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.

Creates and initializes an empty instance of OSData.

public

static OSData * withCapacity(
    unsigned int capacity); 

Parameters

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

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

public

static OSData * withData(
    const OSData * inData); 

Parameters

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

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

public

static OSData * withData( 
    const OSData * inData, 
    unsigned int start, 
    unsigned int numBytes); 

Parameters

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

Last Updated: 2009-10-14