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 OSCollection;
  36 class OSSet;
  37 class OSDictionary;
  38
  39 /*!
  40  * @header
  41  *
  42  * @abstract
  43  * This header declares the OSSerialize class.
  44  */
  45
  46
  47 /*!
  48  * @class OSSerialize
  49  *
  50  * @abstract
  51  * OSSerialize coordinates serialization of Libkern C++ objects
  52  * into an XML stream.
  53  *
  54  * @discussion
  55  * This class is for the most part internal to the OSContainer classes,
  56  * used for transferring property tables between the kernel and user space.
  57  * It should not be used directly.
  58  * Classes that participate in serialization
  59  * override the
  60  * <code>@link
  61  * //apple_ref/cpp/instm/OSObject/serialize/virtualbool/(OSSerialize*)
  62  * OSObject::serialize@/link</code> .
  63  * function.
  64  *
  65  * <b>Use Restrictions</b>
  66  *
  67  * With very few exceptions in the I/O Kit, all Libkern-based C++
  68  * classes, functions, and macros are <b>unsafe</b>
  69  * to use in a primary interrupt context.
  70  * Consult the I/O Kit documentation related to primary interrupts
  71  * for more information.
  72  *
  73  * OSSerialize provides no concurrency protection;
  74  * it's up to the usage context to provide any protection necessary.
  75  * Some portions of the I/O Kit, such as
  76  * @link //apple_ref/doc/class/IORegistryEntry IORegistryEntry@/link,
  77  * handle synchronization via defined member functions
  78  * for serializing properties.
  79  */
  80
  81 OSObject *
  82 OSUnserializeBinary(const void *buffer, size_t bufferSize);
  83
  84 class OSSerialize : public OSObject
  85 {
  86     OSDeclareDefaultStructors(OSSerialize)
  87     friend class OSBoolean;
  88
  89 protected:
  90     char         * data;               // container for serialized data
  91     unsigned int   length;             // of serialized data (counting NULL)
  92     unsigned int   capacity;           // of container
  93     unsigned int   capacityIncrement;  // of container
  94
  95     unsigned int   tag;
  96     OSDictionary * tags;               // tags for all objects seen
  97
  98     struct ExpansionData { };
  99
 100     /* Reserved for future use. (Internal use only)  */
 101     ExpansionData *reserved;
 102
 103 #ifdef XNU_KERNEL_PRIVATE
 104 public:
 105     typedef const OSMetaClassBase * (*Editor)(void                  * reference,
 106                                               OSSerialize           * s,
 107                                               OSCollection          * container,
 108                                               const OSSymbol        * name,
 109                                               const OSMetaClassBase * value);
 110 #else
 111     typedef void * Editor;
 112 #endif
 113
 114 private:
 115     bool   binary;
 116     bool   endCollection;
 117     Editor editor;
 118     void * editRef;
 119
 120     bool binarySerialize(const OSMetaClassBase *o);
 121     bool addBinary(const void * data, size_t size);
 122     bool addBinaryObject(const OSMetaClassBase * o, uint32_t key, const void * _bits, size_t size);
 123
 124 public:
 125
 126    /*!
 127     * @function withCapacity
 128     *
 129     * @abstract
 130     * Creates and initializes an empty OSSerialize object.
 131     *
 132     * @param  capacity The initial size of the XML buffer.
 133     *
 134     * @result
 135     * A new instance of OSSerialize
 136     * with a retain count of 1;
 137     * <code>NULL</code> on failure.
 138     *
 139     * @discussion
 140     * The serializer will grow as needed to accommodate more data.
 141     */
 142     static OSSerialize * withCapacity(unsigned int capacity);
 143
 144     static OSSerialize * binaryWithCapacity(unsigned int inCapacity, Editor editor = 0, void * reference = 0);
 145
 146    /*!
 147     * @function text
 148     *
 149     * @abstract
 150     * Returns the XML text serialized so far.
 151     *
 152     * @result
 153     * The nul-terminated XML data serialized so far.
 154     */
 155     virtual char * text() const;
 156
 157
 158    /*!
 159     * @function clearText
 160     *
 161     * @abstract
 162     * Resets the OSSerialize object.
 163     *
 164     * @discussion
 165     * This function is a useful optimization if you are serializing
 166     * the same object repeatedly.
 167     */
 168     virtual void clearText();
 169
 170     // stuff to serialize your object
 171
 172    /*!
 173     * @function previouslySerialized
 174     *
 175     * @abstract
 176     * Checks whether the object has already been serialized
 177     * into the XML stream, emitting a reference if it has.
 178     *
 179     * @param object The object to check.
 180     *
 181     * @result
 182     * <code>true</code> if <code>object</code> has already been serialized
 183     * by this OSSerialize object and a reference
 184     * to it is successfully added to the XML stream,
 185     * <code>false</code> otherwise.
 186     *
 187     *
 188     * @discussion
 189     * This function both reduces the size of generated XML
 190     * by emitting shorter references to existing objects with the same
 191     * value (particularly for OSString, OSSymbol, and OSData),
 192     * and also preserves instance references
 193     * so that the user-space I/O Kit library can reconstruct
 194     * an identical graph of object relationships.
 195     *
 196     * All classes that override
 197     * <code>@link
 198     * //apple_ref/cpp/instm/OSObject/serialize/virtualbool/(OSSerialize*)
 199     * OSObject::serialize@/link</code>.
 200     * should call this function before doing any actual serialization;
 201     * if it returns <code>true</code>, the <code>serialize</code> implementation
 202     * can immediately return <code>true</code>.
 203     */
 204     virtual bool previouslySerialized(const OSMetaClassBase * object);
 205
 206
 207    /*!
 208     * @function addXMLStartTag
 209     *
 210     * @abstract
 211     * Appends an XML start tag to the XML stream.
 212     *
 213     * @param object    The object being serialized.
 214     * @param tagString The name of the XML tag to emit; for example, "string".
 215     *
 216     * @result
 217     * <code>true</code> if an XML start tag for <code>tagString</code>
 218     * is successfully added to the XML stream, <code>false</code> otherwise.
 219     *
 220     * @discussion
 221     * This function emits the named tag,
 222     * enclosed within a pair of angle brackets.
 223     *
 224     * A class that implements serialization should call this function
 225     * with the name of the XML tag that best represents the serialized
 226     * contents of the object.
 227     * A limited number of tags are supported by the user-space
 228     * I/O Kit library:
 229     * <ul>
 230     * <li>array</li>
 231     * <li>dict</li>
 232     * <li>integer</li>
 233     * <li>key</li>
 234     * <li>set</li>
 235     * <li>string</li>
 236     * </ul>
 237     *
 238     * A call to this function must be balanced with one to
 239     * <code>@link addXMLEndTag addXMLEndTag@/link</code>
 240     * using the same <code>tagString</code>.
 241     */
 242     virtual bool addXMLStartTag(
 243         const OSMetaClassBase * object,
 244         const char            * tagString);
 245
 246
 247    /*!
 248     * @function addXMLEndTag
 249     *
 250     * @abstract
 251     * Appends an XML end tag to the XML stream.
 252     *
 253     * @param tagString The name of the XML tag to emit; for example, "string".
 254     *
 255     * @result
 256     * <code>true</code> if an XML end tag for <code>tagString</code>
 257     * is successfully added to the XML stream, <code>false</code> otherwise.
 258     *
 259     * @discussion
 260     * This function emits the named tag,
 261     * preceded by a slash character to indicate the closing of an entity,
 262     * all enclosed within a pair of angle brackets.
 263     *
 264     * A call to this function must balance an earlier call to
 265     * <code>@link addXMLStartTag addXMLStartTag@/link</code>
 266     * using the same <code>tagString</code>.
 267     */
 268     virtual bool addXMLEndTag(const char * tagString);
 269
 270
 271    /*!
 272     * @function addChar
 273     *
 274     * @abstract
 275     * Appends a single character to the XML stream.
 276     *
 277     * @param aChar The character to append to the XML stream.
 278     *
 279     * @result
 280     * <code>true</code> if <code>char</code>
 281     * is successfully added to the XML stream, <code>false</code> otherwise.
 282     */
 283     virtual bool addChar(const char aChar);
 284
 285
 286    /*!
 287     * @function addString
 288     *
 289     * @abstract
 290     * Appends a C string to the XML stream.
 291     *
 292     * @param cString The C string to append to the XML stream.
 293     *
 294     * @result
 295     *  <code>true</code> if <code>cString</code>
 296     * is successfully added to the XML stream, <code>false</code> otherwise.
 297     */
 298     virtual bool addString(const char * cString);
 299
 300     // stuff you should never have to use (in theory)
 301
 302     virtual bool initWithCapacity(unsigned int inCapacity);
 303     virtual unsigned int getLength() const;
 304     virtual unsigned int getCapacity() const;
 305     virtual unsigned int getCapacityIncrement() const;
 306     virtual unsigned int setCapacityIncrement(unsigned increment);
 307     virtual unsigned int ensureCapacity(unsigned int newCapacity);
 308     virtual void free() APPLE_KEXT_OVERRIDE;
 309
 310     OSMetaClassDeclareReservedUnused(OSSerialize, 0);
 311     OSMetaClassDeclareReservedUnused(OSSerialize, 1);
 312     OSMetaClassDeclareReservedUnused(OSSerialize, 2);
 313     OSMetaClassDeclareReservedUnused(OSSerialize, 3);
 314     OSMetaClassDeclareReservedUnused(OSSerialize, 4);
 315     OSMetaClassDeclareReservedUnused(OSSerialize, 5);
 316     OSMetaClassDeclareReservedUnused(OSSerialize, 6);
 317     OSMetaClassDeclareReservedUnused(OSSerialize, 7);
 318 };
 319
 320 // xx-review: this whole class seems to be unused!
 321
 322 typedef bool (*OSSerializerCallback)(void * target, void * ref,
 323                                      OSSerialize * serializer);
 324
 325 class OSSerializer : public OSObject
 326 {
 327     OSDeclareDefaultStructors(OSSerializer)
 328
 329     void * target;
 330     void * ref;
 331     OSSerializerCallback callback;
 332
 333 public:
 334
 335     static OSSerializer * forTarget(
 336         void * target,
 337         OSSerializerCallback callback,
 338         void * ref = 0);
 339
 340     virtual bool serialize(OSSerialize * serializer) const APPLE_KEXT_OVERRIDE;
 341 };
 342
 343 #endif /* _OS_OSSERIALIZE_H */