CFPropertyList.h

   1 /*
   2  * Copyright (c) 2014 Apple 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
  24 /*      CFPropertyList.h
  25         Copyright (c) 1998-2014, Apple Inc. All rights reserved.
  26 */
  27
  28 #if !defined(__COREFOUNDATION_CFPROPERTYLIST__)
  29 #define __COREFOUNDATION_CFPROPERTYLIST__ 1
  30
  31 #include <CoreFoundation/CFBase.h>
  32 #include <CoreFoundation/CFData.h>
  33 #include <CoreFoundation/CFString.h>
  34 #include <CoreFoundation/CFError.h>
  35 #if TARGET_OS_MAC || TARGET_OS_WIN32 || TARGET_OS_EMBEDDED
  36 #include <CoreFoundation/CFStream.h>
  37 #endif
  38
  39 CF_IMPLICIT_BRIDGING_ENABLED
  40 CF_EXTERN_C_BEGIN
  41
  42 typedef CF_OPTIONS(CFOptionFlags, CFPropertyListMutabilityOptions) {
  43     kCFPropertyListImmutable = 0,
  44     kCFPropertyListMutableContainers,
  45     kCFPropertyListMutableContainersAndLeaves
  46 };
  47
  48 CF_IMPLICIT_BRIDGING_DISABLED
  49
  50 /*
  51         Creates a property list object from its XML description; xmlData should
  52         be the raw bytes of that description, possibly the contents of an XML
  53         file. Returns NULL if the data cannot be parsed; if the parse fails
  54         and errorString is non-NULL, a human-readable description of the failure
  55         is returned in errorString. It is the caller's responsibility to release
  56         either the returned object or the error string, whichever is applicable.
  57
  58         This function is deprecated. See CFPropertyListCreateWithData() for a replacement.
  59 */
  60 CF_EXPORT
  61 CFPropertyListRef CFPropertyListCreateFromXMLData(CFAllocatorRef allocator, CFDataRef xmlData, CFOptionFlags mutabilityOption, CFStringRef *errorString) CF_DEPRECATED(10_0, 10_10, 2_0, 8_0, "Use CFPropertyListCreateWithData instead.");
  62
  63 /*
  64         Returns the XML description of the given object; propertyList must
  65         be one of the supported property list types, and (for composite types
  66         like CFArray and CFDictionary) must not contain any elements that
  67         are not themselves of a property list type. If a non-property list
  68         type is encountered, NULL is returned. The returned data is
  69         appropriate for writing out to an XML file. Note that a data, not a
  70         string, is returned because the bytes contain in them a description
  71         of the string encoding used.
  72
  73         This function is deprecated. See CFPropertyListCreateData() for a replacement.
  74 */
  75 CF_EXPORT
  76 CFDataRef CFPropertyListCreateXMLData(CFAllocatorRef allocator, CFPropertyListRef propertyList) CF_DEPRECATED(10_0, 10_10, 2_0, 8_0, "Use CFPropertyListCreateData instead.");
  77
  78 CF_IMPLICIT_BRIDGING_ENABLED
  79
  80 /*
  81         Recursively creates a copy of the given property list (so nested arrays
  82         and dictionaries are copied as well as the top-most container). The
  83         resulting property list has the mutability characteristics determined
  84         by mutabilityOption.
  85 */
  86 CF_EXPORT
  87 CFPropertyListRef CFPropertyListCreateDeepCopy(CFAllocatorRef allocator, CFPropertyListRef propertyList, CFOptionFlags mutabilityOption);
  88
  89 typedef CF_ENUM(CFIndex, CFPropertyListFormat) {
  90     kCFPropertyListOpenStepFormat = 1,
  91     kCFPropertyListXMLFormat_v1_0 = 100,
  92     kCFPropertyListBinaryFormat_v1_0 = 200
  93 };
  94
  95 /* Returns true if the object graph rooted at plist is a valid property list
  96  * graph -- that is, no cycles, containing only plist objects, and dictionary
  97  * keys are strings. The debugging library version spits out some messages
  98  * to be helpful. The plist structure which is to be allowed is given by
  99  * the format parameter. */
 100 CF_EXPORT
 101 Boolean CFPropertyListIsValid(CFPropertyListRef plist, CFPropertyListFormat format);
 102
 103 #if TARGET_OS_MAC || TARGET_OS_WIN32 || TARGET_OS_EMBEDDED
 104 CF_IMPLICIT_BRIDGING_DISABLED
 105
 106 /* Writes the bytes of a plist serialization out to the stream.  The
 107  * stream must be opened and configured -- the function simply writes
 108  * a bunch of bytes to the stream. The output plist format can be chosen.
 109  * Leaves the stream open, but note that reading a plist expects the
 110  * reading stream to end wherever the writing ended, so that the
 111  * end of the plist data can be identified. Returns the number of bytes
 112  * written, or 0 on error. Error messages are not currently localized, but
 113  * may be in the future, so they are not suitable for comparison.
 114  *
 115  * This function is deprecated. See CFPropertyListWrite() for a replacement. */
 116 CF_EXPORT
 117 CFIndex CFPropertyListWriteToStream(CFPropertyListRef propertyList, CFWriteStreamRef stream, CFPropertyListFormat format, CFStringRef *errorString) CF_DEPRECATED(10_2, 10_10, 2_0, 8_0, "Use CFPropertyListWrite instead.");
 118
 119
 120 /* Same as current function CFPropertyListCreateFromXMLData()
 121  * but takes a stream instead of data, and works on any plist file format.
 122  * CFPropertyListCreateFromXMLData() also works on any plist file format.
 123  * The stream must be open and configured -- the function simply reads a bunch
 124  * of bytes from it starting at the current location in the stream, to the END
 125  * of the stream, which is expected to be the end of the plist, or up to the
 126  * number of bytes given by the length parameter if it is not 0. Error messages
 127  * are not currently localized, but may be in the future, so they are not
 128  * suitable for comparison.
 129  *
 130  * This function is deprecated. See CFPropertyListCreateWithStream() for a replacement. */
 131 CF_EXPORT
 132 CFPropertyListRef CFPropertyListCreateFromStream(CFAllocatorRef allocator, CFReadStreamRef stream, CFIndex streamLength, CFOptionFlags mutabilityOption, CFPropertyListFormat *format, CFStringRef *errorString) CF_DEPRECATED(10_2, 10_10, 2_0, 8_0, "Use CFPropertyListCreateWithStream instead.");
 133
 134 CF_IMPLICIT_BRIDGING_ENABLED
 135 #endif
 136
 137 CF_IMPLICIT_BRIDGING_DISABLED
 138
 139 enum {
 140     kCFPropertyListReadCorruptError = 3840,              // Error parsing a property list
 141     kCFPropertyListReadUnknownVersionError = 3841,       // The version number in the property list is unknown
 142     kCFPropertyListReadStreamError = 3842,               // Stream error reading a property list
 143     kCFPropertyListWriteStreamError = 3851,              // Stream error writing a property list
 144 } CF_ENUM_AVAILABLE(10_6, 4_0);
 145
 146 /* Create a property list with a CFData input. If the format parameter is non-NULL, it will be set to the format of the data after parsing is complete. The options parameter is used to specify CFPropertyListMutabilityOptions. If an error occurs while parsing the data, the return value will be NULL. Additionally, if an error occurs and the error parameter is non-NULL, the error parameter will be set to a CFError describing the problem, which the caller must release. If the parse succeeds, the returned value is a reference to the new property list. It is the responsibility of the caller to release this value.
 147  */
 148 CF_EXPORT
 149 CFPropertyListRef CFPropertyListCreateWithData(CFAllocatorRef allocator, CFDataRef data, CFOptionFlags options, CFPropertyListFormat *format, CFErrorRef *error) CF_AVAILABLE(10_6, 4_0);
 150
 151 #if TARGET_OS_MAC || TARGET_OS_WIN32 || TARGET_OS_EMBEDDED
 152
 153 /* Create and return a property list with a CFReadStream input. If the format parameter is non-NULL, it will be set to the format of the data after parsing is complete. The options parameter is used to specify CFPropertyListMutabilityOptions. The streamLength parameter specifies the number of bytes to read from the stream. Set streamLength to 0 to read until the end of the stream is detected. If an error occurs while parsing the data, the return value will be NULL. Additionally, if an error occurs and the error parameter is non-NULL, the error parameter will be set to a CFError describing the problem, which the caller must release. If the parse succeeds, the returned value is a reference to the new property list. It is the responsibility of the caller to release this value.
 154  */
 155 CF_EXPORT
 156 CFPropertyListRef CFPropertyListCreateWithStream(CFAllocatorRef allocator, CFReadStreamRef stream, CFIndex streamLength, CFOptionFlags options, CFPropertyListFormat *format, CFErrorRef *error) CF_AVAILABLE(10_6, 4_0);
 157
 158 /* Write the bytes of a serialized property list out to a stream. The stream must be opened and configured. The format of the property list can be chosen with the format parameter. The options parameter is currently unused and should be set to 0. The return value is the number of bytes written or 0 in the case of an error. If an error occurs and the error parameter is non-NULL, the error parameter will be set to a CFError describing the problem, which the caller must release.
 159  */
 160 CF_EXPORT
 161 CFIndex CFPropertyListWrite(CFPropertyListRef propertyList, CFWriteStreamRef stream, CFPropertyListFormat format, CFOptionFlags options, CFErrorRef *error) CF_AVAILABLE(10_6, 4_0);
 162
 163 #endif
 164
 165 /* Create a CFData with the bytes of a serialized property list. The format of the property list can be chosen with the format parameter. The options parameter is currently unused and should be set to 0. If an error occurs while parsing the data, the return value will be NULL. Additionally, if an error occurs and the error parameter is non-NULL, the error parameter will be set to a CFError describing the problem, which the caller must release. If the conversion succeeds, the returned value is a reference to the created data. It is the responsibility of the caller to release this value.
 166  */
 167 CF_EXPORT
 168 CFDataRef CFPropertyListCreateData(CFAllocatorRef allocator, CFPropertyListRef propertyList, CFPropertyListFormat format, CFOptionFlags options, CFErrorRef *error) CF_AVAILABLE(10_6, 4_0);
 169
 170 CF_IMPLICIT_BRIDGING_ENABLED
 171
 172 CF_EXTERN_C_END
 173 CF_IMPLICIT_BRIDGING_DISABLED
 174
 175 #endif /* ! __COREFOUNDATION_CFPROPERTYLIST__ */
 176