OSSerialize Class Reference (TP40011910 2.0.0) - Apple Developer

OSSerialize Class Reference

Contents
OSSerialize 3
Overview 3
Tasks 3
Miscellaneous 3
Instance Methods 4
addChar 4
addString 4
addXMLEndTag 5
addXMLStartTag 5
clearText 6
previouslySerialized 6
text 7
withCapacity 7
2012-07-23 | Copyright © 2012 Apple Inc. All Rights Reserved.
2

OSSerialize
Inherits from
Availability
Declared in
OSObject
Available in OS X v10.0 and later.
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
addChar (page 4)
Appends a single character to the XML stream.
addString (page 4)
Appends a C string to the XML stream.
2012-07-23 | Copyright © 2012 Apple Inc. All Rights Reserved.
3

OSSerialize
Instance Methods
addXMLEndTag (page 5)
Appends an XML end tag to the XML stream.
addXMLStartTag (page 5)
Appends an XML start tag to the XML stream.
clearText (page 6)
Resets the OSSerialize object.
previouslySerialized (page 6)
Checks whether the object has already been serialized into the XML stream, emitting a reference if it has.
text (page 7)
Returns the XML text serialized so far.
withCapacity (page 7)
Creates and initializes an empty OSSerialize object.
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);
2012-07-23 | Copyright © 2012 Apple Inc. All Rights Reserved.
4

OSSerialize
Instance Methods
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".
2012-07-23 | Copyright © 2012 Apple Inc. All Rights Reserved.
5

OSSerialize
Instance Methods
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.
2012-07-23 | Copyright © 2012 Apple Inc. All Rights Reserved.
6

OSSerialize
Instance Methods
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.
2012-07-23 | Copyright © 2012 Apple Inc. All Rights Reserved.
7

Apple Inc.
Copyright © 2012 Apple Inc.
All rights reserved.
No part of this publication may be reproduced,
stored in a retrieval system, or transmitted, in any
form or by any means, mechanical, electronic,
photocopying, recording, or otherwise, without
prior written permission of Apple Inc., with the
following exceptions: Any person is hereby
authorized to store documentation on a single
computer for personal use only and to print
copies of documentation for personal use
provided that the documentation contains
Apple’s copyright notice.
No licenses, express or implied, are granted with
respect to any of the technology described in this
document. Apple retains all intellectual property
rights associated with the technology described
in this document. This document is intended to
assist application developers to develop
applications only for Apple-labeled computers.
Apple Inc.
1 Infinite Loop
Cupertino, CA 95014
408-996-1010
Apple, the Apple logo, Mac, and OS X are
trademarks of Apple Inc., registered in the U.S.
and other countries.
Even though Apple has reviewed this document,
APPLE MAKES NO WARRANTY OR REPRESENTATION,
EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS
DOCUMENT, ITS QUALITY, ACCURACY,
MERCHANTABILITY, OR FITNESS FOR A PARTICULAR
PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED
“AS IS,” AND YOU, THE READER, ARE ASSUMING THE
ENTIRE RISK AS TO ITS QUALITY AND ACCURACY.
IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,
INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES RESULTING FROM ANY DEFECT OR
INACCURACY IN THIS DOCUMENT, even if advised of
the possibility of such damages.
THE WARRANTY AND REMEDIES SET FORTH ABOVE
ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL
OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer,
agent, or employee is authorized to make any
modification, extension, or addition to this warranty.
Some states do not allow the exclusion or limitation
of implied warranties or liability for incidental or
consequential damages, so the above limitation or
exclusion may not apply to you. This warranty gives
you specific legal rights, and you may also have other
rights which vary from state to state.