CFPropertyList Reference

Overview

CFPropertyList provides functions that convert property list objects to and from several serialized formats such as XML. The CFPropertyListRef type that denotes CFPropertyList objects is an abstract type for property list objects. Depending on the contents of the XML data used to create the property list, CFPropertyListRef can be any of the property list objects: CFData, CFString, CFArray, CFDictionary, CFDate, CFBoolean, and CFNumber. Note that if you use a property list to generate XML, the keys of any dictionaries in the property list must be CFString objects.

It is important to understand that CFPropertyList provides an abstraction for all the property list types—you can think of CFPropertyList in object-oriented terms as being the superclass of CFString, CFNumber, CFDictionary, and so on. When a Core Foundation function returns a CFPropertyListRef, it means that the value may be any of the property list types. For example, CFPreferencesCopyAppValue returns a CFPropertyListRef. This means that the value returned can be a CFString object, a CFNumber object, a CFDictionary object, and so on again. You can use CFGetTypeID to determine what type of object a property list value is.

You use one of the CFPropertyListCreate... functions to create a property list object given an existing property list object, raw XML data (as in a file), or a stream. You can also convert a property list object to XML using the CFPropertyListCreateXMLData function. You use the CFPropertyListWriteToStream function to write a property list to an output stream, and validate a property list object using the CFPropertyListIsValid function. CFPropertyList properly takes care of endian issues—a property list (whether represented by a stream, XML, or a CFData object) created on a PowerPC-based Macintosh is correctly interpreted on an Intel-based Macintosh, and vice versa.

For code examples illustrating how to read and write property list files, see Property List Programming Topics for Core Foundation and in particular Saving and Restoring Property Lists.

Functions by Task

Creating a Property List

• CFPropertyListCreateWithData
• CFPropertyListCreateWithStream
• CFPropertyListCreateDeepCopy
• CFPropertyListCreateFromXMLData
• CFPropertyListCreateFromStream

Exporting a Property List

• CFPropertyListCreateData
• CFPropertyListWrite
• CFPropertyListCreateXMLData
• CFPropertyListWriteToStream

Validating a Property List

• CFPropertyListIsValid

Functions

CFPropertyListCreateData

Returns a CFData object containing a serialized representation of a given property list in a specified format.

CFDataRef CFPropertyListCreateData (
   CFAllocatorRef allocator,
   CFPropertyListRef propertyList,
   CFPropertyListFormat format,
   CFOptionFlags options,
   CFErrorRef *error
);

CFPropertyListCreateDeepCopy

Recursively creates a copy of a given property list.

CFPropertyListRef CFPropertyListCreateDeepCopy (
   CFAllocatorRef allocator,
   CFPropertyListRef propertyList,
   CFOptionFlags mutabilityOption
);

CFPropertyListCreateFromStream

Creates a property list using data from a stream.

CFPropertyListRef CFPropertyListCreateFromStream (
   CFAllocatorRef allocator,
   CFReadStreamRef stream,
   CFIndex streamLength,
   CFOptionFlags mutabilityOption,
   CFPropertyListFormat *format,
   CFStringRef *errorString
);

CFPropertyListCreateFromXMLData

Creates a property list using the specified XML or binary property list data.

CFPropertyListRef CFPropertyListCreateFromXMLData (
   CFAllocatorRef allocator,
   CFDataRef xmlData,
   CFOptionFlags mutabilityOption,
   CFStringRef *errorString
);

CFPropertyListCreateWithData

Creates a property list from a given CFData object.

CFPropertyListRef CFPropertyListCreateWithData (
   CFAllocatorRef allocator,
   CFDataRef data,
   CFOptionFlags options,
   CFPropertyListFormat *format,
   CFErrorRef *error
);

CFPropertyListCreateWithStream

Create and return a property list with a CFReadStream input.

CFPropertyListRef CFPropertyListCreateWithStream (
   CFAllocatorRef allocator,
   CFReadStreamRef stream,
   CFIndex streamLength,
   CFOptionFlags options,
   CFPropertyListFormat *format,
   CFErrorRef *error
);

CFPropertyListCreateXMLData

Creates an XML representation of the specified property list.

CFDataRef CFPropertyListCreateXMLData (
   CFAllocatorRef allocator,
   CFPropertyListRef propertyList
);

CFPropertyListIsValid

Determines if a property list is valid.

Boolean CFPropertyListIsValid (
   CFPropertyListRef plist,
   CFPropertyListFormat format
);

CFPropertyListWrite

Write the bytes of a serialized property list out to a stream.

CFIndex CFPropertyListWrite (
   CFPropertyListRef propertyList,
   CFWriteStreamRef stream,
   CFPropertyListFormat format,
   CFOptionFlags options,
   CFErrorRef *error
);

CFPropertyListWriteToStream

Writes the bytes of a property list serialization out to a stream.

CFIndex CFPropertyListWriteToStream (
   CFPropertyListRef propertyList,
   CFWriteStreamRef stream,
   CFPropertyListFormat format,
   CFStringRef *errorString
);

Data Types

CFPropertyListMutabilityOptions

Type for flags that determine the degree of mutability of newly created property lists.

typedef enum CFPropertyListMutabilityOptions CFPropertyListMutabilityOptions;

CFPropertyListRef

A reference to a CFPropertyList object.

typedef CFTypeRef CFPropertyListRef;

Constants

Property List Formats

Specifies the format of a property list.

enum CFPropertyListFormat {
   kCFPropertyListOpenStepFormat = 1,
   kCFPropertyListXMLFormat_v1_0 = 100,
   kCFPropertyListBinaryFormat_v1_0 = 200
};
typedef enum CFPropertyListFormat CFPropertyListFormat;

Constants

kCFPropertyListOpenStepFormat

OpenStep format (use of this format is discouraged).

Available in iOS 2.0 and later.

Declared in CFPropertyList.h.

kCFPropertyListXMLFormat_v1_0

XML format version 1.0.

Available in iOS 2.0 and later.

Declared in CFPropertyList.h.

kCFPropertyListBinaryFormat_v1_0

Binary format version 1.0.

Available in iOS 2.0 and later.

Declared in CFPropertyList.h.

Property List Mutability Options

Option flags that determine the degree of mutability of newly created property lists.

enum CFPropertyListMutabilityOptions {
   kCFPropertyListImmutable = 0,
   kCFPropertyListMutableContainers = 1,
   kCFPropertyListMutableContainersAndLeaves = 2
};

Constants

kCFPropertyListImmutable

Specifies that the property list should be immutable.

Available in iOS 2.0 and later.

Declared in CFPropertyList.h.

kCFPropertyListMutableContainers

Specifies that the property list should have mutable containers but immutable leaves.

Available in iOS 2.0 and later.

Declared in CFPropertyList.h.

kCFPropertyListMutableContainersAndLeaves

Specifies that the property list should have mutable containers and mutable leaves.

Available in iOS 2.0 and later.

Declared in CFPropertyList.h.

Reading and Writing Error Codes

Error codes for property list reading and writing functions such as CFPropertyListCreateWithData.

enum {
   kCFPropertyListReadCorruptError = 3840,
   kCFPropertyListReadUnknownVersionError = 3841,
   kCFPropertyListReadStreamError = 3842,
   kCFPropertyListWriteStreamError = 3851,
};

Constants

kCFPropertyListReadCorruptError

Signifies an error parsing a property list.

Available in iOS 4.0 and later.

Declared in CFPropertyList.h.

kCFPropertyListReadUnknownVersionError

Signifies the version number in the property list is unknown.

Available in iOS 4.0 and later.

Declared in CFPropertyList.h.

kCFPropertyListReadStreamError

Signifies a stream error reading a property list.

Available in iOS 4.0 and later.

Declared in CFPropertyList.h.

kCFPropertyListWriteStreamError

Signifies a stream error writing a property list.

Available in iOS 4.0 and later.

Declared in CFPropertyList.h.