OSData |
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.
Appends a single byte value to the OSData object's internal data buffer a specified number of times.
Appends the data contained in another OSData object.
Appends a buffer of bytes to the OSData object's internal data buffer.
Ensures the array has enough space to store the requested number of bytes.
Deallocates or releases any resources used by the OSDictionary instance.
Returns a pointer to the OSData object's internal data buffer.
Returns a pointer into the OSData object's internal data buffer with a given offset and length.
Returns the total number of bytes the OSData can store without reallocating.
Returns the storage increment of the OSData object.
Returns the number of bytes in or referenced by the OSData object.
Initializes an instance of OSData with a copy of the provided data buffer.
Initializes an instance of OSData to share the provided data buffer.
Initializes an instance of OSData.
Creates and initializes an instance of OSData with contents copied from another OSData object.
Initializes an instance of OSData with contents copied from a range within another OSData object.
Tests the equality of two OSData objects.
Tests the equality of an OSData object to an arbitrary object.
Tests the equality of an OSData object to an OSString.
Tests the equality of an OSData object's contents to a C array of bytes.
Archives the receiver into the provided OSSerialize object.
Sets the storage increment of the array.
Creates and initializes an instance of OSData with a copy of the provided data buffer.
Creates and initializes an instance of OSData that shares the provided data buffer.
Creates and initializes an empty instance of OSData.
Creates and initializes an instance of OSData with contents copied from another OSData object.
Creates and initializes an instance of OSData with contents copied from a range within another OSData object.
appendByte |
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);
byte
The byte value to append.
numBytes
The number of copies of byte
to append.
true
if the new data was successfully added,
false
if not.
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.
public
virtual bool appendBytes( const OSData *aDataObj);
aDataObj
The OSData object whose contents will be appended.
true
if the new data was successfully added,
false
on failure.
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.
public
virtual bool appendBytes( const void *bytes, unsigned int numBytes);
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.
true
if the new data was successfully added,
false
on failure.
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.
public
virtual unsigned int ensureCapacity( unsigned int newCapacity);
newCapacity
The total number of bytes the OSData object should be able to store.
Returns the new capacity of the OSData object, which may be different from the number requested (if smaller, reallocation of storage failed).
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.
This function should not be called directly;
use
release
instead.
getBytesNoCopy() |
Returns a pointer to the OSData object's internal data buffer.
public
virtual const void * getBytesNoCopy() const;
A pointer to the OSData object's internal data buffer.
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.
public
virtual const void * getBytesNoCopy( unsigned int start, unsigned int numBytes) const;
start
The offset from the base of the internal data buffer.
numBytes
The length of the window.
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.
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.
public
virtual unsigned int getCapacity() const;
The total number bytes the OSData can store without reallocating.
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.
public
virtual unsigned int getCapacityIncrement() const;
The storage increment of the OSData object.
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.
public
virtual unsigned int getLength() const;
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.
public
virtual bool initWithBytes( const void *bytes, unsigned int numBytes);
bytes
The buffer of data to copy.
numBytes
The length of bytes
.
true
on success, false
on failure.
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.
public
virtual bool initWithBytesNoCopy( void *bytes, unsigned int numBytes);
bytes
The buffer of data to represent.
numBytes
The length of bytes
.
true
on success, false
on failure.
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.
public
virtual bool initWithCapacity( unsigned int capacity);
capacity
The initial capacity of the OSData object in bytes.
true
on success, false
on failure.
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.
public
virtual bool initWithData( const OSData *inData);
inData
An OSData object that provides the initial data.
true
on success, false
on failure.
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.
public
virtual bool initWithData( const OSData *inData, unsigned int start, unsigned int numBytes);
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
.
Returns true
on success, false
on failure.
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.
public
virtual bool isEqualTo( const OSData *aDataObj) const;
aDataObj
The OSData object being compared against the receiver.
true
if the two OSData objects are equivalent,
false
otherwise.
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.
public
virtual bool isEqualTo( const OSMetaClassBase *anObject) const;
anObject
The object to be compared against the receiver.
true
if the two objects are equivalent,
false
otherwise.
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.
public
virtual bool isEqualTo( const OSString *aString) const;
aString
The string object to be compared against the receiver.
true
if the two objects are equivalent,
false
otherwise.
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".
isEqualTo(const void *, unsigned int) |
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;
bytes
A pointer to the bytes to compare.
numBytes
The number of bytes to compare.
true
if the data buffers are equal
over the given length,
false
otherwise.
serialize |
Archives the receiver into the provided OSSerialize object.
public
virtual bool serialize( OSSerialize *serializer) const;
serializer
The OSSerialize object.
true
if serialization succeeds, false
if not.
setCapacityIncrement |
Sets the storage increment of the array.
public
virtual unsigned int setCapacityIncrement( unsigned increment);
The original storage increment of the array.
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.
bytes
The buffer of data to copy.
numBytes
The length of bytes
.
An instance of OSData containing a copy of the provided byte array,
with a reference count of 1;
NULL
on failure.
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.
bytes
The buffer of data to represent.
numBytes
The length of bytes
.
A instance of OSData that shares the provided byte array,
with a reference count of 1;
NULL on failure.
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.
public
static OSData * withCapacity( unsigned int capacity);
capacity
The initial capacity of the OSData object in bytes.
An instance of OSData with a reference count of 1;
NULL
on failure.
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.
inData
An OSData object that provides the initial data.
An instance of OSData containing a copy of the data in inData
,
with a reference count of 1;
NULL
on failure.
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.
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
.
An instance of OSData containing a copy
of the specified data range from inData
,
with a reference count of 1;
NULL
on failure.
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: 2010-07-29