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 35class OSSet; 36class 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 */ 79class OSSerialize : public OSObject 80{ 81 OSDeclareDefaultStructors(OSSerialize) 82 83protected: 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 98public: 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 294typedef bool (*OSSerializerCallback)(void * target, void * ref, 295 OSSerialize * serializer); 296 297class OSSerializer : public OSObject 298{ 299 OSDeclareDefaultStructors(OSSerializer) 300 301 void * target; 302 void * ref; 303 OSSerializerCallback callback; 304 305public: 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 */ 316