OSSerialize

Overview

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

Discussion

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.

Functions

addChar

Appends a single character to the XML stream.

addString

Appends a C string to the XML stream.

addXMLEndTag

Appends an XML end tag to the XML stream.

addXMLStartTag

Appends an XML start tag to the XML stream.

clearText

Resets the OSSerialize object.

previouslySerialized

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

text

Returns the XML text serialized so far.

withCapacity

Creates and initializes an empty OSSerialize object.

Appends a single character to the XML stream.

public

virtual bool addChar(
    const char aChar); 

Parameters

Return Value

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

Appends a C string to the XML stream.

public

virtual bool addString(
    const char * cString); 

Parameters

Return Value

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

Appends an XML end tag to the XML stream.

public

virtual bool addXMLEndTag(
    const char * tagString); 

Parameters

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.

Appends an XML start tag to the XML stream.

public

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

Parameters

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.

Resets the OSSerialize object.

public

virtual void clearText(); 

Discussion

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

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

public

virtual bool previouslySerialized(
    const OSMetaClassBase * object); 

Parameters

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.

Returns the XML text serialized so far.

public

virtual char * text() const; 

Return Value

The nul-terminated XML data serialized so far.

Creates and initializes an empty OSSerialize object.

public

static OSSerialize * withCapacity(
    unsigned int capacity); 

Parameters

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.

Last Updated: 2009-10-14