Mac Developer Library

Developer

OSSerialize Class Reference

Options
Deployment Target:

On This Page
Language:

OSSerialize

Inheritance


  • OSSerialize

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.0 and later.

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.

  • Appends a single character to the XML stream.

    Declaration

    C++

    virtual bool addChar( const charaChar);

    Parameters

    aChar

    The character to append to the XML stream.

    Return Value

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

  • Appends a C string to the XML stream.

    Declaration

    C++

    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.

  • Appends an XML end tag to the XML stream.

    Declaration

    C++

    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.

  • Appends an XML start tag to the XML stream.

    Declaration

    C++

    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.

  • Resets the OSSerialize object.

    Declaration

    C++

    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.

    Declaration

    C++

    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.

  • Returns the XML text serialized so far.

    Declaration

    C++

    virtual char * text() const;

    Return Value

    The nul-terminated XML data serialized so far.

  • Creates and initializes an empty OSSerialize object.

    Declaration

    C++

    static OSSerialize * withCapacity( unsigned intcapacity);

    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.