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