Parsing.subproj/CFPropertyList.h

   1 /*
   2  * Copyright (c) 2005 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_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. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23 /*      CFPropertyList.h
  24         Copyright (c) 1998-2005, Apple, Inc. All rights reserved.
  25 */
  26
  27 #if !defined(__COREFOUNDATION_CFPROPERTYLIST__)
  28 #define __COREFOUNDATION_CFPROPERTYLIST__ 1
  29
  30 #include <CoreFoundation/CFBase.h>
  31 #include <CoreFoundation/CFData.h>
  32 #include <CoreFoundation/CFString.h>
  33 #include <CoreFoundation/CFStream.h>
  34
  35 #if defined(__cplusplus)
  36 extern "C" {
  37 #endif
  38
  39 typedef enum {
  40     kCFPropertyListImmutable = 0,
  41     kCFPropertyListMutableContainers,
  42     kCFPropertyListMutableContainersAndLeaves
  43 } CFPropertyListMutabilityOptions;
  44
  45 /*
  46         Creates a property list object from its XML description; xmlData should
  47         be the raw bytes of that description, possibly the contents of an XML
  48         file. Returns NULL if the data cannot be parsed; if the parse fails
  49         and errorString is non-NULL, a human-readable description of the failure
  50         is returned in errorString. It is the caller's responsibility to release
  51         either the returned object or the error string, whichever is applicable.
  52 */
  53 CF_EXPORT
  54 CFPropertyListRef CFPropertyListCreateFromXMLData(CFAllocatorRef allocator, CFDataRef xmlData, CFOptionFlags mutabilityOption, CFStringRef *errorString);
  55
  56 /*
  57         Returns the XML description of the given object; propertyList must
  58         be one of the supported property list types, and (for composite types
  59         like CFArray and CFDictionary) must not contain any elements that
  60         are not themselves of a property list type. If a non-property list
  61         type is encountered, NULL is returned. The returned data is
  62         appropriate for writing out to an XML file. Note that a data, not a
  63         string, is returned because the bytes contain in them a description
  64         of the string encoding used.
  65 */
  66 CF_EXPORT
  67 CFDataRef CFPropertyListCreateXMLData(CFAllocatorRef allocator, CFPropertyListRef propertyList);
  68
  69 /*
  70         Recursively creates a copy of the given property list (so nested arrays
  71         and dictionaries are copied as well as the top-most container). The
  72         resulting property list has the mutability characteristics determined
  73         by mutabilityOption.
  74 */
  75 CF_EXPORT
  76 CFPropertyListRef CFPropertyListCreateDeepCopy(CFAllocatorRef allocator, CFPropertyListRef propertyList, CFOptionFlags mutabilityOption);
  77
  78 #if MAC_OS_X_VERSION_10_2 <= MAC_OS_X_VERSION_MAX_ALLOWED
  79
  80 typedef enum {
  81     kCFPropertyListOpenStepFormat = 1,
  82     kCFPropertyListXMLFormat_v1_0 = 100,
  83     kCFPropertyListBinaryFormat_v1_0 = 200
  84 } CFPropertyListFormat;
  85
  86 CF_EXPORT
  87 Boolean CFPropertyListIsValid(CFPropertyListRef plist, CFPropertyListFormat format);
  88
  89 /* Returns true if the object graph rooted at plist is a valid property list
  90  * graph -- that is, no cycles, containing only plist objects, and dictionary
  91  * keys are strings. The debugging library version spits out some messages
  92  * to be helpful. The plist structure which is to be allowed is given by
  93  * the format parameter. */
  94
  95 CF_EXPORT
  96 CFIndex CFPropertyListWriteToStream(CFPropertyListRef propertyList, CFWriteStreamRef stream, CFPropertyListFormat format, CFStringRef *errorString);
  97
  98 /* Writes the bytes of a plist serialization out to the stream.  The
  99  * stream must be opened and configured -- the function simply writes
 100  * a bunch of bytes to the stream. The output plist format can be chosen.
 101  * Leaves the stream open, but note that reading a plist expects the
 102  * reading stream to end wherever the writing ended, so that the
 103  * end of the plist data can be identified. Returns the number of bytes
 104  * written, or 0 on error. Error messages are not currently localized, but
 105  * may be in the future, so they are not suitable for comparison. */
 106
 107 CF_EXPORT
 108 CFPropertyListRef CFPropertyListCreateFromStream(CFAllocatorRef allocator, CFReadStreamRef stream, CFIndex streamLength, CFOptionFlags mutabilityOption, CFPropertyListFormat *format, CFStringRef *errorString);
 109
 110 /* Same as current function CFPropertyListCreateFromXMLData()
 111  * but takes a stream instead of data, and works on any plist file format.
 112  * CFPropertyListCreateFromXMLData() also works on any plist file format.
 113  * The stream must be open and configured -- the function simply reads a bunch
 114  * of bytes from it starting at the current location in the stream, to the END
 115  * of the stream, which is expected to be the end of the plist, or up to the
 116  * number of bytes given by the length parameter if it is not 0. Error messages
 117  * are not currently localized, but may be in the future, so they are not
 118  * suitable for comparison. */
 119
 120 #endif
 121
 122 #if defined(__cplusplus)
 123 }
 124 #endif
 125
 126 #endif /* ! __COREFOUNDATION_CFPROPERTYLIST__ */
 127