libkern/c++/OSData.h Kernel.framework

@function withCapacity @abstract Creates and initializes an empty instance of OSData. @param capacity The initial capacity of the OSData object in bytes. @result An instance of OSData with a reference count of 1; <code>NULL</code> on failure. @discussion <code>capacity</code> may be zero. The OSData object will allocate a buffer internally when necessary, and will grow as needed to accommodate more bytes (<i>unlike</i> @link //apple_ref/doc/uid/20001498 CFMutableData@/link, for which a nonzero initial capacity is a hard limit).

@function withBytes @abstract Creates and initializes an instance of OSData with a copy of the provided data buffer. @param bytes The buffer of data to copy. @param numBytes The length of <code>bytes</code>. @result An instance of OSData containing a copy of the provided byte array, with a reference count of 1; <code>NULL</code> on failure. @discussion The new OSData object will grow as needed to accommodate more bytes (<i>unlike</i> @link //apple_ref/doc/uid/20001498 CFMutableData@/link, for which a nonzero initial capacity is a hard limit).

@function withBytesNoCopy @abstract Creates and initializes an instance of OSData that shares the provided data buffer. @param bytes The buffer of data to represent. @param numBytes The length of <code>bytes</code>. @result A instance of OSData that shares the provided byte array, with a reference count of 1; <code>NULL</code> 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.

@function withData @abstract Creates and initializes an instance of OSData with contents copied from another OSData object. @param inData An OSData object that provides the initial data. @result An instance of OSData containing a copy of the data in <code>inData</code>, with a reference count of 1; <code>NULL</code> on failure. @discussion The new OSData object will grow as needed to accommodate more bytes (<i>unlike</i> @link //apple_ref/doc/uid/20001498 CFMutableData@/link, for which a nonzero initial capacity is a hard limit).

static OSPtr<OSData> withData(
	const OSData * inData,
	unsigned int start,
	unsigned int numBytes
)

@function withData @abstract Creates and initializes an instance of OSData with contents copied from a range within another OSData object. @param inData An OSData object that provides the initial data. @param start The starting index from which bytes will be copied. @param numBytes The number of bytes to be copied from <code>start</code>. @result An instance of OSData containing a copy of the specified data range from <code>inData</code>, with a reference count of 1; <code>NULL</code> on failure. @discussion The new OSData object will grow as needed to accommodate more bytes (<i>unlike</i> @link //apple_ref/doc/uid/20001498 CFMutableData@/link, for which a nonzero initial capacity is a hard limit).

@function initWithCapacity @abstract Initializes an instance of OSData. @param capacity The initial capacity of the OSData object in bytes. @result <code>true</code> on success, <code>false</code> on failure. @discussion Not for general use. Use the static instance creation method <code>@link //apple_ref/cpp/clm/OSData/withCapacity/staticOSData*\/(unsignedint) withCapacity@/link</code> instead. <code>capacity</code> may be zero. The OSData object will allocate a buffer internally when necessary, and will grow as needed to accommodate more bytes (<i>unlike</i> @link //apple_ref/doc/uid/20001498 CFMutableData@/link, for which a nonzero initial capacity is a hard limit).

@function initWithBytes @abstract Initializes an instance of OSData with a copy of the provided data buffer. @param bytes The buffer of data to copy. @param numBytes The length of <code>bytes</code>. @result <code>true</code> on success, <code>false</code> on failure. @discussion Not for general use. Use the static instance creation method <code>@link withBytes withBytes@/link</code> instead. The new OSData object will grow as needed to accommodate more bytes (<i>unlike</i> @link //apple_ref/doc/uid/20001498 CFMutableData@/link, for which a nonzero initial capacity is a hard limit).

@function initWithBytesNoCopy @abstract Initializes an instance of OSData to share the provided data buffer. @param bytes The buffer of data to represent. @param numBytes The length of <code>bytes</code>. @result <code>true</code> on success, <code>false</code> on failure. @discussion Not for general use. Use the static instance creation method <code>@link withBytesNoCopy withBytesNoCopy@/link</code> 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.

@function initWithData @abstract Creates and initializes an instance of OSData with contents copied from another OSData object. @param inData An OSData object that provides the initial data. @result <code>true</code> on success, <code>false</code> on failure. @discussion Not for general use. Use the static instance creation method <code>@link //apple_ref/cpp/clm/OSData/withData/staticOSData*\/(constOSData*) withData(OSData *)@/link</code> instead. The new OSData object will grow as needed to accommodate more bytes (<i>unlike</i> @link //apple_ref/doc/uid/20001498 CFMutableData@/link, for which a nonzero initial capacity is a hard limit).

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

@function initWithData @abstract Initializes an instance of OSData with contents copied from a range within another OSData object. @param inData An OSData object that provides the initial data. @param start The starting index from which bytes will be copied. @param numBytes The number of bytes to be copied from <code>start</code>. @result Returns <code>true</code> on success, <code>false</code> on failure. @discussion Not for general use. Use the static instance creation method <code>@link //apple_ref/cpp/clm/OSData/withData/staticOSData*\/(constOSData*,unsignedint,unsignedint) withData(OSData *, unsigned int, unsigned int)@/link</code> instead. The new OSData object will grow as needed to accommodate more bytes (<i>unlike</i> @link //apple_ref/doc/uid/20001498 CFMutableData@/link, for which a nonzero initial capacity is a hard limit).

APPLE_KEXT_OVERRIDE
virtual void free()

@function free @abstract Deallocates or releases any resources used by the OSData instance. @discussion This function should not be called directly; use <code>@link //apple_ref/cpp/instm/OSObject/release/virtualvoid/() release@/link</code> instead.

@function getLength @abstract Returns the number of bytes in or referenced by the OSData object. @result The number of bytes in or referenced by the OSData object.

@function getCapacity @abstract Returns the total number of bytes the OSData can store without reallocating. @result The total number bytes the OSData can store without reallocating. @discussion OSData objects grow when full to accommodate additional bytes. See <code>@link //apple_ref/cpp/instm/OSData/getCapacityIncrement/virtualunsignedint/() getCapacityIncrement@/link</code> and <code>@link //apple_ref/cpp/instm/OSData/ensureCapacity/virtualunsignedint/(unsignedint) ensureCapacity@/link</code>. OSData objects created or initialized to use a shared buffer do not make use of this attribute, and return -1 from this function.

@function getCapacityIncrement @abstract Returns the storage increment of the OSData object. @result 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.

@function setCapacityIncrement @abstract Sets the storage increment of the array. @result 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.

@function ensureCapacity @abstract Ensures the array has enough space to store the requested number of bytes. @param newCapacity The total number of bytes the OSData object should be able to store. @result 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 <code>newCapacity</code> bytes. If <code>newCapacity</code> 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.

@function appendBytes @abstract Appends a buffer of bytes to the OSData object's internal data buffer. @param bytes A pointer to the data to append. If <code>bytes</code> is <code>NULL</code> then a zero-filled buffer of length <code>numBytes</code> is appended. @param numBytes The number of bytes from <code>bytes</code> to append. @result <code>true</code> if the new data was successfully added, <code>false</code> 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.

@function appendBytes @abstract Appends the data contained in another OSData object. @param aDataObj The OSData object whose contents will be appended. @result <code>true</code> if the new data was successfully added, <code>false</code> 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.

@function isEqualTo @abstract Tests the equality of two OSData objects. @param aDataObj The OSData object being compared against the receiver. @result <code>true</code> if the two OSData objects are equivalent, <code>false</code> otherwise. @discussion Two OSData objects are considered equal if they have same length and if their byte buffers hold the same contents.

@function isEqualTo @abstract Tests the equality of an OSData object's contents to a C array of bytes. @param bytes A pointer to the bytes to compare. @param numBytes The number of bytes to compare. @result <code>true</code> if the data buffers are equal over the given length, <code>false</code> otherwise.

APPLE_KEXT_OVERRIDE
virtual bool isEqualTo(const OSMetaClassBase * anObject) const

@function isEqualTo @abstract Tests the equality of an OSData object to an arbitrary object. @param anObject The object to be compared against the receiver. @result <code>true</code> if the two objects are equivalent, <code>false</code> 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.

@function isEqualTo @abstract Tests the equality of an OSData object to an OSString. @param aString The string object to be compared against the receiver. @result <code>true</code> if the two objects are equivalent, <code>false</code> 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".

APPLE_KEXT_OVERRIDE
virtual bool serialize(OSSerialize * serializer) const

@function serialize @abstract Archives the receiver into the provided @link //apple_ref/doc/class/IORegistryEntry OSSerialize@/link object. @param serializer The OSSerialize object. @result <code>true</code> if serialization succeeds, <code>false</code> if not.

@function appendByte @abstract Appends a single byte value to the OSData object's internal data buffer a specified number of times. @param byte The byte value to append. @param numBytes The number of copies of <code>byte</code> to append. @result <code>true</code> if the new data was successfully added, <code>false</code> 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.