libkern/libkern/c++/OSSerialize.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. The rights granted to you under the License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28 /* OSSerialize.h created by rsulack on Wen 25-Nov-1998 */
  29
  30 #ifndef _OS_OSSERIALIZE_H
  31 #define _OS_OSSERIALIZE_H
  32
  33 #include <libkern/c++/OSObject.h>
  34
  35 class OSSet;
  36 class OSDictionary;
  37
  38 /*!
  39  * @header
  40  *
  41  * @abstract
  42  * This header declares the OSSerialize class.
  43  */
  44
  45
  46 /*!
  47  * @class OSSerialize
  48  *
  49  * @abstract
  50  * OSSerialize coordinates serialization of Libkern C++ objects
  51  * into an XML stream.
  52  *
  53  * @discussion
  54  * This class is for the most part internal to the OSContainer classes,
  55  * used for transferring property tables between the kernel and user space.
  56  * It should not be used directly.
  57  * Classes that participate in serialization
  58  * override the
  59  * <code>@link
  60  * //apple_ref/cpp/instm/OSObject/serialize/virtualbool/(OSSerialize*)
  61  * OSObject::serialize@/link</code> .
  62  * function.
  63  *
  64  * <b>Use Restrictions</b>
  65  *
  66  * With very few exceptions in the I/O Kit, all Libkern-based C++
  67  * classes, functions, and macros are <b>unsafe</b>
  68  * to use in a primary interrupt context.
  69  * Consult the I/O Kit documentation related to primary interrupts
  70  * for more information.
  71  *
  72  * OSSerialize provides no concurrency protection;
  73  * it's up to the usage context to provide any protection necessary.
  74  * Some portions of the I/O Kit, such as
  75  * @link //apple_ref/doc/class/IORegistryEntry IORegistryEntry@/link,
  76  * handle synchronization via defined member functions
  77  * for serializing properties.
  78  */
  79 class OSSerialize : public OSObject
  80 {
  81     OSDeclareDefaultStructors(OSSerialize)
  82
  83 protected:
  84     char         * data;               // container for serialized data
  85     unsigned int   length;             // of serialized data (counting NULL)
  86     unsigned int   capacity;           // of container
  87     unsigned int   capacityIncrement;  // of container
  88
  89     unsigned int   tag;
  90     OSDictionary * tags;               // tags for all objects seen
  91
  92     struct ExpansionData { };
  93
  94     /* Reserved for future use. (Internal use only)  */
  95     ExpansionData *reserved;
  96
  97
  98 public:
  99
 100    /*!
 101     * @function withCapacity
 102     *
 103     * @abstract
 104     * Creates and initializes an empty OSSerialize object.
 105     *
 106     * @param  capacity The initial size of the XML buffer.
 107     *
 108     * @result
 109     * A new instance of OSSerialize
 110     * with a retain count of 1;
 111     * <code>NULL</code> on failure.
 112     *
 113     * @discussion
 114     * The serializer will grow as needed to accommodate more data.
 115     */
 116     static OSSerialize * withCapacity(unsigned int capacity);
 117
 118    /*!
 119     * @function text
 120     *
 121     * @abstract
 122     * Returns the XML text serialized so far.
 123     *
 124     * @result
 125     * The nul-terminated XML data serialized so far.
 126     */
 127     virtual char * text() const;
 128
 129
 130    /*!
 131     * @function clearText
 132     *
 133     * @abstract
 134     * Resets the OSSerialize object.
 135     *
 136     * @discussion
 137     * This function is a useful optimization if you are serializing
 138     * the same object repeatedly.
 139     */
 140     virtual void clearText();
 141
 142     // stuff to serialize your object
 143
 144    /*!
 145     * @function previouslySerialized
 146     *
 147     * @abstract
 148     * Checks whether the object has already been serialized
 149     * into the XML stream, emitting a reference if it has.
 150     *
 151     * @param object The object to check.
 152     *
 153     * @result
 154     * <code>true</code> if <code>object</code> has already been serialized
 155     * by this OSSerialize object and a reference
 156     * to it is successfully added to the XML stream,
 157     * <code>false</code> otherwise.
 158     *
 159     *
 160     * @discussion
 161     * This function both reduces the size of generated XML
 162     * by emitting shorter references to existing objects with the same
 163     * value (particularly for OSString, OSSymbol, and OSData),
 164     * and also preserves instance references
 165     * so that the user-space I/O Kit library can reconstruct
 166     * an identical graph of object relationships.
 167     *
 168     * All classes that override
 169     * <code>@link
 170     * //apple_ref/cpp/instm/OSObject/serialize/virtualbool/(OSSerialize*)
 171     * OSObject::serialize@/link</code>.
 172     * should call this function before doing any actual serialization;
 173     * if it returns <code>true</code>, the <code>serialize</code> implementation
 174     * can immediately return <code>true</code>.
 175     */
 176     virtual bool previouslySerialized(const OSMetaClassBase * object);
 177
 178
 179    /*!
 180     * @function addXMLStartTag
 181     *
 182     * @abstract
 183     * Appends an XML start tag to the XML stream.
 184     *
 185     * @param object    The object being serialized.
 186     * @param tagString The name of the XML tag to emit; for example, "string".
 187     *
 188     * @result
 189     * <code>true</code> if an XML start tag for <code>tagString</code>
 190     * is successfully added to the XML stream, <code>false</code> otherwise.
 191     *
 192     * @discussion
 193     * This function emits the named tag,
 194     * enclosed within a pair of angle brackets.
 195     *
 196     * A class that implements serialization should call this function
 197     * with the name of the XML tag that best represents the serialized
 198     * contents of the object.
 199     * A limited number of tags are supported by the user-space
 200     * I/O Kit library:
 201     * <ul>
 202     * <li>array</li>
 203     * <li>dict</li>
 204     * <li>integer</li>
 205     * <li>key</li>
 206     * <li>set</li>
 207     * <li>string</li>
 208     * </ul>
 209     *
 210     * A call to this function must be balanced with one to
 211     * <code>@link addXMLEndTag addXMLEndTag@/link</code>
 212     * using the same <code>tagString</code>.
 213     */
 214     virtual bool addXMLStartTag(
 215         const OSMetaClassBase * object,
 216         const char            * tagString);
 217
 218
 219    /*!
 220     * @function addXMLEndTag
 221     *
 222     * @abstract
 223     * Appends an XML end tag to the XML stream.
 224     *
 225     * @param tagString The name of the XML tag to emit; for example, "string".
 226     *
 227     * @result
 228     * <code>true</code> if an XML end tag for <code>tagString</code>
 229     * is successfully added to the XML stream, <code>false</code> otherwise.
 230     *
 231     * @discussion
 232     * This function emits the named tag,
 233     * preceded by a slash character to indicate the closing of an entity,
 234     * all enclosed within a pair of angle brackets.
 235     *
 236     * A call to this function must balance an earlier call to
 237     * <code>@link addXMLStartTag addXMLStartTag@/link</code>
 238     * using the same <code>tagString</code>.
 239     */
 240     virtual bool addXMLEndTag(const char * tagString);
 241
 242
 243    /*!
 244     * @function addChar
 245     *
 246     * @abstract
 247     * Appends a single character to the XML stream.
 248     *
 249     * @param aChar The character to append to the XML stream.
 250     *
 251     * @result
 252     * <code>true</code> if <code>char</code>
 253     * is successfully added to the XML stream, <code>false</code> otherwise.
 254     */
 255     virtual bool addChar(const char aChar);
 256
 257
 258    /*!
 259     * @function addString
 260     *
 261     * @abstract
 262     * Appends a C string to the XML stream.
 263     *
 264     * @param cString The C string to append to the XML stream.
 265     *
 266     * @result
 267     *  <code>true</code> if <code>cString</code>
 268     * is successfully added to the XML stream, <code>false</code> otherwise.
 269     */
 270     virtual bool addString(const char * cString);
 271
 272     // stuff you should never have to use (in theory)
 273
 274     virtual bool initWithCapacity(unsigned int inCapacity);
 275     virtual unsigned int getLength() const;
 276     virtual unsigned int getCapacity() const;
 277     virtual unsigned int getCapacityIncrement() const;
 278     virtual unsigned int setCapacityIncrement(unsigned increment);
 279     virtual unsigned int ensureCapacity(unsigned int newCapacity);
 280     virtual void free();
 281
 282     OSMetaClassDeclareReservedUnused(OSSerialize, 0);
 283     OSMetaClassDeclareReservedUnused(OSSerialize, 1);
 284     OSMetaClassDeclareReservedUnused(OSSerialize, 2);
 285     OSMetaClassDeclareReservedUnused(OSSerialize, 3);
 286     OSMetaClassDeclareReservedUnused(OSSerialize, 4);
 287     OSMetaClassDeclareReservedUnused(OSSerialize, 5);
 288     OSMetaClassDeclareReservedUnused(OSSerialize, 6);
 289     OSMetaClassDeclareReservedUnused(OSSerialize, 7);
 290 };
 291
 292 // xx-review: this whole class seems to be unused!
 293
 294 typedef bool (*OSSerializerCallback)(void * target, void * ref,
 295                                      OSSerialize * serializer);
 296
 297 class OSSerializer : public OSObject
 298 {
 299     OSDeclareDefaultStructors(OSSerializer)
 300
 301     void * target;
 302     void * ref;
 303     OSSerializerCallback callback;
 304
 305 public:
 306
 307     static OSSerializer * forTarget(
 308         void * target,
 309         OSSerializerCallback callback,
 310         void * ref = 0);
 311
 312     virtual bool serialize(OSSerialize * serializer) const;
 313 };
 314
 315 #endif /* _OS_OSSERIALIZE_H */