OSSerialize |
Inherits from: | |
Declared In: |
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.
Appends a C string to the XML stream.
Appends an XML end tag to the XML stream.
Appends an XML start tag to the XML stream.
Resets the OSSerialize object.
Checks whether the object has already been serialized into the XML stream, emitting a reference if it has.
Returns the XML text serialized so far.
Creates and initializes an empty OSSerialize object.
addChar |
Appends a single character to the XML stream.
public
virtual bool addChar( const char aChar);
aChar
The character to append to the XML stream.
true
if char
is successfully added to the XML stream, false
otherwise.
addString |
Appends a C string to the XML stream.
public
virtual bool addString( const char *cString);
cString
The C string to append to the XML stream.
true
if cString
is successfully added to the XML stream, false
otherwise.
addXMLEndTag |
Appends an XML end tag to the XML stream.
public
virtual bool addXMLEndTag( const char *tagString);
tagString
The name of the XML tag to emit; for example, "string".
true
if an XML end tag for tagString
is successfully added to the XML stream, false
otherwise.
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.
public
virtual bool addXMLStartTag( const OSMetaClassBase *object, const char *tagString);
object
The object being serialized.
tagString
The name of the XML tag to emit; for example, "string".
true
if an XML start tag for tagString
is successfully added to the XML stream, false
otherwise.
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.
public
virtual void clearText();
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.
public
virtual bool previouslySerialized( const OSMetaClassBase *object);
object
The object to check.
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.
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.
public
virtual char * text() const;
The nul-terminated XML data serialized so far.
withCapacity |
Creates and initializes an empty OSSerialize object.
public
static OSSerialize * withCapacity( unsigned int capacity);
capacity
The initial size of the XML buffer.
A new instance of OSSerialize
with a retain count of 1;
NULL
on failure.
The serializer will grow as needed to accommodate more data.
Last Updated: 2010-07-29