OSData

Inherits from
OSObject
Availability
Available in OS X v10.0 and later.
Declared in
OSData.h

Overview

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

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.

Tasks

Miscellaneous

Instance Methods

appendByte

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

virtual bool appendByte( unsigned char byte, unsigned int numBytes);
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.

appendBytes(const OSData *)

Appends the data contained in another OSData object.

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.

appendBytes(const void *, unsigned int)

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

virtual bool appendBytes( const void *bytes, unsigned int numBytes);
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.

ensureCapacity

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

virtual unsigned int ensureCapacity( unsigned int newCapacity);
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.

free

Deallocates or releases any resources used by the OSDictionary instance.

virtual void free();
Discussion

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

getBytesNoCopy()

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

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.

getBytesNoCopy(unsigned int, unsigned int)

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

virtual const void * getBytesNoCopy( unsigned int start, unsigned int numBytes) 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.

getCapacity

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

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.

getCapacityIncrement

Returns the storage increment of the OSData object.

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.

getLength

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

virtual unsigned int getLength() const;
Return Value

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.

virtual bool initWithBytes( const void *bytes, unsigned int numBytes);
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).

initWithBytesNoCopy

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

virtual bool initWithBytesNoCopy( void *bytes, unsigned int numBytes);
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.

initWithCapacity

Initializes an instance of OSData.

virtual bool initWithCapacity( unsigned int capacity);
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).

initWithData(const OSData *)

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

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

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

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

virtual bool initWithData( const OSData *inData, unsigned int start, unsigned int numBytes);
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).

isEqualTo(const OSData *)

Tests the equality of two OSData objects.

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.

isEqualTo(const OSMetaClassBase *)

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

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.

isEqualTo(const OSString *)

Tests the equality of an OSData object to an OSString.

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

isEqualTo(const void *, unsigned int)

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

virtual bool isEqualTo( const void *bytes, unsigned int numBytes) 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.

serialize

Archives the receiver into the provided OSSerialize object.

virtual bool serialize( OSSerialize *serializer) const;
Parameters
serializer

The OSSerialize object.

Return Value

true if serialization succeeds, false if not.

setCapacityIncrement

Sets the storage increment of the array.

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.

withBytes

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

static OSData * withBytes( const void *bytes, unsigned int numBytes);
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).

withBytesNoCopy

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

static OSData * withBytesNoCopy( void *bytes, unsigned int numBytes);
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.

withCapacity

Creates and initializes an empty instance of OSData.

static OSData * withCapacity( unsigned int capacity);
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).

withData(const OSData *)

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

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

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

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

static OSData * withData( const OSData *inData, unsigned int start, unsigned int numBytes);
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).