/* * Copyright (c) 2000 Apple Computer, Inc. All rights reserved. * * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ * * This file contains Original Code and/or Modifications of Original Code * as defined in and that are subject to the Apple Public Source License * Version 2.0 (the 'License'). You may not use this file except in * compliance with the License. The rights granted to you under the License * may not be used to create, or enable the creation or redistribution of, * unlawful or unlicensed copies of an Apple operating system, or to * circumvent, violate, or enable the circumvention or violation of, any * terms of an Apple operating system software license agreement. * * Please obtain a copy of the License at * http://www.opensource.apple.com/apsl/ and read it before using this file. * * The Original Code and all software distributed under the License are * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. * Please see the License for the specific language governing rights and * limitations under the License. * * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ */ /* OSSerialize.h created by rsulack on Wen 25-Nov-1998 */ #ifndef _OS_OSSERIALIZE_H #define _OS_OSSERIALIZE_H #include <libkern/c++/OSObject.h> class OSSet; class OSDictionary; /*! * @header * * @abstract * This header declares the OSSerialize class. */ /*! * @class OSSerialize * * @abstract * OSSerialize coordinates serialization of Libkern C++ objects * into an XML stream. * * @discussion * 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 * <code>@link * //apple_ref/cpp/instm/OSObject/serialize/virtualbool/(OSSerialize*) * OSObject::serialize@/link</code> . * function. * * <b>Use Restrictions</b> * * With very few exceptions in the I/O Kit, all Libkern-based C++ * classes, functions, and macros are <b>unsafe</b> * 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 * @link //apple_ref/doc/class/IORegistryEntry IORegistryEntry@/link, * handle synchronization via defined member functions * for serializing properties. */ class OSSerialize : public OSObject { OSDeclareDefaultStructors(OSSerialize) protected: char * data; // container for serialized data unsigned int length; // of serialized data (counting NULL) unsigned int capacity; // of container unsigned int capacityIncrement; // of container unsigned int tag; OSDictionary * tags; // tags for all objects seen struct ExpansionData { }; /* Reserved for future use. (Internal use only) */ ExpansionData *reserved; public: /*! * @function withCapacity * * @abstract * Creates and initializes an empty OSSerialize object. * * @param capacity The initial size of the XML buffer. * * @result * A new instance of OSSerialize * with a retain count of 1; * <code>NULL</code> on failure. * * @discussion * The serializer will grow as needed to accommodate more data. */ static OSSerialize * withCapacity(unsigned int capacity); /*! * @function text * * @abstract * Returns the XML text serialized so far. * * @result * The nul-terminated XML data serialized so far. */ virtual char * text() const; /*! * @function clearText * * @abstract * Resets the OSSerialize object. * * @discussion * This function is a useful optimization if you are serializing * the same object repeatedly. */ virtual void clearText(); // stuff to serialize your object /*! * @function previouslySerialized * * @abstract * Checks whether the object has already been serialized * into the XML stream, emitting a reference if it has. * * @param object The object to check. * * @result * <code>true</code> if <code>object</code> has already been serialized * by this OSSerialize object and a reference * to it is successfully added to the XML stream, * <code>false</code> 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 * <code>@link * //apple_ref/cpp/instm/OSObject/serialize/virtualbool/(OSSerialize*) * OSObject::serialize@/link</code>. * should call this function before doing any actual serialization; * if it returns <code>true</code>, the <code>serialize</code> implementation * can immediately return <code>true</code>. */ virtual bool previouslySerialized(const OSMetaClassBase * object); /*! * @function addXMLStartTag * * @abstract * Appends an XML start tag to the XML stream. * * @param object The object being serialized. * @param tagString The name of the XML tag to emit; for example, "string". * * @result * <code>true</code> if an XML start tag for <code>tagString</code> * is successfully added to the XML stream, <code>false</code> 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: * <ul> * <li>array</li> * <li>dict</li> * <li>integer</li> * <li>key</li> * <li>set</li> * <li>string</li> * </ul> * * A call to this function must be balanced with one to * <code>@link addXMLEndTag addXMLEndTag@/link</code> * using the same <code>tagString</code>. */ virtual bool addXMLStartTag( const OSMetaClassBase * object, const char * tagString); /*! * @function addXMLEndTag * * @abstract * Appends an XML end tag to the XML stream. * * @param tagString The name of the XML tag to emit; for example, "string". * * @result * <code>true</code> if an XML end tag for <code>tagString</code> * is successfully added to the XML stream, <code>false</code> 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 * <code>@link addXMLStartTag addXMLStartTag@/link</code> * using the same <code>tagString</code>. */ virtual bool addXMLEndTag(const char * tagString); /*! * @function addChar * * @abstract * Appends a single character to the XML stream. * * @param aChar The character to append to the XML stream. * * @result * <code>true</code> if <code>char</code> * is successfully added to the XML stream, <code>false</code> otherwise. */ virtual bool addChar(const char aChar); /*! * @function addString * * @abstract * Appends a C string to the XML stream. * * @param cString The C string to append to the XML stream. * * @result * <code>true</code> if <code>cString</code> * is successfully added to the XML stream, <code>false</code> otherwise. */ virtual bool addString(const char * cString); // stuff you should never have to use (in theory) virtual bool initWithCapacity(unsigned int inCapacity); virtual unsigned int getLength() const; virtual unsigned int getCapacity() const; virtual unsigned int getCapacityIncrement() const; virtual unsigned int setCapacityIncrement(unsigned increment); virtual unsigned int ensureCapacity(unsigned int newCapacity); virtual void free(); OSMetaClassDeclareReservedUnused(OSSerialize, 0); OSMetaClassDeclareReservedUnused(OSSerialize, 1); OSMetaClassDeclareReservedUnused(OSSerialize, 2); OSMetaClassDeclareReservedUnused(OSSerialize, 3); OSMetaClassDeclareReservedUnused(OSSerialize, 4); OSMetaClassDeclareReservedUnused(OSSerialize, 5); OSMetaClassDeclareReservedUnused(OSSerialize, 6); OSMetaClassDeclareReservedUnused(OSSerialize, 7); }; // xx-review: this whole class seems to be unused! typedef bool (*OSSerializerCallback)(void * target, void * ref, OSSerialize * serializer); class OSSerializer : public OSObject { OSDeclareDefaultStructors(OSSerializer) void * target; void * ref; OSSerializerCallback callback; public: static OSSerializer * forTarget( void * target, OSSerializerCallback callback, void * ref = 0); virtual bool serialize(OSSerialize * serializer) const; }; #endif /* _OS_OSSERIALIZE_H */