OSSerialize

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

Overview

OSSerialize coordinates serialization of Libkern C++ objects into an XML stream.

This class is for the most part internal to the OSContainer classes, used for transferring property tables between the kernel and user space. It should not be used directly. Classes that participate in serialization override the OSObject::serialize . function.

Use Restrictions

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

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

Tasks

Miscellaneous

Instance Methods

addChar

Appends a single character to the XML stream.

virtual bool addChar( const char aChar);
Parameters
aChar

The character to append to the XML stream.

Return Value

true if char is successfully added to the XML stream, false otherwise.

addString

Appends a C string to the XML stream.

virtual bool addString( const char *cString);
Parameters
cString

The C string to append to the XML stream.

Return Value

true if cString is successfully added to the XML stream, false otherwise.

addXMLEndTag

Appends an XML end tag to the XML stream.

virtual bool addXMLEndTag( const char *tagString);
Parameters
tagString

The name of the XML tag to emit; for example, "string".

Return Value

true if an XML end tag for tagString is successfully added to the XML stream, false otherwise.

Discussion

This function emits the named tag, preceded by a slash character to indicate the closing of an entity, all enclosed within a pair of angle brackets.

A call to this function must balance an earlier call to addXMLStartTag using the same tagString.

addXMLStartTag

Appends an XML start tag to the XML stream.

virtual bool addXMLStartTag( const OSMetaClassBase *object, const char *tagString);
Parameters
object

The object being serialized.

tagString

The name of the XML tag to emit; for example, "string".

Return Value

true if an XML start tag for tagString is successfully added to the XML stream, false otherwise.

Discussion

This function emits the named tag, enclosed within a pair of angle brackets.

A class that implements serialization should call this function with the name of the XML tag that best represents the serialized contents of the object. A limited number of tags are supported by the user-space I/O Kit library:

  • array

  • dict

  • integer

  • key

  • set

  • string

A call to this function must be balanced with one to addXMLEndTag using the same tagString.

clearText

Resets the OSSerialize object.

virtual void clearText();
Discussion

This function is a useful optimization if you are serializing the same object repeatedly.

previouslySerialized

Checks whether the object has already been serialized into the XML stream, emitting a reference if it has.

virtual bool previouslySerialized( const OSMetaClassBase *object);
Parameters
object

The object to check.

Return Value

true if object has already been serialized by this OSSerialize object and a reference to it is successfully added to the XML stream, false otherwise.

Discussion

This function both reduces the size of generated XML by emitting shorter references to existing objects with the same value (particularly for OSString, OSSymbol, and OSData), and also preserves instance references so that the user-space I/O Kit library can reconstruct an identical graph of object relationships.

All classes that override OSObject::serialize. should call this function before doing any actual serialization; if it returns true, the serialize implementation can immediately return true.

text

Returns the XML text serialized so far.

virtual char * text() const;
Return Value

The nul-terminated XML data serialized so far.

withCapacity

Creates and initializes an empty OSSerialize object.

static OSSerialize * withCapacity( unsigned int capacity);
Parameters
capacity

The initial size of the XML buffer.

Return Value

A new instance of OSSerialize with a retain count of 1; NULL on failure.

Discussion

The serializer will grow as needed to accommodate more data.