OSArray.h

OSArray

Member Functions

ensureCapacity

Abstract: A member function which will expand the size of the collection to a given storage capacity.

public:

virtual unsigned int ensureCapacity(unsigned int newCapacity);

Parameters

Name Description

newCapacity The new capacity for the array.

Name	Description
`newCapacity`	The new capacity for the array.

Result: Returns the new capacity of the array or the previous capacity upon error.

flushCollection

Abstract: A member function which removes all items within the array.

public:

virtual void flushCollection();

free

Abstract: Deallocates and releases all resources used by the OSArray instance. Normally, this is not called directly.

public:

virtual void free();

This function should not be called directly, use release() instead.

getCapacity

Abstract: A member function which returns the storage capacity of the OSArray object.

public:

virtual unsigned int getCapacity() const;

Result: Returns the storage capacity of the OSArray object.

getCapacityIncrement

Abstract: A member function which returns the size by which the array will grow.

public:

virtual unsigned int getCapacityIncrement() const;

Result: Returns the size by which the array will grow.

getCount

Abstract: A member function which returns the number of references contained within the OSArray object.

public:

virtual unsigned int getCount() const;

Result: Returns the number of items within the OSArray object.

getObject

Abstract: A member function wich returns a reference to an object located within the array at a given index. The caller should not release the returned object.

public:

virtual OSObject *getObject(unsigned int index) const;

Parameters

Name Description

index The index into the array from which the reference to an object is taken.

Name	Description
`index`	The index into the array from which the reference to an object is taken.

Result: Returns a reference to an object or 0 if the index is beyond the bounds of the array.

initWithArray

Abstract: A member function which initializes an instance of OSArray and populates it with the contents of the supplied OSArray object.

public:

virtual bool initWithArray(const OSArray *anArray,
 unsigned int theCapacity = 0);

Parameters

Name Description

anArray An instance of OSArray containing the references to objects which will be copied to the new instances of OSArray.

capacity The initial capacity of the new instance of OSArray. If 0, the capacity will be set to the number of elements in the array, else the capacity must be greater than or equal to the number of elements in the array.

Name	Description
`anArray`	An instance of OSArray containing the references to objects which will be copied to the new instances of OSArray.
`capacity`	The initial capacity of the new instance of OSArray. If 0, the capacity will be set to the number of elements in the array, else the capacity must be greater than or equal to the number of elements in the array.

Result: Returns a true if initialization succeeded or false if not.

initWithCapacity

Abstract: A member function which initializes an instance of OSArray.

public:

virtual bool initWithCapacity(unsigned int capacity);

Parameters

Name Description

capacity The initial capacity of the new instance of OSArray.

Name	Description
`capacity`	The initial capacity of the new instance of OSArray.

Result: Returns a true if initialization succeeded or false if not.

Abstract: A member function which initializes an instance of OSArray and populates it with the given list of objects. #param objects A static array containing references to OSObject derived objects.

public:

virtual bool initWithObjects(OSObject *objects[],
 unsigned int count,
 unsigned int capacity = 0);

Parameters

Name Description

count The number of objects to added to the array.

capacity The initial capacity of the new instance of OSArray. If 0, the capacity will be set to the same value as the 'count' parameter, else capacity must be greater than or equal to the value of 'count'.

Name	Description
`count`	The number of objects to added to the array.
`capacity`	The initial capacity of the new instance of OSArray. If 0, the capacity will be set to the same value as the 'count' parameter, else capacity must be greater than or equal to the value of 'count'.

Result: Returns a true if initialization succeeded or false if not.

isEqualTo

Abstract: A member function which tests the equality of two OSArray objects.

public:

virtual bool isEqualTo(OSArray *anArray) const;

Parameters

Name Description

anArray The array object being compared against the receiver.

Name	Description
`anArray`	The array object being compared against the receiver.

Result: Returns true if the two arrays are equivalent or false otherwise.

isEqualTo

Abstract: A member function which compares the equality of the array to an arbitrary object.

public:

virtual bool isEqualTo(const OSObject *anObject) const;

Parameters

Name Description

anObject The object to be compared against the receiver.

Name	Description
`anObject`	The object to be compared against the receiver.

Result: Returns true if the two objects are equivalent, that is they are either the same object or they are both arrays containing the same or equivalent objects, or false otherwise.

lastObject

Abstract: A member function which returns a reference to the last object in the array. The caller should not release the returned object.

public:

virtual OSObject *lastObject() const;

Result: Returns a reference to the last object in the array or 0 if the array is empty.

merge

Abstract: A member function which appends the contents of an array onto the receiving array.

public:

virtual bool merge(const OSArray *otherArray);

Parameters

Name Description

otherArray The array whose contents will be appended to the reveiving array.

Name	Description
`otherArray`	The array whose contents will be appended to the reveiving array.

Result: Returns true when merging was successful, false otherwise.

removeObject

Abstract: A member function which removes an object from the array.

public:

virtual void removeObject(unsigned int index);

This function removes an object from the array which is located at a given index. Once removed the contents of the array will shift to fill in the vacated spot. The removed object is automatically released.

Parameters

Name Description

index The index of the object to be removed.

Name	Description
`index`	The index of the object to be removed.

replaceObject

Abstract: A member function which will replace an object in an array at a given index. The original object will be released and the new object will be retained.

public:

virtual void replaceObject(unsigned int index, OSObject *anObject);

Parameters

Name Description

index The index into the array at which the new object will be placed.

anObject The object to be placed into the array.

Name	Description
`index`	The index into the array at which the new object will be placed.
`anObject`	The object to be placed into the array.

serialize

Abstract: A member function which archives the receiver.

public:

virtual bool serialize(OSSerialize *s) const;

Parameters

Name Description

s The OSSerialize object.

Name	Description
`s`	The OSSerialize object.

Result: Returns true if serialization was successful, false if not.

setCapacityIncrement

Abstract: A member function which sets the growth size of the array.

public:

virtual unsigned int setCapacityIncrement(unsigned increment);

Result: Returns the new growth size.

setObject

Abstract: A member function which appends an object onto the end of the array.

public:

virtual bool setObject(OSObject *anObject);

Parameters

Name Description

anObject The object to add to the OSArray instance. The object will be retained automatically.

Name	Description
`anObject`	The object to add to the OSArray instance. The object will be retained automatically.

Result: Returns a true if the addition of 'anObject' was successful, false if not.

setObject

Abstract: A member function which inserts an object into the array at a particular index.

public:

virtual bool setObject(unsigned int index, OSObject *anObject);

Parameters

Name Description

index The index in the array to insert the object.

anObject The object to add to the OSArray instance. The object will be retained automatically.

Name	Description
`index`	The index in the array to insert the object.
`anObject`	The object to add to the OSArray instance. The object will be retained automatically.

Result: Returns true if the addition of 'anObject' was successful, false if not.

withArray

Abstract: A static constructor function to create and initialize an instance of OSArray of a given capacity and populate it with the contents of the supplied OSArray object.

public:

static OSArray *withArray(const OSArray *array,
 unsigned int capacity = 0);

Parameters

Name Description

array An instance of OSArray from which the new instance will aquire its contents.

capacity The capacity of the new OSArray. If 0, the capacity will be set to the number of elements in the array, else the capacity must be greater than or equal to the number of elements in the array.

Name	Description
`array`	An instance of OSArray from which the new instance will aquire its contents.
`capacity`	The capacity of the new OSArray. If 0, the capacity will be set to the number of elements in the array, else the capacity must be greater than or equal to the number of elements in the array.

Result: Returns a reference to an new instance of OSArray or 0 if an error occurred.

withCapacity

Abstract: A static constructor function to create and initialize a new instance of OSArray with a given capacity.

public:

static OSArray *withCapacity(unsigned int capacity);

Parameters

Name Description

capacity The initial capacity (number of refernces) of the OSArray instance.

Name	Description
`capacity`	The initial capacity (number of refernces) of the OSArray instance.

Result: Returns a reference to an instance of OSArray or 0 if an error occurred.

withObjects

Abstract: A static constructor function to create and initialize a new instance of OSArray an populates it with a list of objects provided.

public:

static OSArray *withObjects(OSObject *objects[],
 unsigned int count,
 unsigned int capacity = 0);

Parameters

Name Description

objects A static array of references to OSObject derived objects.

count The number of objects provided.

capacity The initial storage size of the OSArray instance. If 0, the capacity will be set to the size of count, else the capacity must be greater than or equal to count.

Name	Description
`objects`	A static array of references to OSObject derived objects.
`count`	The number of objects provided.
`capacity`	The initial storage size of the OSArray instance. If 0, the capacity will be set to the size of count, else the capacity must be greater than or equal to count.

Result: Returns a reference to an new instance of OSArray or 0 if an error occurred.

OSAtomic.h

Functions

OSAddAtomic

Abstract: 32-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern SInt32 OSAddAtomic(SInt32 amount, SInt32 * address);

The OSAddAtomic function adds the specified amount to the value at the specified address and returns the result.

Parameters

Name Description

amount The amount to add.

address The 4-byte aligned address of the value to update atomically.

Name	Description
`amount`	The amount to add.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the addition.

OSAddAtomic16

Abstract: 16-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern SInt16 OSAddAtomic16(SInt32 amount, SInt16 * address);

The OSAddAtomic16 function adds the specified amount to the value at the specified address and returns the result.

Parameters

Name Description

amount The amount to add.

address The 4-byte aligned address of the value to update atomically.

Name	Description
`amount`	The amount to add.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the addition.

OSAddAtomic8

Abstract: 8-bit add operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern SInt8 OSAddAtomic8(SInt32 amount, SInt8 * address);

The OSAddAtomic8 function adds the specified amount to the value at the specified address and returns the result.

Parameters

Name Description

amount The amount to add.

address The 4-byte aligned address of the value to update atomically.

Name	Description
`amount`	The amount to add.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the addition.

OSBitAndAtomic

Abstract: 32-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern UInt32 OSBitAndAtomic(UInt32 mask, UInt32 * address);

The OSBitAndAtomic function logically ands the bits of the specified mask into the value at the specified address and returns the result.

Parameters

Name Description

mask The mask to logically and with the value.

address The 4-byte aligned address of the value to update atomically.

Name	Description
`mask`	The mask to logically and with the value.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the logical and.

OSBitAndAtomic16

Abstract: 16-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern UInt16 OSBitAndAtomic16(UInt32 mask, UInt16 * address);

The OSBitAndAtomic16 function logically ands the bits of the specified mask into the value at the specified address and returns the result.

Parameters

Name Description

mask The mask to logically and with the value.

address The 4-byte aligned address of the value to update atomically.

Name	Description
`mask`	The mask to logically and with the value.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the logical and.

OSBitAndAtomic8

Abstract: 8-bit logical and operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern UInt8 OSBitAndAtomic8(UInt32 mask, UInt8 * address);

The OSBitAndAtomic8 function logically ands the bits of the specified mask into the value at the specified address and returns the result.

Parameters

Name Description

mask The mask to logically and with the value.

address The 4-byte aligned address of the value to update atomically.

Name	Description
`mask`	The mask to logically and with the value.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the logical and.

OSBitOrAtomic

Abstract: 32-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern UInt32 OSBitOrAtomic(UInt32 mask, UInt32 * address);

The OSBitOrAtomic function logically ors the bits of the specified mask into the value at the specified address and returns the result.

Parameters

Name Description

mask The mask to logically or with the value.

address The 4-byte aligned address of the value to update atomically.

Name	Description
`mask`	The mask to logically or with the value.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the logical or.

OSBitOrAtomic16

Abstract: 16-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern UInt16 OSBitOrAtomic16(UInt32 mask, UInt16 * address);

The OSBitOrAtomic16 function logically ors the bits of the specified mask into the value at the specified address and returns the result.

Parameters

Name Description

mask The mask to logically or with the value.

address The 4-byte aligned address of the value to update atomically.

Name	Description
`mask`	The mask to logically or with the value.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the logical or.

OSBitOrAtomic8

Abstract: 8-bit logical or operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern UInt8 OSBitOrAtomic8(UInt32 mask, UInt8 * address);

The OSBitOrAtomic8 function logically ors the bits of the specified mask into the value at the specified address and returns the result.

Parameters

Name Description

mask The mask to logically or with the value.

address The 4-byte aligned address of the value to update atomically.

Name	Description
`mask`	The mask to logically or with the value.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the logical or.

OSBitXorAtomic

Abstract: 32-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern UInt32 OSBitXorAtomic(UInt32 mask, UInt32 * address);

The OSBitXorAtomic function logically xors the bits of the specified mask into the value at the specified address and returns the result.

Parameters

Name Description

mask The mask to logically or with the value.

address The 4-byte aligned address of the value to update atomically.

Name	Description
`mask`	The mask to logically or with the value.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the logical xor.

OSBitXorAtomic16

Abstract: 16-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern UInt16 OSBitXorAtomic16(UInt32 mask, UInt16 * address);

The OSBitXorAtomic16 function logically xors the bits of the specified mask into the value at the specified address and returns the result.

Parameters

Name Description

mask The mask to logically or with the value.

address The 4-byte aligned address of the value to update atomically.

Name	Description
`mask`	The mask to logically or with the value.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the logical xor.

OSBitXorAtomic8

Abstract: 8-bit logical xor operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern UInt8 OSBitXorAtomic8(UInt32 mask, UInt8 * address);

The OSBitXorAtomic8 function logically xors the bits of the specified mask into the value at the specified address and returns the result.

Parameters

Name Description

mask The mask to logically or with the value.

address The 4-byte aligned address of the value to update atomically.

Name	Description
`mask`	The mask to logically or with the value.
`address`	The 4-byte aligned address of the value to update atomically.

Result: The result of the logical xor.

OSCompareAndSwap

Abstract: Compare and swap operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern Boolean OSCompareAndSwap( UInt32 oldValue, UInt32 newValue, UInt32 * address );

The OSCompareAndSwap function compares the value at the specified address with oldVal. The value of newValue is written to the address only if oldValue and the value at the address are equal. OSCompareAndSwap returns true if newValue is written to the address; otherwise, it returns false. A false return value does not imply that oldValue and the value at the specified address are not equal; it only implies that OSCompareAndSwap did not write newValue to the address.

Parameters

Name Description

oldValue The value to compare at address.

newValue The value to write to address if oldValue compares true.

address The 4-byte aligned address of the data to update atomically.

Name	Description
`oldValue`	The value to compare at address.
`newValue`	The value to write to address if oldValue compares true.
`address`	The 4-byte aligned address of the data to update atomically.

Result: true if newValue was written to the address.

OSDecrementAtomic

Abstract: 32-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern SInt32 OSDecrementAtomic(SInt32 * address);

The OSDecrementAtomic function decrements the value at the specified address by one and returns the value as it was before the change.

Parameters

Name Description

address The 4-byte aligned address of the value to update atomically.

Name	Description
`address`	The 4-byte aligned address of the value to update atomically.

Result: The value before the decrement.

OSDecrementAtomic16

Abstract: 16-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern SInt16 OSDecrementAtomic16(SInt16 * address);

The OSDecrementAtomic16 function decrements the value at the specified address by one and returns the value as it was before the change.

Parameters

Name Description

address The 4-byte aligned address of the value to update atomically.

Name	Description
`address`	The 4-byte aligned address of the value to update atomically.

Result: The value before the decrement.

OSDecrementAtomic8

Abstract: 8-bit decrement operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern SInt8 OSDecrementAtomic8(SInt8 * address);

The OSDecrementAtomic8 function decrements the value at the specified address by one and returns the value as it was before the change.

Parameters

Name Description

address The 4-byte aligned address of the value to update atomically.

Name	Description
`address`	The 4-byte aligned address of the value to update atomically.

Result: The value before the decrement.

OSDequeueAtomic

Abstract: Singly linked list element head removal, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern void * OSDequeueAtomic(void ** listHead,
 SInt32 elementNextFieldOffset);

The OSDequeueAtomic function removes an element from the head of a single linked list, which is specified with the address of a head pointer, listHead. The element structure has a next field whose offset is specified.

Parameters

Name Description

listHead The address of a head pointer for the list .

elementNextFieldOffset The byte offset into the element where a pointer to the next element in the list is stored.

Name	Description
`listHead`	The address of a head pointer for the list .
`elementNextFieldOffset`	The byte offset into the element where a pointer to the next element in the list is stored.

Result: A removed element, or zero if the list is empty.

OSEnqueueAtomic

Abstract: Singly linked list head insertion, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern void OSEnqueueAtomic(void ** listHead, void * element,
 SInt32 elementNextFieldOffset);

The OSEnqueueAtomic function places an element at the head of a single linked list, which is specified with the address of a head pointer, listHead. The element structure has a next field whose offset is specified.

Parameters

Name Description

listHead The address of a head pointer for the list .

element The list element to insert at the head of the list.

elementNextFieldOffset The byte offset into the element where a pointer to the next element in the list is stored.

Name	Description
`listHead`	The address of a head pointer for the list .
`element`	The list element to insert at the head of the list.
`elementNextFieldOffset`	The byte offset into the element where a pointer to the next element in the list is stored.

OSIncrementAtomic

Abstract: 32-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern SInt32 OSIncrementAtomic(SInt32 * address);

The OSIncrementAtomic function increments the value at the specified address by one and returns the value as it was before the change.

Parameters

Name Description

address The 4-byte aligned address of the value to update atomically.

Name	Description
`address`	The 4-byte aligned address of the value to update atomically.

Result: The value before the increment.

OSIncrementAtomic16

Abstract: 16-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern SInt16 OSIncrementAtomic16(SInt16 * address);

The OSIncrementAtomic16 function increments the value at the specified address by one and returns the value as it was before the change.

Parameters

Name Description

address The 4-byte aligned address of the value to update atomically.

Name	Description
`address`	The 4-byte aligned address of the value to update atomically.

Result: The value before the increment.

OSIncrementAtomic8

Abstract: 8-bit increment operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern SInt8 OSIncrementAtomic8(SInt8 * address);

The OSIncrementAtomic8 function increments the value at the specified address by one and returns the value as it was before the change.

Parameters

Name Description

address The 4-byte aligned address of the value to update atomically.

Name	Description
`address`	The 4-byte aligned address of the value to update atomically.

Result: The value before the increment.

OSSynchronizeIO

Abstract: The OSSynchronizeIO routine ensures orderly load and store operations to noncached memory mapped I/O devices.

static __inline__ void OSSynchronizeIO(void)
{
#if defined(__ppc__)
 __asm__ ("eieio");

The OSSynchronizeIO routine ensures orderly load and store operations to noncached memory mapped I/O devices. It executes the eieio instruction on PowerPC processors.

OSTestAndClear

Abstract: Bit test and clear operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern Boolean OSTestAndClear(UInt32 bit, UInt8 * startAddress);

The OSTestAndClear function clears a single bit in a byte at a specified address. It returns true if the bit was already clear, false otherwise.

Parameters

Name Description

bit The bit number in the range 0 through 7.

address The address of the byte to update atomically.

Name	Description
`bit`	The bit number in the range 0 through 7.
`address`	The address of the byte to update atomically.

Result: true if the bit was already clear, false otherwise.

OSTestAndSet

Abstract: Bit test and set operation, performed atomically with respect to all devices that participate in the coherency architecture of the platform.

extern Boolean OSTestAndSet(UInt32 bit, UInt8 * startAddress);

The OSTestAndSet function sets a single bit in a byte at a specified address. It returns true if the bit was already set, false otherwise.

Parameters

Name Description

bit The bit number in the range 0 through 7.

address The address of the byte to update atomically.

Name	Description
`bit`	The bit number in the range 0 through 7.
`address`	The address of the byte to update atomically.

Result: true if the bit was already set, false otherwise.

OSBoolean.h

OSBoolean

Member Functions

free

Abstract: A member function to release all resources used by the OSBoolean instance.

public:

virtual void free();

This function should not be called directly, use release() instead.

init

Abstract: A member function to initialize an instance of OSBoolean.

public:

virtual bool init(bool value);

Parameters

Name Description

value A boolean value.

Name	Description
`value`	A boolean value.

Result: Returns true if initialization was successful, false otherwise.

isEqualTo

Abstract: A member function to test the equality of two OSBoolean objects.

public:

virtual bool isEqualTo(const OSBoolean *boolean) const;

Parameters

Name Description

boolean An OSBoolean object to be compared against the receiver.

Name	Description
`boolean`	An OSBoolean object to be compared against the receiver.

Result: Returns true if the two objects are equivalent.

isEqualTo

Abstract: A member function to test the equality between an arbitrary OSObject derived object and an OSBoolean object.

public:

virtual bool isEqualTo(const OSObject *obj) const;

Parameters

Name Description

obj An OSObject derived object to be compared against the receiver.

Name	Description
`obj`	An OSObject derived object to be compared against the receiver.

Result: Returns true if the two objects are equivalent.

isFalse

Abstract: A member function to test if the boolean object is false.

public:

virtual bool isFalse() const;

Result: Returns true if the OSBoolean object is false, false otherwise.

isTrue

Abstract: A member function to test if the boolean object is true.

public:

virtual bool isTrue() const;

Result: Returns true if the OSBoolean object is true, false otherwise.

serialize

Abstract: A member function which archives the receiver.

public:

virtual bool serialize(OSSerialize *s) const;

Parameters

Name Description

s The OSSerialize object.

Name	Description
`s`	The OSSerialize object.

Result: Returns true if serialization was successful, false if not.

withBoolean

Abstract: A static constructor function to create and initialize an instance of OSBoolean.

public:

static OSBoolean *withBoolean(bool value);

Parameters

Name Description

value A boolean value.

Name	Description
`value`	A boolean value.

Result: Returns and instance of OSBoolean, or 0 if an error occurred.

OSCollection.h

OSCollection

OSCollectionIterator.h

OSCollectionIterator

Member Functions

free

Abstract: A member function to release and deallocate all resources created or used by the OSCollectionIterator object.

public:

virtual void free();

This function should not be called directly, use release() instead.

getNextObject

Abstract: A member function to get the next object in the collection being iterated.

public:

virtual OSObject *getNextObject();

Result: Returns the next object in the collection or 0 when the end has been reached.

isValid

Abstract: A member function for determining if the collection was modified during iteration.

public:

virtual bool isValid();

reset

Abstract: A member function which resets the iterator to begin the next iteration from the beginning of the collection.

public:

virtual void reset();

withCollection

Abstract: A static constructor function which creates and initialize an intance of OSCollectionIterator for the provided colleciton object.

public:

static OSCollectionIterator *withCollection(OSCollection *inColl);

Parameters

Name Description

inColl The OSCollection derived collection object to be iteratated.

Name	Description
`inColl`	The OSCollection derived collection object to be iteratated.

Result: Returns an new instance of OSCollection or 0 on failure.

withCollection

Abstract: A member function to initialize the intance of OSCollectionIterator with the provided colleciton object.

public:

virtual bool initWithCollection(OSCollection *inColl);

Parameters

Name Description

inColl The OSCollection derived collection object to be iteratated.

Name	Description
`inColl`	The OSCollection derived collection object to be iteratated.

Result: Returns true if the initialization was successful or false on failure.

OSData.h

OSData

Member Functions

appendBytes

Abstract: A member function which appends the data contained in an OSData object to the receiver.

public:

virtual bool appendBytes(const OSData *other);

Parameters

Name Description

other An OSData object.

Name	Description
`other`	An OSData object.

Result: Returns true if appending the new data was successful, false otherwise.

appendBytes

Abstract: A member function which appends a buffer of data onto the end of the object's internal data buffer.

public:

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

Parameters

Name Description

bytes A pointer to the block of data.

inLength The length of the data block.

Name	Description
`bytes`	A pointer to the block of data.
`inLength`	The length of the data block.

Result: Returns true if the object was able to append the new data, false otherwise.

ensureCapacity

Abstract: A member function which will expand the size of the collection to a given storage capacity.

public:

virtual unsigned int ensureCapacity(unsigned int newCapacity);

Parameters

Name Description

newCapacity The new capacity for the data buffer.

Name	Description
`newCapacity`	The new capacity for the data buffer.

Result: Returns the new capacity of the data buffer or the previous capacity upon error.

free

Abstract: A member function which releases all resources created or used by the OSData object.

public:

virtual void free();

Do not call this function directly, use release() instead.

getBytesNoCopy

Abstract: A member function to return a pointer to the OSData object's internal data buffer.

public:

virtual const void *getBytesNoCopy() const;

Result: Returns a reference to the OSData object's internal data buffer.

getBytesNoCopy

Abstract: Returns a reference into the OSData object's internal data buffer at particular offset and with a particular length.

public:

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

Parameters

Name Description

start The offset from the base of the internl data buffer.

inLength The length of window.

Name	Description
`start`	The offset from the base of the internl data buffer.
`inLength`	The length of window.

Result: Returns a pointer at a particular offset into the data buffer, or 0 if the starting offset or length are not valid.

getCapacity

Abstract: A member function which returns the capacity of the internal data buffer.

public:

virtual unsigned int getCapacity() const;

Result: Returns an integer value for the size of the object's internal data buffer.

getCapacityIncrement

Abstract: A member function which returns the size by which the data buffer will grow.

public:

virtual unsigned int getCapacityIncrement() const;

Result: Returns the size by which the data buffer will grow.

getLength

Abstract: A member function which returns the length of the internal data buffer.

public:

virtual unsigned int getLength() const;

Result: Returns an integer value for the length of data in the object's internal data buffer.

initWithBytes

Abstract: A member function to initialize an instance of OSData with the provided data.

public:

virtual bool initWithCapacity(unsigned int inCapacity);

Parameters

Name Description

bytes A pointer to a block of data to be copied.

inLength The length of the block of data.

Result: Returns true if initialization was successful, false otherwise.

initWithBytes

Abstract: A member function to initialize an instance of OSData which references a block of data.

public:

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

Parameters

Name Description

bytes A reference to a block of data

inLength The length of the block of data.

Result: Returns true if initialization was successful, false otherwise.

initWithBytes

Abstract: A member function to initialize an instance of OSData which references a block of data.

public:

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

Parameters

Name Description

bytes A reference to a block of data

inLength The length of the block of data.

Result: Returns true if initialization was successful, false otherwise.

initWithData

Abstract: A member function to initialize an instance of OSData with the data provided.

public:

virtual bool initWithData(const OSData *inData);

Parameters

Name Description

inData An OSData object which provides the data to be copied.

Result: Returns true if initialization was successful, false otherwise.

initWithData

Abstract: A member function to initialize an instance of OSData with a specific range of the data provided

public:

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

Parameters

Name Description

inData An OSData object.

start The starting range of data to be copied.

inLength The length in bytes of the data to be copied.

Result: Returns true if initialization was successful, false otherwise.

isEqualTo

Abstract: A member function to test the equality between an OSData object and an arbitrary OSObject derived object.

public:

virtual bool isEqualTo(const OSObject *obj) const;

Parameters

Name Description

obj An OSObject derived object.

Result: Returns true if the two objects are equivalent.

isEqualTo

Abstract: A member function to test the equality of an arbitrary block of data with the OSData object's internal data buffer.

public:

virtual bool isEqualTo(const void *someData, unsigned int inLength) const;

Parameters

Name Description

someData A pointer to a block of data.

inLength The length of the block of data.

Result: Returns true if the two blocks of data are equivalent, false otherwise.

isEqualTo

Abstract: A member function to test the equality of two OSData objects.

public:

virtual bool isEqualTo(const OSData *aData) const;

Parameters

Name Description

aData The OSData object to be compared to the receiver.

Result: Returns true if the two objects are equivalent, false otherwise.

serialize

Abstract: A member function which archives the receiver.

public:

virtual bool serialize(OSSerialize *s) const;

Parameters

Name Description

s The OSSerialize object.

Result: Returns true if serialization was successful, false if not.

setCapacityIncrement

Abstract: A member function which sets the growth size of the data buffer.

public:

virtual unsigned int setCapacityIncrement(unsigned increment);

Result: Returns the new growth size.

withBytes

Abstract: A static constructor function to create and initialize an instance of OSData and copies in the provided data.

public:

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

Parameters

Name Description

bytes A buffer of data.

inLength The size of the given buffer.

Result: Returns an instance of OSData or 0 if a failure occurrs.

withBytesNoCopy

Abstract: A static constructor function to create and initialize an instance of OSData which references a buffer of data.

public:

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

Parameters

Name Description

bytes A reference to a block of data.

inLength The size of the data block.

Result: Returns an instance of OSData or 0 if a failure occurrs.

withCapacity

Abstract: A static constructor function to create and initialize an empty instance of OSData with a given capacity.

public:

static OSData *withCapacity(unsigned int inCapacity);

Parameters

Name Description

inCapacity The initial capacity of the OSData object in bytes.

Result: Returns an instance of OSData or 0 if a failure occurrs.

withData

Abstract: A static constructor function to create and initialize an instance of OSData with the data provided.

public:

static OSData *withData(const OSData *inData);

Parameters

Name Description

inData An OSData object which provides the initial data.

Result: Returns an instance of OSData or 0 if a failure occurrs.

withData

Abstract: A static constructor function to create and initialize an instance of OSData with a specific range of the data provided.

public:

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

Parameters

Name Description

inData An OSData object which provides the initial data.

start The starting index at which the data will be copied.

inLength The number of bytes to be copied starting at index 'start'.

Result: Returns an instance of OSData or 0 if a failure occurrs.

OSDictionary.h

OSDictionary

Member Functions

ensureCapacity

Abstract: Member function to grow the size of the collection.

public:

virtual unsigned int ensureCapacity(unsigned int newCapacity);

Parameters

Name Description

newCapacity The new capacity for the dictionary to expand to.

Result: Returns the new capacity of the dictionary or the previous capacity upon error.

flushCollection

Abstract: A member function which removes and releases all objects within the collection.

public:

virtual void flushCollection();

free

Abstract: A member functions to deallocate and release all resources used by the OSDictionary instance.

public:

virtual void free();

This function should not be called directly, use release() instead.

getCapacity

Abstract: A member function which returns the storage capacity of the collection.

public:

virtual unsigned int getCapacity() const;

Result: Returns the storage capacity of the dictionary.

getCapacityIncrement

Abstract: A member function which returns the growth size for the collection.

public:

virtual unsigned int getCapacityIncrement() const;

getCount

Abstract: A member function which returns the current number of objects within the collection.

public:

virtual unsigned int getCount() const;

Result: Returns the number of objects contained within the dictionary.

getObject

Abstract: A member function to find an object in the dictionary associated by a given key.

public:

virtual OSObject *getObject(const char *aKey) const;

Parameters

Name Description

aKey The unique string identifying the object to be returned to caller.

Result: Returns a reference to the object corresponding to the given key, or 0 if the key does not exist in the dictionary.

getObject

Abstract: A member function to find an object in the dictionary associated by a given key.

public:

virtual OSObject *getObject(const OSString *aKey) const;

Parameters

Name Description

aKey The unique OSString key identifying the object to be returned to caller.

Result: Returns a reference to the object corresponding to the given key, or 0 if the key does not exist in the dictionary.

getObject

Abstract: A member function to find an object in the dictionary associated by a given key.

public:

virtual OSObject *getObject(const OSSymbol *aKey) const;

Parameters

Name Description

aKey The unique OSSymbol key identifying the object to be returned to caller.

Result: Returns a reference to the object corresponding to the given key, or 0 if the key does not exist in the dictionary.

initWithCapacity

Abstract: A member function to initialize an instance of OSDictionary.

public:

virtual bool initWithCapacity(unsigned int capacity);

Parameters

Name Description

capacity The initial storage capacity of the dictionary object.

Result: Returns true if intialization succeeded or false on failure.

initWithDictionary

Abstract: A member function to initialize an instance of OSDictionary and populate it with the contents of another dictionary.

public:

virtual bool initWithDictionary(const OSDictionary *dict,
 unsigned int capacity = 0);

Parameters

Name Description

dict The dictionary contining the objects to be used to populate the receiving dictionary.

capacity The initial storage capacity of the dictionary. If 0, the value of capacity will be set to the number of elements in the dictionary object, else the value of capacity must be greater than or equal to the number of elements in the dictionary object.

Result: Returns true if intialization succeeded or false on failure.

initWithObjects

Abstract: A member function to initialize an instance of OSDictionary and populate it with the provided objects and keys.

public:

virtual bool initWithObjects(OSObject *objects[],
 OSString *keys[],
 unsigned int count,
 unsigned int capacity = 0);

Parameters

Name Description

objects A static array of OSObject derived objects to be placed into the dictionary.

keys A static array of OSString keys which identify the correspoding objects provided in the 'objects' parameter.

count The number of objects provided to the dictionary.

capacity The initial storage capacity of the dictionary object. If 0, the capacity will be set to the size of 'count', else the capacity must be greater than or equal to the value of 'count'.

Result: Returns true if intialization succeeded or false on failure.

initWithObjects

Abstract: A member function to initialize an instance of OSDictionary and populate it with the provided objects and keys.

public:

virtual bool initWithObjects(OSObject *objects[],
 const OSSymbol *keys[],
 unsigned int count,
 unsigned int capacity = 0);

Parameters

Name Description

objects A static array of OSObject derived objects to be placed into the dictionary.

keys A static array of OSSymbol keys which identify the correspoding objects provided in the 'objects' parameter.

count The number of objects provided to the dictionary.

capacity The initial storage capacity of the dictionary object. If 0, the capacity will be set to the size of 'count', else the capacity must be greater than or equal to the value of 'count'.

Result: Returns true if intialization succeeded or false on failure.

isEqualTo

Abstract: A member function to test the equality of two dictionaries.

public:

virtual bool isEqualTo(OSDictionary *aDictionary) const;

Parameters

Name Description

aDictionary The dictionary to be compared against the receiver.

Result: Returns true if the dictionaries are equal.

isEqualTo

Abstract: A member function to test the equality of the intersections of two dictionaries.

public:

virtual bool isEqualTo(OSDictionary *aDictionary, OSCollection *keys) const;

Parameters

Name Description

aDictionary The dictionary to be compared against the receiver.

keys An OSArray or OSDictionary containing the keys describing the intersecion for the comparison.

Result: Returns true if the intersections of the two dictionaries are equal.

isEqualTo

Abstract: A member function to test the equality between the receiver and an unknown object.

public:

virtual bool isEqualTo(const OSObject *anObject) const;

Parameters

Name Description

anObject An object to be compared against the receiver.

Result: Returns true if the objects are equal.

merge

Abstract: A member function which merges the contents of a dictionary into the receiver.

public:

virtual bool merge(const OSDictionary *aDictionary);

If there are keys in 'aDictionary' which match keys in the receiving dictionary, then the objects in the receiver are replaced by those from 'aDictionary', the replaced objects are released.

Parameters

Name Description

aDictionary The dictionary whose contents are to be merged with the receiver.

Result: Returns true if the merger is successful, false otherwise.

removeObject

Abstract: A member function which removes an object from the dictionary. The removed object is automatically released.

public:

virtual void removeObject(const char *aKey);

Parameters

Name Description

aKey A unique string identifying the object to be removed from the dictionary.

removeObject

Abstract: A member function which removes an object from the dictionary. The removed object is automatically released.

public:

virtual void removeObject(const OSString *aKey);

Parameters

Name Description

aKey A unique OSString identifying the object to be removed from the dictionary.

removeObject

Abstract: A member function which removes an object from the dictionary. The removed object is automatically released.

public:

virtual void removeObject(const OSSymbol *aKey);

Parameters

Name Description

aKey A unique OSSymbol identifying the object to be removed from the dictionary.

serialize

Abstract: A member function which archives the receiver.

public:

virtual bool serialize(OSSerialize *s) const;

Parameters

Name Description

s The OSSerialize object.

Result: Returns true if serialization was successful, false if not.

setCapacityIncrement

Abstract: A member function to set the growth size of the collection.

public:

virtual unsigned int setCapacityIncrement(unsigned increment);

Parameters

Name Description

increment The new growth size.

Result: Returns the new capacity increment.

setObject

Abstract: A member function which places an object into the dictionary and identifed by a unique key.

public:

virtual bool setObject(const OSString *aKey, OSObject *anObject);

Parameters

Name Description

aKey A unique OSString identifying the object placed within the collection.

anObject The object to be stored in the dictionary. It is automatically retained.

Result: Returns true if the addition of an object was successful, false otherwise.

setObject

Abstract: A member function which places an object into the dictionary and identifed by a unique key.

public:

virtual bool setObject(const char *aKey, OSObject *anObject);

Parameters

Name Description

aKey A unique string identifying the object placed within the collection.

anObject The object to be stored in the dictionary. It is automatically retained.

Result: Returns true if the addition of an object was successful, false otherwise.

setObject

Abstract: A member function which places an object into the dictionary and identifed by a unique key.

public:

virtual bool setObject(const OSSymbol *aKey, OSObject *anObject);

Parameters

Name Description

aKey A unique OSSymbol identifying the object placed within the collection.

anObject The object to be stored in the dictionary. It is automatically retained.

Result: Returns true if the addition of an object was successful, false otherwise.

withCapacity

Abstract: A static constructor function to create and initialize an instance of OSDictionary.

public:

static OSDictionary *withCapacity(unsigned int capacity);

Parameters

Name Description

capacity The initial storage capacity of the dictionary object.

Result: Returns an instance of OSDictionary or 0 on failure.

withDictionary

Abstract: A static constructor function to create and initialize an instance of OSDictionary and populate it with objects from another dictionary.

public:

static OSDictionary *withDictionary(const OSDictionary *dict,
 unsigned int capacity = 0);

Parameters

Name Description

dict A dictionary whose contents will be placed in the new instance.

capacity The initial storage capacity of the dictionary object. If 0, the capacity will be set to the number of elements in the dictionary object, else the capacity must be greater than or equal to the number of elements in the dictionary.

Result: Returns an instance of OSDictionary or 0 on failure.

withObjects

Abstract: A static constructor function to create and initialize an instance of OSDictionary and populate it with objects provided.

public:

static OSDictionary *withObjects(OSObject *objects[],
 OSString *keys[],
 unsigned int count,
 unsigned int capacity = 0);

Parameters

Name Description

objects A static array of OSObject derived objects.

keys A static array of OSString keys.

count The number of items to be placed into the dictionary.

capacity The initial storage capacity of the dictionary object. If 0, the capacity will be set to the size of 'count', else this value must be greater or equal to 'count'.

Result: Returns an instance of OSDictionary or 0 on failure.

withObjects

Abstract: A static constructor function to create and initialize an instance of OSDictionary and populate it with objects provided.

public:

static OSDictionary *withObjects(OSObject *objects[],
 const OSSymbol *keys[],
 unsigned int count,
 unsigned int capacity = 0);

Parameters

Name Description

objects A static array of OSObject derived objects.

keys A static array of OSSymbol keys.

count The number of items to be placed into the dictionary.

capacity The initial storage capacity of the dictionary object. If 0, the capacity will be set to the size of 'count', else this value must be greater or equal to 'count'.

Result: Returns an instance of OSDictionary or 0 on failure.

OSIterator.h

OSIterator

Member Functions

getNextObject

Abstract: A pure virtual function to be over-ridden by the subclass which returns a reference to the current object in the collection and advances the interator to the next object.

public:

virtual OSObject *getNextObject() = 0;

isValid

Abstract: A pure virtual member function to be over-ridden by the subclass which indicates a modification was made to the collection.

public:

virtual bool isValid() = 0;

reset

Abstract: A pure virtual member function to be over-ridden by the subclass which reset the iterator to the beginning of the collection.

public:

virtual void reset() = 0;

OSMetaClass.h

OSMetaClass

Member Functions

OSDeclareAbstractStructors

Abstract: One of the macro's used in the class declaration of all subclasses of OSObject, declares runtime type information data and interfaces.

public:

This macro is used when the class being declared has one or more '= 0' pure virtual methods and thus it is illegal to create an instance of this class. It leaves the current privacy state as 'protected:'.

Parameters

Name Description

className Name of class. NO QUOTES.

OSDeclareCommonStructors

Abstract: Basic helper macro for the OSDeclare for Default and Abstract macros, qv. DO NOT USE.

public:

Parameters

Name Description

className Name of class. NO QUOTES.

OSDeclareDefaultStructors

Abstract: One of the macro's used in the class declaration of all subclasses of OSObject, declares runtime type information data and interfaces.

public:

Macro used in the class declaration all subclasses of OSObject, declares runtime type information data and interfaces. By convention it should be 'called' immediately after the opening brace in a class declaration. It leaves the current privacy state as 'protected:'.

Parameters

Name Description

className Name of class. NO QUOTES.

OSDefineAbstractStructors

Abstract: Basic helper macro for the OSDefineMetaClass for the default and Abstract macros, qv. DO NOT USE.

public:

Parameters

Name Description

className Name of class. NO QUOTES and NO MACROS.

superClassName Name of super class. NO QUOTES and NO MACROS.

OSDefineDefaultStructors

Abstract: Basic helper macro for the OSDefineMetaClass for the default and Abstract macros, qv. DO NOT USE.

public:

Parameters

Name Description

className Name of class. NO QUOTES and NO MACROS.

superClassName Name of super class. NO QUOTES and NO MACROS.

OSDefineMetaClass

Abstract: Define an OSMetaClass instance, used for backward compatiblility only.

public:

Parameters

Name Description

className Name of class. NO QUOTES and NO MACROS.

superClassName Name of super class. NO QUOTES and NO MACROS.

OSDefineMetaClassAndAbstractStructors

Abstract: Define an OSMetaClass subclass and the runtime system routines.

public:

Parameters

Name Description

className Name of class. NO QUOTES and NO MACROS.

superClassName Name of super class. NO QUOTES and NO MACROS.

OSDefineMetaClassAndAbstractStructorsWithInit

Abstract: Primary definition macro for all abstract classes that a subclasses of OSObject.

public:

Define an OSMetaClass subclass and the primary constructors and destructors for a subclass of OSObject that is an abstract class. In general this 'function' is 'called' at the top of the file just before the first function is implemented for a particular class. Once the OSMetaClass has been constructed, at load time, call the init routine. NB you can not rely on the order of execution of the init routines.

Parameters

Name Description

className Name of class. NO QUOTES and NO MACROS.

superClassName Name of super class. NO QUOTES and NO MACROS.

init Name of a function to call after the OSMetaClass is constructed.

OSDefineMetaClassAndStructors

Abstract: Define an OSMetaClass subclass and the runtime system routines.

public:

Parameters

Name Description

className Name of class. NO QUOTES and NO MACROS.

superClassName Name of super class. NO QUOTES and NO MACROS.

OSDefineMetaClassAndStructorsWithInit

Abstract: See OSDefineMetaClassAndStructors

public:

Define an OSMetaClass subclass and the primary constructors and destructors for a subclass of OSObject that isn't an abstract class. In general this 'function' is 'called' at the top of the file just before the first function is implemented for a particular class. Once the OSMetaClass has been constructed, at load time, call the init routine. NB you can not rely on the order of execution of the init routines.

Parameters

Name Description

className Name of class. NO QUOTES and NO MACROS.

superClassName Name of super class. NO QUOTES and NO MACROS.

init Name of a function to call after the OSMetaClass is constructed.

OSDefineMetaClassWithInit

Abstract: Basic helper macro for the OSDefineMetaClass for the default and Abstract macros, qv. DO NOT USE.

public:

Parameters

Name Description

className Name of class. NO QUOTES and NO MACROS.

superClassName Name of super class. NO QUOTES and NO MACROS.

init Name of a function to call after the OSMetaClass is constructed.

OSMetaClass

Abstract: Private the default constructor

private:

 OSMetaClass();

OSMetaClass

Abstract: Constructor for OSMetaClass objects

protected:

 OSMetaClass(const char *inClassName,
 const char *inSuperClassName,
 unsigned int inClassSize);

This constructor is protected and cannot not be used to instantiate an OSMetaClass object, i.e. OSMetaClass is an abstract class. This function stores the currently constructing OSMetaClass instance away for later processing. See preModLoad and postModLoad.

Parameters

Name Description

inClassName cString of the name of the class this meta-class represents.

inSuperClassName cString of the name of the super class.

inClassSize sizeof the class.

alloc

Abstract: Allocate an instance of the class that this OSMetaClass instance represents.

public:

virtual OSObject *alloc() const = 0;

This alloc function is analogous to the old ObjC class alloc method. Typically not used by clients as the static function allocClassWithName is more generally useful. Infact that function is implemented in terms of this virtual function. All subclass's of OSMetaClass must implement this function but that is what the OSDefineMetaClassAndStructor's families of macros does for the developer automatically.

Result: Pointer to a new object with a retain count of 1.

allocClassWithName

Abstract: Lookup a meta-class in the runtime type information system and return the results of an alloc call.

public:

static OSObject *allocClassWithName(const char *name);

Parameters

Name Description

name Name of the desired class.

Result: pointer to an new object, 0 if not found or so memory.

allocClassWithName

Abstract: Lookup a meta-class in the runtime type information system and return the results of an alloc call.

public:

static OSObject *allocClassWithName(const OSSymbol *name);

Parameters

Name Description

name Name of the desired class.

Result: pointer to an new object, 0 if not found or so memory.

allocClassWithName

Abstract: Lookup a meta-class in the runtime type information system and return the results of an alloc call.

public:

static OSObject *allocClassWithName(const OSString *name);

Parameters

Name Description

name Name of the desired class.

Result: pointer to an new object, 0 if not found or so memory.

checkMetaCast

Abstract: Ask a OSMetaClass instance if the given object is either an instance of it or an instance of a subclass of it.

public:

OSObject *checkMetaCast(const OSObject *check) const;

Parameters

Name Description

check Pointer of object to introspect.

Result: check parameter if cast valid, 0 otherwise.

checkMetaCastWithName

Abstract: Introspect an objects inheritance tree looking for a class of the given name. Basis of MacOSX's kernel dynamic casting mechanism.

public:

static OSObject * checkMetaCastWithName(const char *name, const OSObject *in);

Parameters

Name Description

name Name of the desired class or super class.

in object to be introspected.

Result: in parameter if cast valid, 0 otherwise.

checkMetaCastWithName

Abstract: Introspect an objects inheritance tree looking for a class of the given name. Basis of MacOSX's kernel dynamic casting mechanism.

public:

static OSObject * checkMetaCastWithName(const OSSymbol *name, const OSObject *in);

Parameters

Name Description

name Name of the desired class or super class.

in object to be introspected.

Result: in parameter if cast valid, 0 otherwise.

checkMetaCastWithName

Abstract: Introspect an objects inheritance tree looking for a class of the given name. Basis of MacOSX's kernel dynamic casting mechanism.

public:

static OSObject * checkMetaCastWithName(const OSString *name, const OSObject *in);

Parameters

Name Description

name Name of the desired class or super class.

in object to be introspected.

Result: in parameter if cast valid, 0 otherwise.

checkModLoad

Abstract: Check if the current load attempt is still OK.

public:

static bool checkModLoad(void *loadHandle);

Parameters

Name Description

loadHandle Handle returned when a successful call to preModLoad is made.

Result: true if no error's are outstanding and the system is primed to recieve more objects.

failModLoad

Abstract: Record an error during the loading of an kernel module.

public:

static void failModLoad(OSReturn error);

As constructor's can't return errors nor can they through exceptions in embedded-c++ an indirect error mechanism is necessary. Check mod load returns a bool to indicate the current error state of the runtime type information system. During object construction a call to failModLoad will cause an error code to be recorded. Once an error has been set the continuing construction will be ignored until the end of the pre/post load.

Parameters

Name Description

error Code of the error.

free

Abstract: Don't allow OSObject::free to be called

protected:

virtual void free();

The allocation strategies implemented by OSObject don't work for OSMetaClasses, as OSObjects assume that all object are allocated using new and thus they must all be removed using delete, or in fact free. As OSMetaClass is always a statically defined object, see OSDefineMetaClass, it isn't appropriate for any attempt to be made to implement the default reference counting and free mechanism..

getClassName

Abstract: 'Get'ter for class name.

public:

const char *getClassName() const;

Result: cString of the class name.

getClassSize

Abstract: 'Get'ter for sizeof(class).

public:

unsigned int getClassSize() const;

Result: sizeof of class that this OSMetaClass instance represents.

getInstanceCount

Abstract: How many instances of the class have been created.

public:

unsigned int getInstanceCount() const;

Result: Count of the number of instances.

getMetaClassWithName

Abstract: Lookup a meta-class in the runtime type information system

public:

static const OSMetaClass *getMetaClassWithName(const OSSymbol *name);

Parameters

Name Description

name Name of the desired class's meta-class.

Result: pointer to a meta-class object if found, 0 otherwise.

getMetaClassWithName

Abstract: Lookup a meta-class in the runtime type information system

public:

static const OSMetaClass *getMetaClassWithName(const char *name);

Parameters

Name Description

name Name of the desired class's meta-class.

Result: pointer to a meta-class object if found, 0 otherwise.

getMetaClassWithName

Abstract: Lookup a meta-class in the runtime type information system

public:

static const OSMetaClass *getMetaClassWithName(const OSString *name);

Parameters

Name Description

name Name of the desired class's meta-class.

Result: pointer to a meta-class object if found, 0 otherwise.

getSuperClass

Abstract: 'Get'ter for the super class.

public:

const OSMetaClass *getSuperClass() const;

Result: Pointer to superclass, chain ends with 0 for OSObject.

instanceConstructed

Abstract: Counts the instances of the class behind this metaclass.

public:

void instanceConstructed() const;

Every non-abstract class that inherits from OSObject has a default constructor that calls it's own meta-class' instanceConstructed function. This constructor is defined by the OSDefineMetaClassAndStructors macro (qv) that all OSObject subclasses must use. Also if the instance count goes from 0 to 1, ie the first instance, then increment the instance count of the super class

instanceDestructed

Abstract: Removes one instance of the class behind this metaclass.

public:

void instanceDestructed() const;

OSObject's free function calls this method just before it does a 'delete this' on itself. If the instance count transitions from 1 to 0, i.e. the last object, then one instance of the superclasses is also removed.

logError

Abstract: Given an error code log an error string using printf

private:

static void logError(OSReturn result);

modHasInstance

Abstract: Do any of the objects represented by OSMetaClass and associated with the given kernel module name have instances?

public:

static bool modHasInstance(const char *kmodName);

Check all meta-classes associated with the module name and check their instance counts. This function is used to check to see if a module can be unloaded. Obviously if an instance is still outstanding it isn't safe to unload the code that relies on that object.

Parameters

Name Description

kmodName cString of the kernel module name.

Result: true if there are any current instances of any class in the module.

postModLoad

Abstract: Finish postprocessing on a kernel module's meta-classes.

public:

static OSReturn postModLoad(void *loadHandle);

As the order of static object construction is undefined it is necessary to process the constructors in two phases. These phases rely on global information that is created be the preparation step, preModLoad, which also guarantees single threading between multiple modules. Phase one was the static construction of each meta-class object one by one withing the context prepared by the preModLoad call. postModLoad is the second phase of processing. Inserts links all of the super class inheritance chains up, inserts the meta-classes into the global register of classes and records for each meta-class which kernel module caused it's construction. Finally it cleans up the temporary storage and releases the single threading lock and returns whatever error has been recorded in during the construction phase or the post processing phase.

Parameters

Name Description

loadHandle Handle returned when a successful call to preModLoad is made.

Result: Error code of the first error encountered.

preModLoad

Abstract: Prepare the runtime type system for the load of a module.

public:

static void *preModLoad(const char *kmodName);

Prepare the runtime type information system for the loading of new all meta-classes constructed between now and the next postModLoad. preModLoad grab's a lock so that the runtime type information system loading can be protected, the lock is released by the postModLoad function. Any OSMetaClass that is constructed between the bracketing pre and post calls will be assosiated with the module name.

Parameters

Name Description

kmodName globally unique cString name of the kernel module being loaded.

Result: If success full return a handle to be used in later calls 0 otherwise.

release

Abstract: Don't allow OSObject::release to be called, see free

protected:

virtual void release();

reportModInstances

Abstract: Log any object that has instances in a module.

public:

static void reportModInstances(const char *kmodName);

When a developer ask for a module to be unloaded but the unload fails due to outstanding instances. This function will report which classes still have instances. It is intended mostly for developers to find problems with unloading classes and will be called automatically by 'verbose' unloads.

Parameters

Name Description

kmodName cString of the kernel module name.

retain

Abstract: Don't allow OSObject::retain to be called, see free

protected:

virtual void retain();

~OSMetaClass

Abstract: Destructor for OSMetaClass objects

protected:

virtual ~OSMetaClass();

If this function is called it means that the object code that implemented this class is actually in the process of unloading. The destructor removes all reference's to the subclass from the runtime type information system.

Member Data

className

private:

 const OSSymbol *className;

OSSymbol of the class' name.

classSize

private:

 unsigned int classSize;

How big is a single instancde of this class.

instanceCount

private:

 mutable unsigned int instanceCount;

Roughly number of instances of the object. Used primarily as a code in use flag.

superClass

private:

 OSMetaClass *superClass;

Handle to the superclass' meta class.

OSNumber.h

OSNumber

Member Functions

addValue

Abstract: A member function which adds an integer value to the internal numeric value of the OSNumber object.

public:

virtual void addValue(signed long long value);

Parameters

Name Description

value The value to be added.

free

Abstract: Releases and deallocates resources created by the OSNumber instances.

public:

virtual void free();

This function should not be called directly, use release() instead.

init

Abstract: A member function to initialize an instance of OSNumber.

public:

virtual bool init(const char *value, unsigned int numberOfBits);

Parameters

Name Description

value A c-string representation of a numeric value.

numberOfBits The number of bit required to represent the value.

Result: Returns true if instance was successfully initialized, false otherwise.

init

Abstract: A member function to initialize an instance of OSNumber.

public:

virtual bool init(unsigned long long value, unsigned int numberOfBits);

Parameters

Name Description

value An integer value.

numberOfBits The number of bit required to represent the value.

Result: Returns true if instance was successfully initialized, false otherwise.

isEqualTo

Abstract: A member function to test the equality of two OSNumber objects.

public:

virtual bool isEqualTo(const OSNumber *integer) const;

Parameters

Name Description

integer The OSNumber object to be compared against the receiver.

Result: Returns true if the two objects are equivalent, false otherwise.

isEqualTo

Abstract: A member function to test the equality of an arbitrary OSObject derived object and an OSNumber object.

public:

virtual bool isEqualTo(const OSObject *obj) const;

Parameters

Name Description

obj The OSObject derived object to be compared to the receiver.

Result: Returns true if the two objects are equivalent, false otherwise.

numberOfBits

Abstract: A member function which returns the number of bits used to represent the value.

public:

virtual unsigned int numberOfBits() const;

Result: Returns the number of bits required to represent the value.

numberOfBytes

Abstract: A member function which returns the number of bytes used to represent the value.

public:

virtual unsigned int numberOfBytes() const;

Result: Returns the number of bytes required to represent the value.

serialize

Abstract: A member function which archives the receiver.

public:

virtual bool serialize(OSSerialize *s) const;

Parameters

Name Description

s The OSSerialize object.

Result: Returns true if serialization was successful, false if not.

setValue

Abstract: Replaces the current internal numeric value of the OSNumber object by the value given.

public:

virtual void setValue(unsigned long long value);

Parameters

Name Description

value The new value for the OSNumber object.

unsigned16BitValue

Abstract: A member function which returns its internal value as an 16-bit value.

public:

virtual unsigned short unsigned16BitValue() const;

Result: Returns the internal value as an 16-bit value.

unsigned32BitValue

Abstract: A member function which returns its internal value as an 32-bit value.

public:

virtual unsigned int unsigned32BitValue() const;

Result: Returns the internal value as an 32-bit value.

unsigned64BitValue

Abstract: A member function which returns its internal value as an 64-bit value.

public:

virtual unsigned long long unsigned64BitValue() const;

Result: Returns the internal value as an 64-bit value.

unsigned8BitValue

Abstract: A member function which returns its internal value as an 8-bit value.

public:

virtual unsigned char unsigned8BitValue() const;

Result: Returns the internal value as an 8-bit value.

withNumber

Abstract: A static constructor function to create and initialize an instance of OSNumber with a given value represented as a simple c-string.

public:

static OSNumber *withNumber(const char *value, unsigned int numberOfBits);

Parameters

Name Description

value A c-string representing a numeric value.

numberOfBits The number of bit required to represent the value.

Result: Returns an instance of OSNumber or 0 if an error occurred.

withNumber

Abstract: A static constructor function to create and initialize an instance of OSNumber with a given value.

public:

static OSNumber *withNumber(unsigned long long value,
 unsigned int numberOfBits);

Parameters

Name Description

value The numeric integer value.

numberOfBits The number of bit required to represent the value.

Result: Returns an instance of OSNumber or 0 if an error occurred.

OSObject.h

OSObject

Member Functions

OSCheckTypeInst

Abstract: Is the target object a subclass of the reference object?

public:

Parameters

Name Description

typeinst Reference instance of an object, desired type.

inst Instance of object to check for type compatibility.

Result: false if typeinst or inst are 0 or inst is not a subclass of typeinst's class. true otherwise.

OSDynamicCast

Abstract: Roughly analagous to (type *) inst, but check if valid first.

public:

OSDynamicCast is an attempt to implement a rudimentary equivalent to rtti's dynamic_cast operator. Embedded-C++ doesn't allow the use of rtti. OSDynamicCast is build on the OSMetaClass mechanism. Note it is safe to call this with a 0 paramter.

Parameters

Name Description

type name of desired class name. Notice that it is assumed that you desire to cast to a pointer to an object of this type. Also type qualifiers, like const, are not recognised and will cause an, usually obscure, compile error.

inst Pointer to object that you wish to attempt to type cast. May be 0.

Result: inst if object non-zero and it is of the desired type, otherwise 0.

OSObject

Abstract: Disable implicit copy constructor by making private

private:

 OSObject(OSObject &src);

Parameters

Name Description

src Reference to source object that isn't allowed to be copied

OSTypeID

Abstract: Given the name of a class return it's typeID

public:

Parameters

Name Description

type Name of the desired type, eg. OSObject.

Result: 'this' if object is of desired type, otherwise 0.

OSTypeIDInst

Abstract: Given a pointer to an object return it's typeID

public:

Parameters

Name Description

typeinst An instance of an OSObject subclass.

Result: The typeID, ie. OSMetaClass *.

free

Abstract: The last reference is gone so clean up your resources.

protected:

virtual void free();

Release all resources held by the object, then call your parent's free().

Caution:
1> You can not assume that you have completed initialisation before your free is called, so be very careful in your implementation.
2> The implementation is OSObject::free() { delete this; } so do not call super::free() until just before you return.
3> Free is not allowed to fail all resource must be released on completion.

getRetainCount

Abstract: How many times has this object been retained?

public:

virtual int getRetainCount() const;

Result: Current retain count

init

Abstract: Mac OS X kernel's primary mechanism for constructing objects.

protected:

virtual bool init();

Your responsibility as a subclass author is to override the init method of your parent. In general most of our implementations call ::init() before doing local initialisation, if the parent fails then return false immediately. If you have a failure during you local initialisation then return false.

Result: OSObject::init Always returns true, but subclasses will return false on init failure.

isEqualTo

Abstract: Is this == anObj?

public:

virtual bool isEqualTo(const OSObject *anObj) const;

OSObject::isEqualTo implements this as a shallow pointer comparison. The OS container classes do a more meaningful comparison. Your mileage may vary.

Parameters

Name Description

anObj Object to compare 'this' to.

Result: true if the objects are equivalent, false otherwise.

metaCast

Abstract: Check to see if this object is or inherits from the given type.

public:

OSObject *metaCast(const OSMetaClass *toMeta) const;

This function is the guts of the OSMetaClass system. IODynamicCast, qv, is implemented using this function.

Parameters

Name Description

toMeta Pointer to a constant OSMetaClass for the desired target type.

Result: 'this' if object is of desired type, otherwise 0.

metaCast

Abstract: See OSObject::metaCast(const OSMetaClass *)

public:

OSObject *metaCast(const OSSymbol *toMeta) const;

Parameters

Name Description

toMeta OSSymbol of the desired class' name.

Result: 'this' if object is of desired type, otherwise 0.

metaCast

Abstract: See OSObject::metaCast(const OSMetaClass *)

public:

OSObject *metaCast(const OSString *toMeta) const;

Parameters

Name Description

toMeta OSString of the desired class' name.

Result: 'this' if object is of desired type, otherwise 0.

metaCast

Abstract: See OSObject::metaCast(const OSMetaClass *)

public:

OSObject *metaCast(const char *toMeta) const;

Parameters

Name Description

toMeta const char * C String of the desired class' name.

Result: 'this' if object is of desired type, otherwise 0.

operator =

Abstract: Disable implicit copy constructor by making private

private:

void operator =(OSObject &src);

Parameters

Name Description

src Reference to source object that isn't allowed to be copied

operator delete

Abstract: Release the 'operator new'ed memory.

protected:

static void operator delete(void *mem, size_t size);

Never attempt to delete an object that inherits from OSObject directly use $link release().

Parameters

Name Description

mem pointer to block of memory

size size of block of memory

operator new

Abstract: Allocator for all objects that inherit from OSObject

public:

static void *operator new(size_t size);

Parameters

Name Description

size number of bytes to allocate

Result: returns pointer to block of memory if avaialable, 0 otherwise.

release

Abstract: Primary implementation of the release mechanism.

protected:

void release(int when) const;

If $link retainCount <= the when argument then call $link free(). This indirect implementation of $link release allows the developer to break reference circularity. An example of this sort of problem is a parent/child mutual reference, either the parent or child can implement: void release() { release(2); } thus breaking the cirularity.

Parameters

Name Description

when When retainCount == when then call free().

release

Abstract: Release a reference to this object

public:

virtual void release() const;

retain

Abstract: Retain a reference in this object.

public:

virtual void retain() const;

serialize

public:

virtual bool serialize(OSSerialize *s) const;

Member Data

retainCount

private:

 int retainCount;

Number of references held on this instance.

OSOrderedSet.h

OSOrderedSet

Member Functions

containsObject

Abstract: A member function to query the set for the presence of a particular object.

public:

virtual bool containsObject(const OSObject *anObject) const;

Parameters

Name Description

anObject The object to be located.

Result: Returns true if the object is present in the set, false otherwise.

ensureCapacity

Abstract: A member function to expand the size of the collection.

public:

virtual unsigned int ensureCapacity(unsigned int newCapacity);

Parameters

Name Description

newCapacity The new size capacity for the collection.

Result: Returns new capacity of the set when successful or the old capacity on failure.

flushCollection

Abstract: A member function to remove and release all items in the set.

public:

virtual void flushCollection();

free

Abstract: A member function to release and deallocate any resources used by the instance of OSOrderedSet.

public:

virtual void free();

getCapacity

Abstract: A member function to return the storage capacity of the collection.

public:

virtual unsigned int getCapacity() const;

Result: Returns the total storage capacity of the set.

getCapacityIncrement

Abstract: A member function to get the size by which the collection will grow.

public:

virtual unsigned int getCapacityIncrement() const;

Result: Returns the current growth size.

getCount

Abstract: A member function to return the number of objects within the collection.

public:

virtual unsigned int getCount() const;

Result: Returns the number of items in the set.

getFirstObject

Abstract: A member function to return the first object in the set.

public:

virtual OSObject *getFirstObject() const;

Result: Returns the object ordered first in the set or 0 if none exist.

getLastObject

Abstract: A member function to return the last object in the set.

public:

virtual OSObject *getLastObject() const;

Result: Returns the object ordered last in the set or 0 if none exist.

getObject

Abstract: A member function to return a reference to an object at a particular index.

public:

virtual OSObject *getObject( unsigned int index) const;

Parameters

Name Description

index The index into the set.

Result: Returns a reference to the object at the given index, 0 if none exist at that location.

getOrderingRef

Abstract: A member function to return a the ordering context.

public:

virtual void *getOrderingRef();

Result: Returns the ordering context, or NULL if none exist.

initWithCapacity

Abstract: A member function for initializing an instance of OSOrderedSet.

public:

virtual bool initWithCapacity(unsigned int capacity,
 OSOrderFunction orderFunc = 0,
 void * orderingRef = 0);

Parameters

Name Description

capacity The initial storage size in number of objects of the set.

orderFunc A c-style function which implements the sorting algorithm for the set.

orderingRef A ordering context used as a hint for ordering objects within the set.

Result: Returns true if initialization was successful, or false if a failure occurred.

isEqualTo

Abstract: A member function to test the equality between an OSOrderedSet object and the receiver.

public:

virtual bool isEqualTo(OSOrderedSet *anOrderedSet) const;

Parameters

Name Description

anOrderedSet The OSOrderedSet object to be compared against the receiver.

Result: Returns true if the two objects are equivalent, false otherwise.

isEqualTo

Abstract: A member function to test the equality between an arbitrary OSObject derived object and the receiver.

public:

virtual bool isEqualTo(const OSObject *anObject) const;

Parameters

Name Description

anObject The OSObject derived object to be compared against the receiver.

Result: Returns true if the two objects are equivalent, false otherwise.

member

Abstract: A member function to query the set for the presence of a particular object.

public:

virtual bool member(const OSObject *anObject) const;

Parameters

Name Description

anObject The object to be located.

Result: Returns true if the object is present in the set, false otherwise.

orderObject

Abstract: A member function to return the ordering value of an object.

public:

virtual SInt32 orderObject( OSObject * anObject );

Parameters

Name Description

anObject The object to be queried.

Result: Returns the ordering value for an object.

removeObject

Abstract: A member function to remove and release an object in the set.

public:

virtual void removeObject(OSObject *anObject);

Parameters

Name Description

anObject The object to remove from the set.

setCapacityIncrement

Abstract: A member function to set the size by which the collection will grow.

public:

virtual unsigned int setCapacityIncrement(unsigned increment);

Parameters

Name Description

increment The new growth factor for the set.

Result: Returns new growth size.

setFirstObject

Abstract: A member function to place an OSObject derived object order it first in the set.

public:

virtual bool setFirstObject(OSObject *anObject);

Parameters

Name Description

anObject The object to be placed into the collection.

Result: Returns true if object was successfully added to the collection, false otherwise.

setLastObject

Abstract: A member function to place an OSObject derived object order it last in the set.

public:

virtual bool setLastObject(OSObject *anObject);

Parameters

Name Description

anObject The object to be placed into the collection.

Result: Returns true if object was successfully added to the collection, false otherwise.

setObject

Abstract: A member function to place an OSObject derived object into the set. The object will be automatically sorted in the set.

public:

virtual bool setObject(OSObject *anObject);

Parameters

Name Description

anObject The object to be placed into the collection.

Result: Returns true if object was successfully added to the collection, false otherwise.

setObject

Abstract: A member function to place an object into the set at a particular index.

public:

virtual bool setObject(unsigned int index, OSObject *anObject);

Parameters

Name Description

index The index in the set to place the object.

anObject The object to be placed into the set.

Result: Returns true if the object was successfully placed into the collection, false otherwise.

withCapacity

Abstract: A static constructor function for creating and initializing an instance of OSOrderedSet.

public:

static OSOrderedSet *withCapacity(unsigned int capacity,
 OSOrderFunction orderFunc = 0,
 void * orderingRef = 0);

Parameters

Name Description

capacity The initial storage size in number of objects of the set.

orderFunc A c-style function which implements the sorting algorithm for the set.

orderingRef A ordering context used as a hint for ordering objects within the set.

Result: Returns an instance of OSSet, or 0 if a failure occurred.

Member Data

OSOrderFunction

public:typedef SInt32 (*OSOrderFunction)( OSObject * obj1, OSObject * obj2, void * ref );

Parameters

Name Description

obj1 An object from the collection.

obj2 An object to be compared to obj1.

ref The ordering conext used by the sorting function as a hint for sorting.

OSSerialize.h

OSSerialize

OSSet.h

OSSet

Member Functions

containsObject

Abstract: A member function to query the collection for the presence of an object.

public:

virtual bool containsObject(const OSObject *anObject) const;

Parameters

Name Description

anObject The OSObject derived object to be removed from the collecion.

Result: Returns true if the object is present within the set, false otherwise.

ensureCapacity

Abstract: A member function to grow the size of the collection.

public:

virtual unsigned int ensureCapacity(unsigned int newCapacity);

Parameters

Name Description

newCapacity The new capacity for the collection to expand to.

Result: Returns the new capacity of the collecion or the previous capacity upon error.

flushCollection

Abstract: A member function which removes and releases all objects within the collection.

public:

virtual void flushCollection();

free

Abstract: A member function to release all resources created or used by the OSArray instance.

public:

virtual void free();

getAnyObject

Abstract: A member function which returns an object from the set.

public:

virtual OSObject *getAnyObject() const;

Result: Returns an object if one exists within the set.

getCapacity

Abstract: A member function which returns the storage capacity of the collection.

public:

virtual unsigned int getCapacity() const;

Result: Returns the storage size of the collection.

getCapacityIncrement

Abstract: A member function which returns the growth factor of the collection.

public:

virtual unsigned int getCapacityIncrement() const;

Result: Returns the size by which the collection will grow.

getCount

Abstract: A member function which returns the number of objects current in the collection.

public:

virtual unsigned int getCount() const;

Result: Returns the number of objects in the collection.

initWithArray

Abstract: A member function to initialize a new instance of OSSet and populate it with the contents of the OSArray object provided.

public:

virtual bool initWithArray(const OSArray *array,
 unsigned int capacity = 0);

Parameters

Name Description

array The OSArray object contining OSObject derived objects used to populate the new OSSet object.

capacity The initial storage capacity of the object. This value must be equal to or larger than the number of objects provided by the OSArray object passed as the first parameter.

Result: Returns true if initialization successful or false on failure.

initWithCapacity

Abstract: A member function to initialize an instance of OSSet with a given capacity.

public:

virtual bool initWithCapacity(unsigned int capacity);

Parameters

Name Description

capacity The initial storage size of the collection.

Result: Returns true if initialization successful or false on failure.

initWithObjects

Abstract: A member function to initialize an instance of OSSet with a given capacity and populate the collection with the objects provided.

public:

virtual bool initWithObjects(OSObject *objects[],
 unsigned int count,
 unsigned int capacity = 0);

Parameters

Name Description

object A static array containing OSObject derived objects used to populate the collection.

count The number of objects provided.

capacity The initial storage size of the collection. This value must be equal to or larger than the 'count' parameter.

Result: Returns true if initialization successful or false on failure.

initWithSet

Abstract: A member function to initialize a new instance of OSSet and populate it with the contents of the OSSet object provided.

public:

virtual bool initWithSet(const OSSet *set,
 unsigned int capacity = 0);

This function should not be called directly, use release() instead.

Parameters

Name Description

array The OSSet object contining OSObject derived objects used to populate the new OSSet object.

capacity The initial storage capacity of the object. This value must be equal to or larger than the number of objects provided by the OSSet object passed as the first parameter.

Result: Returns true if initialization successful or false on failure.

isEqualTo

Abstract: A member function to test the equality between the receiver and an unknown object.

public:

virtual bool isEqualTo(const OSObject *anObject) const;

Parameters

Name Description

anObject An object to be compared against the receiver.

Result: Returns true if the objects are equal.

isEqualTo

Abstract: A member function to test the equality between the receiver and an OSSet object.

public:

virtual bool isEqualTo(OSSet *aSet) const;

Parameters

Name Description

aSet An OSSet object to be compared against the receiver.

Result: Returns true if the objects are equivalent.

member

Abstract: A member function to query the collection for the presence of an object.

public:

virtual bool member(const OSObject *anObject) const;

Parameters

Name Description

anObject The OSObject derived object to be removed from the collecion.

Result: Returns true if the object is present within the set, false otherwise.

merge

Abstract: A member function to merge the contents of an OSArray object with set.

public:

virtual bool merge(const OSArray *array);

Parameters

Name Description

array The OSArray object which contains the objects to be merged.

Result: Returns true if the contents of the OSArray were successfully merged into the reciever.

merge

Abstract: A member function to merge the contents of an OSSet object with receiver.

public:

virtual bool merge(const OSSet *set);

Parameters

Name Description

set The OSSet object which contains the objects to be merged.

Result: Returns true if the contents of the OSSet were successfully merged into the reciever.

removeObject

Abstract: A member function to remove objects from the collection.

public:

virtual void removeObject(OSObject * anObject);

The object removed from the collecion is automatically released.

Parameters

Name Description

anObject The OSObject derived object to be removed from the collecion.

serialize

Abstract: A member function which archives the receiver.

public:

virtual bool serialize(OSSerialize *s) const;

Parameters

Name Description

s The OSSerialize object.

Result: Returns true if serialization was successful, false if not.

setCapacityIncrement

Abstract: A member function which sets the growth factor of the collection.

public:

virtual unsigned int setCapacityIncrement(unsigned increment);

Result: Returns the new increment.

setObject

Abstract: A member function to place objects into the collection.

public:

virtual bool setObject(OSObject *anObject);

The object added to the collecion is automatically retained.

Parameters

Name Description

anObject The OSObject derived object to be placed into the collecion.

Result: Returns true if the object was successfully placed into the collection, false otherwise.

withArray

Abstract: A static constructor function to create and initialize an instance of OSSet and populate it with the objects from an OSSArray obeject.

public:

static OSSet *withArray(const OSArray *array,
 unsigned int capacity = 0);

Parameters

Name Description

array An OSArray object containing a list of OSObject derived objects which are used to initially populate the OSSet object.

capacity The initial storage size of the collection. This value must be equal to or larger than the number of objects provided by the OSArray object passed as the first parameter.

Result: Returns an instance of OSSet or 0 on failure.

withCapacity

Abstract: A static constructor function to create and initialize an instance of OSSet with a given capacity.

public:

static OSSet *withCapacity(unsigned int capacity);

Parameters

Name Description

capacity The initial capacity of the collection. The capacity is the total number of objects that can be stored in the collection.

Result: Returns an instance of OSSet or 0 on failure.

withObjects

Abstract: A static constructor function to create and initialize an instance of OSSet and populate it with the objects provied.

public:

static OSSet *withObjects(OSObject *objects[],
 unsigned int count,
 unsigned int capacity = 0);

Parameters

Name Description

objects A static array of OSObject derived objects which are used to populate the collection.

count The number of objects passed to the collection.

capacity The initial storage size of the collection. The capacity is the total number of objects that can be stored in the collection. This value must be equal to or larger than the count parameter.

Result: Returns an instance of OSSet or 0 on failure.

withSet

Abstract: A static constructor function to create an instance of OSSet and populate it with the objects from another OSSet obeject.

public:

static OSSet *withSet(const OSSet *set,
 unsigned int capacity = 0);

Parameters

Name Description

array An OSSet object containing OSObject derived objects which are used to initially populate the new OSSet object.

capacity The initial storage size of the collection. This value must be equal to or larger than the number of objects provided by the OSSet object passed as the first parameter.

Result: Returns an instance of OSSet or 0 on failure.

OSString.h

OSString

Member Functions

free

Abstract: Releases all resources used by the OSString object.

public:

virtual void free();

This function should not be called directly, use release() instead.

getCStringNoCopy

Abstract: Returns a pointer to the internal c-string array.

public:

virtual const char *getCStringNoCopy() const;

Result: Returns a pointer to the internal c-string array.

getChar

Abstract: Returns a character at a particular index in the string object.

public:

virtual char getChar(unsigned int index) const;

Parameters

Name Description

index The index into the string.

Result: Returns a character.

getLength

Abstract: A member function to return the length of the string.

public:

virtual unsigned int getLength() const;

Result: Returns the length of the string.

initWithCString

Abstract: Member function to initialize an instance of OSString with a simple c-string.

public:

virtual bool initWithCString(const char *cString);

Parameters

Name Description

cString A simple c-string.

Result: Returns true on success, false otherwise.

initWithCStringNoCopy

Abstract: Member function to initialize an instance of OSString with a simple c-string but does not copy the string into the container.

public:

virtual bool initWithCStringNoCopy(const char *cString);

Parameters

Name Description

cString A simple c-string.

Result: Returns true on success, false otherwise.

initWithString

Abstract: Member function to initialize an instance of OSString from another OSString object.

public:

virtual bool initWithString(const OSString *aString);

Parameters

Name Description

aString An OSString object.

Result: Returns true on success, false otherwise.

isEqualTo

Abstract: A member function to test the equality of an unknown OSObject derived object and the OSString instance.

public:

virtual bool isEqualTo(const OSObject *obj) const;

Parameters

Name Description

obj An OSObject derived object.

Result: Returns true if the two objects are equivalent, false otherwise.

isEqualTo

Abstract: A member function to test the equality of c-string and the internal string array of the receiving OSString object.

public:

virtual bool isEqualTo(const char *aCString) const;

Parameters

Name Description

aCString A simple c-string.

Result: Returns true if the two strings are equal, false otherwise.

isEqualTo

Abstract: A member function to test the equality of two OSString objects.

public:

virtual bool isEqualTo(const OSString *aString) const;

Parameters

Name Description

aString An OSString object.

Result: Returns true if the two strings are equal, false otherwise.

serialize

Abstract: A member function which archives the receiver.

public:

virtual bool serialize(OSSerialize *s) const;

Parameters

Name Description

s The OSSerialize object.

Result: Returns true if serialization was successful, false if not.

setChar

Abstract: Replaces a character at a particular index in the string object.

public:

virtual bool setChar(char aChar, unsigned int index);

Parameters

Name Description

index The index into the string.

Result: Returns true if the character was successfully replaced or false if the string is immutable or index was beyond the bounds of the character array.

withCString

Abstract: Static constructor function to create and initialize an instance of OSString.

public:

static OSString *withCString(const char *cString);

Parameters

Name Description

cString A simple c-string.

Result: Returns an instance of OSString or 0 on error.

withCStringNoCopy

Abstract: Static constructor function to create and initialize an instance of OSString but does not copy the original c-string into container.

public:

static OSString *withCStringNoCopy(const char *cString);

Parameters

Name Description

cString A simple c-string.

Result: Returns an instance of OSString or 0 on error.

withString

Abstract: Static constructor function to create and initialize an instance of OSString from another OSString.

public:

static OSString *withString(const OSString *aString);

Parameters

Name Description

aString An OSString object.

Result: Returns an instance of OSString or 0 on error.

OSSymbol.h

OSSymbol

Member Functions

free

Abstract: A member function to release all resources created or used by the OSString object.

protected:

virtual void free();

This function should not be called directly, use release() instead.

isEqualTo

Abstract: A member function which tests the equality between an OSSymbol object and a simple c-string.

public:

virtual bool isEqualTo(const char *aCString) const;

Parameters

Name Description

aCString The c-string to be compared against the receiver.

Result: Returns true if the OSSymbol's internal string representation is equivalent to the c-string it is being compared against, false otherwise.

isEqualTo

Abstract: A member function which tests the equality between two OSSymbol objects. Two OSSymbol objects are only equivalent when their references are identical

public:

virtual bool isEqualTo(const OSSymbol *aSymbol) const;

Parameters

Name Description

aSymbol The OSSymbol object to be compared against the receiver.

Result: Returns true if the two objects are equivalent, false otherwise.

isEqualTo

Abstract: A member function which tests the equality between an OSSymbol object and and arbitrary OSObject derived object.

public:

virtual bool isEqualTo(const OSObject *obj) const;

Parameters

Name Description

obj The OSObject derived object to be compared against the receiver.

Result: Returns true if the OSSymbol and the OSObject objects are equivalent.

withCString

Abstract: A static constructor function to create an OSSymbol instance from a simple c-string returns an existing OSSymbol object based on the string object given.

public:

static const OSSymbol *withCString(const char *cString);

Parameters

Name Description

cString A c-string.

Result: Returns a unique OSSymbol object for the string given.

withCStringNoCopy

Abstract: A static constructor function to create an OSSymbol instance from a simple c-string, but does not copy the string to the container.

public:

static const OSSymbol *withCStringNoCopy(const char *cString);

Parameters

Name Description

cString A c-string.

Result: Returns a unique OSSymbol object for the string given.

withString

Abstract: A static constructor function to create an OSSymbol instance from an OSString object or returns an existing OSSymbol object based on the OSString object given.

public:

static const OSSymbol *withString(const OSString *aString);

Parameters

Name Description

aString An OSString object.

Result: Returns a unique OSSymbol object for the string given.

OSUnserialize.h

Functions

OSUnserializeXML

Abstract: Recreates an OS Container object from its previously serialized OS Container class instance data.

extern OSObject* OSUnserializeXML(const char *buffer, OSString **errorString = 0);

Parameters

Name Description

buffer pointer to buffer containing XML data representing the object to be recreated.

errorString if this is a valid pointer and the XML parser finds a error in buffer, errorString contains text indicating the line number and type of error encountered.

Result: Pointer to the recreated object, or zero on failure.

Name	Description
`bytes`	A pointer to a block of data to be copied.
`inLength`	The length of the block of data.

Name	Description
`bytes`	A reference to a block of data
`inLength`	The length of the block of data.

Name	Description
`inData`	An OSData object.
`start`	The starting range of data to be copied.
`inLength`	The length in bytes of the data to be copied.

Name	Description
`someData`	A pointer to a block of data.
`inLength`	The length of the block of data.

Name	Description
`bytes`	A buffer of data.
`inLength`	The size of the given buffer.

Name	Description
`bytes`	A reference to a block of data.
`inLength`	The size of the data block.

Name	Description
`inData`	An OSData object which provides the initial data.
`start`	The starting index at which the data will be copied.
`inLength`	The number of bytes to be copied starting at index 'start'.

Name	Description
`dict`	The dictionary contining the objects to be used to populate the receiving dictionary.
`capacity`	The initial storage capacity of the dictionary. If 0, the value of capacity will be set to the number of elements in the dictionary object, else the value of capacity must be greater than or equal to the number of elements in the dictionary object.

Name	Description
`objects`	A static array of OSObject derived objects to be placed into the dictionary.
`keys`	A static array of OSString keys which identify the correspoding objects provided in the 'objects' parameter.
`count`	The number of objects provided to the dictionary.
`capacity`	The initial storage capacity of the dictionary object. If 0, the capacity will be set to the size of 'count', else the capacity must be greater than or equal to the value of 'count'.

Name	Description
`aDictionary`	The dictionary to be compared against the receiver.
`keys`	An OSArray or OSDictionary containing the keys describing the intersecion for the comparison.

Name	Description
`aKey`	A unique OSString identifying the object placed within the collection.
`anObject`	The object to be stored in the dictionary. It is automatically retained.

Name	Description
`aKey`	A unique string identifying the object placed within the collection.
`anObject`	The object to be stored in the dictionary. It is automatically retained.

Name	Description
`aKey`	A unique OSSymbol identifying the object placed within the collection.
`anObject`	The object to be stored in the dictionary. It is automatically retained.

Name	Description
`dict`	A dictionary whose contents will be placed in the new instance.
`capacity`	The initial storage capacity of the dictionary object. If 0, the capacity will be set to the number of elements in the dictionary object, else the capacity must be greater than or equal to the number of elements in the dictionary.

Name	Description
`className`	Name of class. NO QUOTES and NO MACROS.
`superClassName`	Name of super class. NO QUOTES and NO MACROS.

Name	Description
`inClassName`	cString of the name of the class this meta-class represents.
`inSuperClassName`	cString of the name of the super class.
`inClassSize`	sizeof the class.

Name	Description
`name`	Name of the desired class or super class.
`in`	object to be introspected.

Name	Description
`value`	A c-string representation of a numeric value.
`numberOfBits`	The number of bit required to represent the value.

Name	Description
`value`	An integer value.
`numberOfBits`	The number of bit required to represent the value.

Name	Description
`value`	A c-string representing a numeric value.
`numberOfBits`	The number of bit required to represent the value.

Name	Description
`value`	The numeric integer value.
`numberOfBits`	The number of bit required to represent the value.

Name	Description
`typeinst`	Reference instance of an object, desired type.
`inst`	Instance of object to check for type compatibility.

Name	Description
`type`	name of desired class name. Notice that it is assumed that you desire to cast to a pointer to an object of this type. Also type qualifiers, like const, are not recognised and will cause an, usually obscure, compile error.
`inst`	Pointer to object that you wish to attempt to type cast. May be 0.

Name	Description
`mem`	pointer to block of memory
`size`	size of block of memory

Name	Description
`capacity`	The initial storage size in number of objects of the set.
`orderFunc`	A c-style function which implements the sorting algorithm for the set.
`orderingRef`	A ordering context used as a hint for ordering objects within the set.

Name	Description
`index`	The index in the set to place the object.
`anObject`	The object to be placed into the set.

Name	Description
`obj1`	An object from the collection.
`obj2`	An object to be compared to obj1.
`ref`	The ordering conext used by the sorting function as a hint for sorting.

Name	Description
`array`	The OSArray object contining OSObject derived objects used to populate the new OSSet object.
`capacity`	The initial storage capacity of the object. This value must be equal to or larger than the number of objects provided by the OSArray object passed as the first parameter.

Name	Description
`object`	A static array containing OSObject derived objects used to populate the collection.
`count`	The number of objects provided.
`capacity`	The initial storage size of the collection. This value must be equal to or larger than the 'count' parameter.

Name	Description
`array`	The OSSet object contining OSObject derived objects used to populate the new OSSet object.
`capacity`	The initial storage capacity of the object. This value must be equal to or larger than the number of objects provided by the OSSet object passed as the first parameter.