/* * Copyright (c) 2005 Apple Computer, Inc. All rights reserved. * * @APPLE_LICENSE_HEADER_START@ * * This file contains Original Code and/or Modifications of Original Code * as defined in and that are subject to the Apple Public Source License * Version 2.0 (the 'License'). You may not use this file except in * compliance with the License. Please obtain a copy of the License at * http://www.opensource.apple.com/apsl/ and read it before using this * file. * * The Original Code and all software distributed under the License are * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. * Please see the License for the specific language governing rights and * limitations under the License. * * @APPLE_LICENSE_HEADER_END@ */ /* CFPropertyList.h Copyright (c) 1998-2005, Apple, Inc. All rights reserved. */ #if !defined(__COREFOUNDATION_CFPROPERTYLIST__) #define __COREFOUNDATION_CFPROPERTYLIST__ 1 #include <CoreFoundation/CFBase.h> #include <CoreFoundation/CFData.h> #include <CoreFoundation/CFString.h> #include <CoreFoundation/CFStream.h> #if defined(__cplusplus) extern "C" { #endif typedef enum { kCFPropertyListImmutable = 0, kCFPropertyListMutableContainers, kCFPropertyListMutableContainersAndLeaves } CFPropertyListMutabilityOptions; /* Creates a property list object from its XML description; xmlData should be the raw bytes of that description, possibly the contents of an XML file. Returns NULL if the data cannot be parsed; if the parse fails and errorString is non-NULL, a human-readable description of the failure is returned in errorString. It is the caller's responsibility to release either the returned object or the error string, whichever is applicable. */ CF_EXPORT CFPropertyListRef CFPropertyListCreateFromXMLData(CFAllocatorRef allocator, CFDataRef xmlData, CFOptionFlags mutabilityOption, CFStringRef *errorString); /* Returns the XML description of the given object; propertyList must be one of the supported property list types, and (for composite types like CFArray and CFDictionary) must not contain any elements that are not themselves of a property list type. If a non-property list type is encountered, NULL is returned. The returned data is appropriate for writing out to an XML file. Note that a data, not a string, is returned because the bytes contain in them a description of the string encoding used. */ CF_EXPORT CFDataRef CFPropertyListCreateXMLData(CFAllocatorRef allocator, CFPropertyListRef propertyList); /* Recursively creates a copy of the given property list (so nested arrays and dictionaries are copied as well as the top-most container). The resulting property list has the mutability characteristics determined by mutabilityOption. */ CF_EXPORT CFPropertyListRef CFPropertyListCreateDeepCopy(CFAllocatorRef allocator, CFPropertyListRef propertyList, CFOptionFlags mutabilityOption); #if MAC_OS_X_VERSION_10_2 <= MAC_OS_X_VERSION_MAX_ALLOWED typedef enum { kCFPropertyListOpenStepFormat = 1, kCFPropertyListXMLFormat_v1_0 = 100, kCFPropertyListBinaryFormat_v1_0 = 200 } CFPropertyListFormat; CF_EXPORT Boolean CFPropertyListIsValid(CFPropertyListRef plist, CFPropertyListFormat format); /* Returns true if the object graph rooted at plist is a valid property list * graph -- that is, no cycles, containing only plist objects, and dictionary * keys are strings. The debugging library version spits out some messages * to be helpful. The plist structure which is to be allowed is given by * the format parameter. */ CF_EXPORT CFIndex CFPropertyListWriteToStream(CFPropertyListRef propertyList, CFWriteStreamRef stream, CFPropertyListFormat format, CFStringRef *errorString); /* Writes the bytes of a plist serialization out to the stream. The * stream must be opened and configured -- the function simply writes * a bunch of bytes to the stream. The output plist format can be chosen. * Leaves the stream open, but note that reading a plist expects the * reading stream to end wherever the writing ended, so that the * end of the plist data can be identified. Returns the number of bytes * written, or 0 on error. Error messages are not currently localized, but * may be in the future, so they are not suitable for comparison. */ CF_EXPORT CFPropertyListRef CFPropertyListCreateFromStream(CFAllocatorRef allocator, CFReadStreamRef stream, CFIndex streamLength, CFOptionFlags mutabilityOption, CFPropertyListFormat *format, CFStringRef *errorString); /* Same as current function CFPropertyListCreateFromXMLData() * but takes a stream instead of data, and works on any plist file format. * CFPropertyListCreateFromXMLData() also works on any plist file format. * The stream must be open and configured -- the function simply reads a bunch * of bytes from it starting at the current location in the stream, to the END * of the stream, which is expected to be the end of the plist, or up to the * number of bytes given by the length parameter if it is not 0. Error messages * are not currently localized, but may be in the future, so they are not * suitable for comparison. */ #endif #if defined(__cplusplus) } #endif #endif /* ! __COREFOUNDATION_CFPROPERTYLIST__ */