1/*
2 * Copyright (C) 2009 Apple Inc. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 * 1. Redistributions of source code must retain the above copyright
8 *    notice, this list of conditions and the following disclaimer.
9 * 2. Redistributions in binary form must reproduce the above copyright
10 *    notice, this list of conditions and the following disclaimer in the
11 *    documentation and/or other materials provided with the distribution.
12 *
13 * THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
14 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
16 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE INC. OR
17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
18 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
19 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
20 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
21 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
22 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
23 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
24 */
25
26#ifndef BinaryPropertyList_h
27#define BinaryPropertyList_h
28
29#include <CoreFoundation/CoreFoundation.h>
30
31#include <wtf/Forward.h>
32#include <wtf/Vector.h>
33
34// Writes a limited subset of binary property lists.
35// Covers only what's needed for writing browser history as of this writing.
36class BinaryPropertyListObjectStream {
37public:
38    // Call writeBooleanTrue to write the boolean true value.
39    // A single shared object will be used in the serialized list.
40    virtual void writeBooleanTrue() = 0;
41
42    // Call writeInteger to write an integer value.
43    // A single shared object will be used for each integer in the serialized list.
44    virtual void writeInteger(int) = 0;
45
46    // Call writeString to write a string value.
47    // A single shared object will be used for each string in the serialized list.
48    virtual void writeString(const String&) = 0;
49
50    // Call writeUniqueString instead of writeString when it's unlikely the
51    // string will be written twice in the same property list; this saves hash
52    // table overhead for such strings. A separate object will be used for each
53    // of these strings in the serialized list.
54    virtual void writeUniqueString(const String&) = 0;
55    virtual void writeUniqueString(const char*) = 0;
56
57    // Call writeIntegerArray instead of writeArrayStart/writeArrayEnd for
58    // arrays entirely composed of integers. A single shared object will be used
59    // for each identical array in the serialized list. Warning: The integer
60    // pointer must remain valid until the writeBinaryPropertyList function
61    // returns, because these lists are put into a hash table without copying
62    // them -- that's OK if the client already has a Vector<int>.
63    virtual void writeIntegerArray(const int*, size_t) = 0;
64
65    // After calling writeArrayStart, write array elements.
66    // Then call writeArrayEnd, passing in the result from writeArrayStart.
67    // A separate object will be used for each of these arrays in the serialized list.
68    virtual size_t writeArrayStart() = 0;
69    virtual void writeArrayEnd(size_t resultFromWriteArrayStart) = 0;
70
71    // After calling writeDictionaryStart, write all keys, then all values.
72    // Then call writeDictionaryEnd, passing in the result from writeDictionaryStart.
73    // A separate object will be used for each dictionary in the serialized list.
74    virtual size_t writeDictionaryStart() = 0;
75    virtual void writeDictionaryEnd(size_t resultFromWriteDictionaryStart) = 0;
76
77protected:
78    virtual ~BinaryPropertyListObjectStream() { }
79};
80
81class BinaryPropertyListWriter {
82public:
83    // Calls writeObjects once to prepare for writing and determine how big a
84    // buffer is required. Then calls buffer to get the appropriately-sized
85    // buffer, then calls writeObjects a second time and writes the property list.
86    void writePropertyList();
87
88protected:
89    virtual ~BinaryPropertyListWriter() { }
90
91private:
92    // Called by writePropertyList.
93    // Must call the object stream functions for the objects to be written
94    // into the property list.
95    virtual void writeObjects(BinaryPropertyListObjectStream&) = 0;
96
97    // Called by writePropertyList.
98    // Returns the buffer that the writer should write into.
99    virtual UInt8* buffer(size_t) = 0;
100
101    friend class BinaryPropertyListPlan;
102    friend class BinaryPropertyListSerializer;
103};
104
105#endif // BinaryPropertyList_h
106