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-2013, 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 39CF_IMPLICIT_BRIDGING_ENABLED 40CF_EXTERN_C_BEGIN 41 42typedef CF_OPTIONS(CFOptionFlags, CFPropertyListMutabilityOptions) { 43 kCFPropertyListImmutable = 0, 44 kCFPropertyListMutableContainers, 45 kCFPropertyListMutableContainersAndLeaves 46}; 47 48CF_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 obsolete and will be deprecated soon. See CFPropertyListCreateWithData() for a replacement. 59*/ 60CF_EXPORT 61CFPropertyListRef CFPropertyListCreateFromXMLData(CFAllocatorRef allocator, CFDataRef xmlData, CFOptionFlags mutabilityOption, CFStringRef *errorString); 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 obsolete and will be deprecated soon. See CFPropertyListCreateData() for a replacement. 74*/ 75CF_EXPORT 76CFDataRef CFPropertyListCreateXMLData(CFAllocatorRef allocator, CFPropertyListRef propertyList); 77 78CF_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*/ 86CF_EXPORT 87CFPropertyListRef CFPropertyListCreateDeepCopy(CFAllocatorRef allocator, CFPropertyListRef propertyList, CFOptionFlags mutabilityOption); 88 89typedef 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. */ 100CF_EXPORT 101Boolean CFPropertyListIsValid(CFPropertyListRef plist, CFPropertyListFormat format); 102 103#if TARGET_OS_MAC || TARGET_OS_WIN32 || TARGET_OS_EMBEDDED 104CF_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 obsolete and will be deprecated soon. See CFPropertyListWrite() for a replacement. */ 116CF_EXPORT 117CFIndex CFPropertyListWriteToStream(CFPropertyListRef propertyList, CFWriteStreamRef stream, CFPropertyListFormat format, CFStringRef *errorString); 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 obsolete and will be deprecated soon. See CFPropertyListCreateWithStream() for a replacement. */ 131CF_EXPORT 132CFPropertyListRef CFPropertyListCreateFromStream(CFAllocatorRef allocator, CFReadStreamRef stream, CFIndex streamLength, CFOptionFlags mutabilityOption, CFPropertyListFormat *format, CFStringRef *errorString); 133 134CF_IMPLICIT_BRIDGING_ENABLED 135#endif 136 137CF_IMPLICIT_BRIDGING_DISABLED 138 139enum { 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 */ 148CF_EXPORT 149CFPropertyListRef 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. TIf 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 */ 155CF_EXPORT 156CFPropertyListRef 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 */ 160CF_EXPORT 161CFIndex 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 */ 167CF_EXPORT 168CFDataRef CFPropertyListCreateData(CFAllocatorRef allocator, CFPropertyListRef propertyList, CFPropertyListFormat format, CFOptionFlags options, CFErrorRef *error) CF_AVAILABLE(10_6, 4_0); 169 170CF_IMPLICIT_BRIDGING_ENABLED 171 172CF_EXTERN_C_END 173CF_IMPLICIT_BRIDGING_DISABLED 174 175#endif /* ! __COREFOUNDATION_CFPROPERTYLIST__ */ 176 177