CFPropertyList Reference

Inherits From

Not Applicable

Conforms To

Not Applicable

Import Statement

Objective-C

@import CoreFoundation;

Swift

import CoreFoundation

Availability

Not Applicable

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

Creating a Property List


    
      
           CFPropertyListCreateWithData(_:_:_:_:_:)
      
      
           CFPropertyListCreateWithData

Creates a property list from a given CFData object.

Declaration

Swift

func CFPropertyListCreateWithData(_ allocator: CFAllocator!, _ data: CFData!, _ options: CFOptionFlags, _ format: UnsafeMutablePointer<CFPropertyListFormat>, _ error: UnsafeMutablePointer<Unmanaged<CFError>?>) -> Unmanaged<CFPropertyList>!

Objective-C

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

Parameters

`allocator`	The allocator to use to allocate memory for the new property list object. Pass `NULL` or `kCFAllocatorDefault` to use the current default allocator.
`data`	A CFData object containing a serialized representation of a property list.
`options`	A `CFPropertyListMutabilityOptions` constant to specify the mutability of the returned property list—see Property List Mutability Options for possible values.
`format`	If this parameter is non-`NULL`, on return it will be set to the format of the data. See Property List Formats for possible values.
`error`	If this parameter is non-`NULL`, if an error occurs, on return this will contain a CFError error describing the problem. Ownership follows the Create Rule.

Return Value

A new property list created from the data in data. If an error occurs while parsing the data, returns NULL. Ownership follows the Create Rule.

Availability

Available in iOS 4.0 and later.


    
      
           CFPropertyListCreateWithStream(_:_:_:_:_:_:)
      
      
           CFPropertyListCreateWithStream

Create and return a property list with a CFReadStream input.

Declaration

Swift

func CFPropertyListCreateWithStream(_ allocator: CFAllocator!, _ stream: CFReadStream!, _ streamLength: CFIndex, _ options: CFOptionFlags, _ format: UnsafeMutablePointer<CFPropertyListFormat>, _ error: UnsafeMutablePointer<Unmanaged<CFError>?>) -> Unmanaged<CFPropertyList>!

Objective-C

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

Parameters

`allocator`	The allocator to use to allocate memory for the new property list object. Pass `NULL` or `kCFAllocatorDefault` to use the current default allocator.
`stream`	A CFReadStream that contains a serialized representation of a property list.
`streamLength`	The number of bytes to read from the stream. Pass `0` to read until the end of the stream is detected.
`options`	A `CFPropertyListMutabilityOptions` constant to specify the mutability of the returned property list—see Property List Mutability Options for possible values.
`format`	If this parameter is non-`NULL`, on return it will be set to the format of the data. See Property List Formats for possible values.
`error`	If this parameter is non-`NULL`, if an error occurs, on return this will contain a CFError error describing the problem. Ownership follows the Create Rule.

Return Value

A new property list created from the data in stream. If an error occurs while parsing the data, returns NULL. Ownership follows the Create Rule.

Availability

Available in iOS 4.0 and later.


    
      
           CFPropertyListCreateDeepCopy(_:_:_:)
      
      
           CFPropertyListCreateDeepCopy

Recursively creates a copy of a given property list.

Declaration

Swift

func CFPropertyListCreateDeepCopy(_ allocator: CFAllocator!, _ propertyList: CFPropertyList!, _ mutabilityOption: CFOptionFlags) -> CFPropertyList!

Objective-C

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

Parameters

`allocator`	The allocator to use to allocate memory for the new property list. Pass `NULL` or `kCFAllocatorDefault` to use the current default allocator.
`propertyList`	The property list to copy. This may be any of the standard property list objects, for example a CFArray or a CFDictionary object.
`mutabilityOption`	A constant that specifies the degree of mutability of the returned property list. See Property List Mutability Options for descriptions of possible values.

Return Value

A new property list that is a copy of propertyList. Ownership follows the Create Rule.

Discussion

Recursively creates a copy of the given property list so nested arrays and dictionaries are copied as well as the top-most container.

Availability

Available in iOS 2.0 and later.


    
      
           CFPropertyListCreateFromXMLData(_:_:_:_:)
      
      
           CFPropertyListCreateFromXMLData

(iOS 8.0)

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

Declaration

Swift

func CFPropertyListCreateFromXMLData(_ allocator: CFAllocator!, _ xmlData: CFData!, _ mutabilityOption: CFOptionFlags, _ errorString: UnsafeMutablePointer<Unmanaged<CFString>?>) -> Unmanaged<CFPropertyList>!

Objective-C

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

Parameters

`allocator`	The allocator to use to allocate memory for the new property list. Pass `NULL` or `kCFAllocatorDefault` to use the current default allocator.
`data`	The raw bytes to convert into a property list. The bytes may be the content of an XML file or of a binary property list (see Property List Formats).
`mutabilityOption`	A constant that specifies the degree of mutability for the returned property list. See Property List Mutability Options for descriptions of possible values.
`errorString`	On return, `NULL` if the conversion is successful, otherwise a string that describes the nature of the error. Error messages are not localized, but may be in the future, so they are not currently suitable for comparison. Pass `NULL` if you do not wish to receive an error string. Ownership follows the Create Rule.

Return Value

A new property list if the conversion is successful, otherwise NULL. Ownership follows the Create Rule.

Special Considerations

Availability

Available in iOS 2.0 and later.

Deprecated in iOS 8.0.


    
      
           CFPropertyListCreateFromStream(_:_:_:_:_:_:)
      
      
           CFPropertyListCreateFromStream

(iOS 8.0)

Creates a property list using data from a stream.

Declaration

Swift

func CFPropertyListCreateFromStream(_ allocator: CFAllocator!, _ stream: CFReadStream!, _ streamLength: CFIndex, _ mutabilityOption: CFOptionFlags, _ format: UnsafeMutablePointer<CFPropertyListFormat>, _ errorString: UnsafeMutablePointer<Unmanaged<CFString>?>) -> Unmanaged<CFPropertyList>!

Objective-C

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

Parameters

`allocator`	The allocator to use to allocate memory for the new property list. Pass `NULL` or `kCFAllocatorDefault` to use the current default allocator.
`stream`	The stream whose data contains the content. The stream must be opened and configured—this function simply reads bytes from the stream. The stream may contain any supported property list type (see Property List Formats).
`streamLength`	The number of bytes to read. If `0`, this function will read to the end of the stream.
`mutabilityOption`	A constant that specifies the degree of mutability for the returned property list. See Property List Mutability Options for descriptions of possible values.
`format`	A constant that specifies the format of the property list. See Property List Formats for possible values.
`errorString`	On return, `NULL` if the conversion is successful, otherwise a string that describes the nature of the error. Error messages are not localized, but may be in the future, so they are not suitable for comparison. Pass `NULL` if you do not wish to receive an error string. Ownership follows the Create Rule.

Return Value

A new property list initialized with the data contained in stream. Ownership follows the Create Rule.

Discussion

This function simply reads bytes from stream starting at the current location to the end, which is expected to be the end of the property list, or up to the number of bytes specified by streamLength if it is not 0.

Special Considerations

Availability

Available in iOS 2.0 and later.

Deprecated in iOS 8.0.

Exporting a Property List


    
      
           CFPropertyListCreateData(_:_:_:_:_:)
      
      
           CFPropertyListCreateData

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

Declaration

Swift

func CFPropertyListCreateData(_ allocator: CFAllocator!, _ propertyList: CFPropertyList!, _ format: CFPropertyListFormat, _ options: CFOptionFlags, _ error: UnsafeMutablePointer<Unmanaged<CFError>?>) -> Unmanaged<CFData>!

Objective-C

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

Parameters

`allocator`	The allocator to use to allocate memory for the new data object. Pass `NULL` or `kCFAllocatorDefault` to use the current default allocator.
`propertyList`	The property list to write out.
`format`	A CFPropertyListFormat constant to specify the data format. See Property List Formats for possible values.
`options`	This parameter is currently unused and should be set to `0`.
`error`	If this parameter is non-NULL, if an error occurs, on return this will contain a CFError error describing the problem. Ownership follows the Create Rule.

Return Value

A CFData object containing a serialized representation of propertyList in a the format specified by format. Ownership follows the Create Rule.

Discussion

Availability

Available in iOS 4.0 and later.


    
      
           CFPropertyListWrite(_:_:_:_:_:)
      
      
           CFPropertyListWrite

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

Declaration

Swift

func CFPropertyListWrite(_ propertyList: CFPropertyList!, _ stream: CFWriteStream!, _ format: CFPropertyListFormat, _ options: CFOptionFlags, _ error: UnsafeMutablePointer<Unmanaged<CFError>?>) -> CFIndex

Objective-C

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

Parameters

`propertyList`	The property list to write out.
`stream`	The CFWriteStream to which to write the data. The stream must be opened and configured.
`format`	A CFPropertyListFormat constant to specify the data format. See Property List Formats for possible values.
`options`	This parameter is currently unused and should be set to `0`.
`error`	If this parameter is non-NULL, if an error occurs, on return this will contain a CFError error describing the problem. Ownership follows the Create Rule.

Return Value

The number of bytes written to stream. If an error occurs, returns 0.

Availability

Available in iOS 4.0 and later.


    
      
           CFPropertyListCreateXMLData(_:_:)
      
      
           CFPropertyListCreateXMLData

(iOS 8.0)

Creates an XML representation of the specified property list.

Declaration

Swift

func CFPropertyListCreateXMLData(_ allocator: CFAllocator!, _ propertyList: CFPropertyList!) -> Unmanaged<CFData>!

Objective-C

CFDataRef CFPropertyListCreateXMLData ( CFAllocatorRef allocator, CFPropertyListRef propertyList );

Parameters

`allocator`	The allocator to use to allocate memory for the new data object. Pass `NULL` or `kCFAllocatorDefault` to use the current default allocator.
`propertyList`	The property list to convert. This may be any of the standard property list objects, for example a CFArray or a CFDictionary object.

Return Value

A CFData object containing the XML data. Ownership follows the Create Rule.

Special Considerations

Availability

Available in iOS 2.0 and later.

Deprecated in iOS 8.0.


    
      
           CFPropertyListWriteToStream(_:_:_:_:)
      
      
           CFPropertyListWriteToStream

(iOS 8.0)

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

Declaration

Swift

func CFPropertyListWriteToStream(_ propertyList: CFPropertyList!, _ stream: CFWriteStream!, _ format: CFPropertyListFormat, _ errorString: UnsafeMutablePointer<Unmanaged<CFString>?>) -> CFIndex

Objective-C

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

Parameters

`propertyList`	The property list to write out.
`stream`	The stream to write to. The stream must be opened and configured—this function simply writes bytes to the stream.
`format`	A constant that specifies the format used to write `propertyList`. See Property List Formats for possible values.
`errorString`	On return, `NULL` if the conversion is successful, otherwise a string that describes the nature of the errors. Error messages are not localized, but may be in the future, so they are not currently suitable for comparison. Pass `NULL` if you do not wish to receive an error string. Ownership follows the Create Rule.

Return Value

The number of bytes written, or 0 if an error occurred. If 0 is returned, errorString will contain an error message.

Discussion

This function leaves the stream open after reading the content. When reading a property list, this function expects the reading stream to end wherever the writing ended, so that the end of the property list data can be identified.

Special Considerations

Availability

Available in iOS 2.0 and later.

Deprecated in iOS 8.0.

Validating a Property List


    
      
           CFPropertyListIsValid(_:_:)
      
      
           CFPropertyListIsValid

Determines if a property list is valid.

Declaration

Swift

func CFPropertyListIsValid(_ plist: CFPropertyList!, _ format: CFPropertyListFormat) -> Bool

Objective-C

Boolean CFPropertyListIsValid ( CFPropertyListRef plist, CFPropertyListFormat format );

Parameters

`plist`	The property list to validate.
`format`	A constant that specifies the allowable format of `plist`. See Property List Formats for possible values.

Return Value

true if the object graph rooted at plist is a valid property list graph—that is, the property list contains no cycles, only contains property list objects, and all dictionary keys are strings; otherwise false.

Discussion

The debugging library version of this function prints out some useful messages.

Availability

Available in iOS 2.0 and later.

Data Types

Miscellaneous

CFPropertyListRef CFPropertyListRef

A reference to a CFPropertyList object.

Declaration

Swift

typealias CFPropertyListRef = CFPropertyList

Objective-C

typedef CFTypeRef CFPropertyListRef;

Discussion

This is an abstract type for property list objects. The return value of the CFPropertyListCreateFromXMLData function depends on the contents of the given XML data. CFPropertyListRef can be a reference to any of the property list objects: CFData, CFString, CFArray, CFDictionary, CFDate, CFBoolean, and CFNumber.

Import Statement

Objective-C

@import CoreFoundation;

Swift

import CoreFoundation

Availability

Available in iOS 2.0 and later.
CFPropertyListMutabilityOptions CFPropertyListMutabilityOptions

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

Declaration

Swift

struct CFPropertyListMutabilityOptions : OptionSetType { init(rawValue rawValue: CFOptionFlags) static var Immutable: CFPropertyListMutabilityOptions { get } static var MutableContainers: CFPropertyListMutabilityOptions { get } static var MutableContainersAndLeaves: CFPropertyListMutabilityOptions { get } }

Objective-C

typedef enum CFPropertyListMutabilityOptions CFPropertyListMutabilityOptions;

Discussion

See Property List Mutability Options for possible values.

Import Statement

Objective-C

@import CoreFoundation;

Swift

import CoreFoundation

Availability

Available in iOS 2.0 and later.

Constants

Miscellaneous

CFPropertyListFormat
Specifies the format of a property list.

Declaration

Swift

enum CFPropertyListFormat : CFIndex { case OpenStepFormat case XMLFormat_v1_0 case BinaryFormat_v1_0 }

Objective-C

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

Constants
- OpenStepFormat
  
  kCFPropertyListOpenStepFormat
  
  OpenStep format (use of this format is discouraged).
  
  Available in iOS 2.0 and later.
- XMLFormat_v1_0
  
  kCFPropertyListXMLFormat_v1_0
  
  XML format version 1.0.
  
  Available in iOS 2.0 and later.
- BinaryFormat_v1_0
  
  kCFPropertyListBinaryFormat_v1_0
  
  Binary format version 1.0.
  
  Available in iOS 2.0 and later.
Import Statement

Objective-C

@import CoreFoundation;

Swift

import CoreFoundation

Availability

Available in iOS 2.0 and later.
Property List Mutability Options
Option flags that determine the degree of mutability of newly created property lists.

Declaration

Swift

struct CFPropertyListMutabilityOptions : OptionSetType { init(rawValue rawValue: CFOptionFlags) static var Immutable: CFPropertyListMutabilityOptions { get } static var MutableContainers: CFPropertyListMutabilityOptions { get } static var MutableContainersAndLeaves: CFPropertyListMutabilityOptions { get } }

Objective-C

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

Constants
- Immutable
  
  kCFPropertyListImmutable
  
  Specifies that the property list should be immutable.
  
  Available in iOS 2.0 and later.
- MutableContainers
  
  kCFPropertyListMutableContainers
  
  Specifies that the property list should have mutable containers but immutable leaves.
  
  Available in iOS 2.0 and later.
- MutableContainersAndLeaves
  
  kCFPropertyListMutableContainersAndLeaves
  
  Specifies that the property list should have mutable containers and mutable leaves.
  
  Available in iOS 2.0 and later.
Reading and Writing Error Codes
Error codes for property list reading and writing functions such as CFPropertyListCreateWithData.

Declaration

Swift

var kCFPropertyListReadCorruptError: CFIndex { get } var kCFPropertyListReadUnknownVersionError: CFIndex { get } var kCFPropertyListReadStreamError: CFIndex { get } var kCFPropertyListWriteStreamError: CFIndex { get }

Objective-C

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

Constants
- kCFPropertyListReadCorruptError
  
  kCFPropertyListReadCorruptError
  
  Signifies an error parsing a property list.
  
  Available in iOS 4.0 and later.
- kCFPropertyListReadUnknownVersionError
  
  kCFPropertyListReadUnknownVersionError
  
  Signifies the version number in the property list is unknown.
  
  Available in iOS 4.0 and later.
- kCFPropertyListReadStreamError
  
  kCFPropertyListReadStreamError
  
  Signifies a stream error reading a property list.
  
  Available in iOS 4.0 and later.
- kCFPropertyListWriteStreamError
  
  kCFPropertyListWriteStreamError
  
  Signifies a stream error writing a property list.
  
  Available in iOS 4.0 and later.