OSSerialize Class Reference (TP40011910 2.0.0) - Apple Developer
OSSerialize Class Reference (TP40011910 2.0.0) - Apple Developer
OSSerialize Class Reference (TP40011910 2.0.0) - Apple Developer
You also want an ePaper? Increase the reach of your titles
YUMPU automatically turns print PDFs into web optimized ePapers that Google loves.
<strong>OSSerialize</strong> <strong>Class</strong> <strong>Reference</strong>
Contents<br />
<strong>OSSerialize</strong> 3<br />
Overview 3<br />
Tasks 3<br />
Miscellaneous 3<br />
Instance Methods 4<br />
addChar 4<br />
addString 4<br />
addXMLEndTag 5<br />
addXMLStartTag 5<br />
clearText 6<br />
previouslySerialized 6<br />
text 7<br />
withCapacity 7<br />
2012-07-23 | Copyright © 2012 <strong>Apple</strong> Inc. All Rights Reserved.<br />
2
<strong>OSSerialize</strong><br />
Inherits from<br />
Availability<br />
Declared in<br />
OSObject<br />
Available in OS X v10.0 and later.<br />
<strong>OSSerialize</strong>.h<br />
Overview<br />
<strong>OSSerialize</strong> coordinates serialization of Libkern C++ objects into an XML stream.<br />
This class is for the most part internal to the OSContainer classes, used for transferring property tables between<br />
the kernel and user space. It should not be used directly. <strong>Class</strong>es that participate in serialization override the<br />
OSObject::serialize . function.<br />
Use Restrictions<br />
With very few exceptions in the I/O Kit, all Libkern-based C++ classes, functions, and macros are unsafe to use<br />
in a primary interrupt context. Consult the I/O Kit documentation related to primary interrupts for more<br />
information.<br />
<strong>OSSerialize</strong> provides no concurrency protection; it's up to the usage context to provide any protection necessary.<br />
Some portions of the I/O Kit, such as IORegistryEntry, handle synchronization via defined member functions<br />
for serializing properties.<br />
Tasks<br />
Miscellaneous<br />
addChar (page 4)<br />
Appends a single character to the XML stream.<br />
addString (page 4)<br />
Appends a C string to the XML stream.<br />
2012-07-23 | Copyright © 2012 <strong>Apple</strong> Inc. All Rights Reserved.<br />
3
<strong>OSSerialize</strong><br />
Instance Methods<br />
addXMLEndTag (page 5)<br />
Appends an XML end tag to the XML stream.<br />
addXMLStartTag (page 5)<br />
Appends an XML start tag to the XML stream.<br />
clearText (page 6)<br />
Resets the <strong>OSSerialize</strong> object.<br />
previouslySerialized (page 6)<br />
Checks whether the object has already been serialized into the XML stream, emitting a reference if it has.<br />
text (page 7)<br />
Returns the XML text serialized so far.<br />
withCapacity (page 7)<br />
Creates and initializes an empty <strong>OSSerialize</strong> object.<br />
Instance Methods<br />
addChar<br />
Appends a single character to the XML stream.<br />
virtual bool addChar(<br />
const char aChar);<br />
Parameters<br />
aChar<br />
The character to append to the XML stream.<br />
Return Value<br />
true if char is successfully added to the XML stream, false otherwise.<br />
addString<br />
Appends a C string to the XML stream.<br />
virtual bool addString(<br />
const char *cString);<br />
2012-07-23 | Copyright © 2012 <strong>Apple</strong> Inc. All Rights Reserved.<br />
4
<strong>OSSerialize</strong><br />
Instance Methods<br />
Parameters<br />
cString<br />
The C string to append to the XML stream.<br />
Return Value<br />
true if cString is successfully added to the XML stream, false otherwise.<br />
addXMLEndTag<br />
Appends an XML end tag to the XML stream.<br />
virtual bool addXMLEndTag(<br />
const char *tagString);<br />
Parameters<br />
tagString<br />
The name of the XML tag to emit; for example, "string".<br />
Return Value<br />
true if an XML end tag for tagString is successfully added to the XML stream, false otherwise.<br />
Discussion<br />
This function emits the named tag, preceded by a slash character to indicate the closing of an entity, all enclosed<br />
within a pair of angle brackets.<br />
A call to this function must balance an earlier call to addXMLStartTag using the same tagString.<br />
addXMLStartTag<br />
Appends an XML start tag to the XML stream.<br />
virtual bool addXMLStartTag(<br />
const OSMeta<strong>Class</strong>Base *object,<br />
const char *tagString);<br />
Parameters<br />
object<br />
The object being serialized.<br />
tagString<br />
The name of the XML tag to emit; for example, "string".<br />
2012-07-23 | Copyright © 2012 <strong>Apple</strong> Inc. All Rights Reserved.<br />
5
<strong>OSSerialize</strong><br />
Instance Methods<br />
Return Value<br />
true if an XML start tag for tagString is successfully added to the XML stream, false otherwise.<br />
Discussion<br />
This function emits the named tag, enclosed within a pair of angle brackets.<br />
A class that implements serialization should call this function with the name of the XML tag that best represents<br />
the serialized contents of the object. A limited number of tags are supported by the user-space I/O Kit library:<br />
●<br />
array<br />
●<br />
dict<br />
●<br />
integer<br />
●<br />
key<br />
●<br />
set<br />
●<br />
string<br />
A call to this function must be balanced with one to addXMLEndTag using the same tagString.<br />
clearText<br />
Resets the <strong>OSSerialize</strong> object.<br />
virtual void clearText();<br />
Discussion<br />
This function is a useful optimization if you are serializing the same object repeatedly.<br />
previouslySerialized<br />
Checks whether the object has already been serialized into the XML stream, emitting a reference if it has.<br />
virtual bool previouslySerialized(<br />
const OSMeta<strong>Class</strong>Base *object);<br />
Parameters<br />
object<br />
The object to check.<br />
2012-07-23 | Copyright © 2012 <strong>Apple</strong> Inc. All Rights Reserved.<br />
6
<strong>OSSerialize</strong><br />
Instance Methods<br />
Return Value<br />
true if object has already been serialized by this <strong>OSSerialize</strong> object and a reference to it is successfully added<br />
to the XML stream, false otherwise.<br />
Discussion<br />
This function both reduces the size of generated XML by emitting shorter references to existing objects with<br />
the same value (particularly for OSString, OSSymbol, and OSData), and also preserves instance references so<br />
that the user-space I/O Kit library can reconstruct an identical graph of object relationships.<br />
All classes that override OSObject::serialize. should call this function before doing any actual serialization;<br />
if it returns true, the serialize implementation can immediately return true.<br />
text<br />
Returns the XML text serialized so far.<br />
virtual char * text() const;<br />
Return Value<br />
The nul-terminated XML data serialized so far.<br />
withCapacity<br />
Creates and initializes an empty <strong>OSSerialize</strong> object.<br />
static <strong>OSSerialize</strong> * withCapacity(<br />
unsigned int capacity);<br />
Parameters<br />
capacity<br />
The initial size of the XML buffer.<br />
Return Value<br />
A new instance of <strong>OSSerialize</strong> with a retain count of 1; NULL on failure.<br />
Discussion<br />
The serializer will grow as needed to accommodate more data.<br />
2012-07-23 | Copyright © 2012 <strong>Apple</strong> Inc. All Rights Reserved.<br />
7
<strong>Apple</strong> Inc.<br />
Copyright © 2012 <strong>Apple</strong> Inc.<br />
All rights reserved.<br />
No part of this publication may be reproduced,<br />
stored in a retrieval system, or transmitted, in any<br />
form or by any means, mechanical, electronic,<br />
photocopying, recording, or otherwise, without<br />
prior written permission of <strong>Apple</strong> Inc., with the<br />
following exceptions: Any person is hereby<br />
authorized to store documentation on a single<br />
computer for personal use only and to print<br />
copies of documentation for personal use<br />
provided that the documentation contains<br />
<strong>Apple</strong>’s copyright notice.<br />
No licenses, express or implied, are granted with<br />
respect to any of the technology described in this<br />
document. <strong>Apple</strong> retains all intellectual property<br />
rights associated with the technology described<br />
in this document. This document is intended to<br />
assist application developers to develop<br />
applications only for <strong>Apple</strong>-labeled computers.<br />
<strong>Apple</strong> Inc.<br />
1 Infinite Loop<br />
Cupertino, CA 95014<br />
408-996-1010<br />
<strong>Apple</strong>, the <strong>Apple</strong> logo, Mac, and OS X are<br />
trademarks of <strong>Apple</strong> Inc., registered in the U.S.<br />
and other countries.<br />
Even though <strong>Apple</strong> has reviewed this document,<br />
APPLE MAKES NO WARRANTY OR REPRESENTATION,<br />
EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS<br />
DOCUMENT, ITS QUALITY, ACCURACY,<br />
MERCHANTABILITY, OR FITNESS FOR A PARTICULAR<br />
PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED<br />
“AS IS,” AND YOU, THE READER, ARE ASSUMING THE<br />
ENTIRE RISK AS TO ITS QUALITY AND ACCURACY.<br />
IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,<br />
INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL<br />
DAMAGES RESULTING FROM ANY DEFECT OR<br />
INACCURACY IN THIS DOCUMENT, even if advised of<br />
the possibility of such damages.<br />
THE WARRANTY AND REMEDIES SET FORTH ABOVE<br />
ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL<br />
OR WRITTEN, EXPRESS OR IMPLIED. No <strong>Apple</strong> dealer,<br />
agent, or employee is authorized to make any<br />
modification, extension, or addition to this warranty.<br />
Some states do not allow the exclusion or limitation<br />
of implied warranties or liability for incidental or<br />
consequential damages, so the above limitation or<br />
exclusion may not apply to you. This warranty gives<br />
you specific legal rights, and you may also have other<br />
rights which vary from state to state.