---

NSPropertyListSerialization Class Reference

Overview

The NSPropertyListSerialization class provides methods that convert property list objects to and from several serialized formats. Property list objects include NSData, NSString, NSArray, NSDictionary, NSDate, and NSNumber objects. These objects are toll-free bridged with their respective Core Foundation types (CFData, CFString, and so on). For more about toll-free bridging, see Interchangeable Data Types.

Property list serialization automatically takes account of endianness on different platforms—for example, you can correctly read on an Intel-based Macintosh a binary property list created on a PowerPC-based Macintosh.

Tasks

Serializing a Property List

• + dataFromPropertyList:format:errorDescription:

Deserializing a Property List

• + propertyListFromData:mutabilityOption:format:errorDescription:

Validating a Property List

• + propertyList:isValidForFormat:

Class Methods

dataFromPropertyList:format:errorDescription:

Returns an NSData object containing a given property list in a specified format.

+ (NSData *)dataFromPropertyList:(id)plist format:(NSPropertyListFormat)format errorDescription:(NSString **)errorString

Parameters

plist

A property list object. plist must be a kind of NSData, NSString, NSNumber, NSDate, NSArray, or NSDictionary object. Container objects must also contain only these kinds of objects.

format

A property list format. Possible values for format are described in NSPropertyListFormat.

errorString

Upon return, if the conversion is successful, errorString is nil. If the conversion fails, upon return contains a string describing the nature of the error. If you receive a string, you must release it.

Return Value

An NSData object containing plist in the format specified by format.

Special Considerations

Unlike the normal memory management rules for Cocoa, strings returned in errorString need to be released by the caller.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• + propertyListFromData:mutabilityOption:format:errorDescription:

Related Sample Code

• EnhancedAudioBurn
• iSpend
• People
• SpotlightFortunes
• Squiggles

Declared In

NSPropertyList.h

propertyList:isValidForFormat:

Returns a Boolean value that indicates whether a given property list is valid for a given format.

+ (BOOL)propertyList:(id)plist isValidForFormat:(NSPropertyListFormat)format

Parameters

plist

A property list object.

format

A property list format. Possible values for format are listed in NSPropertyListFormat.

Return Value

YES if plist is a valid property list in format format, otherwise NO.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

NSPropertyList.h

propertyListFromData:mutabilityOption:format:errorDescription:

Returns a property list object corresponding to the representation in a given NSData object.

+ (id)propertyListFromData:(NSData *)data mutabilityOption:(NSPropertyListMutabilityOptions)opt format:(NSPropertyListFormat *)format errorDescription:(NSString **)errorString

Parameters

data

A data object containing a serialized property list.

opt

Determines whether the property list’s contents are created as mutable objects, where possible. Possible values are described in NSPropertyListMutabilityOptions.

format

If the property list is valid, upon return contains the format. format can be NULL, in which case the property list format is not returned. Possible values are described in NSPropertyListFormat.

errorString

Upon return, if the conversion is successful, errorString is nil. If the conversion fails, upon return contains a string describing the nature of the error. If you receive a string, you must release it.

Return Value

A property list object corresponding to the representation in data. If data is not in a supported format, returns nil.

Special Considerations

Unlike the normal memory management rules for Cocoa, strings returned in errorString need to be released by the caller.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• + dataFromPropertyList:format:errorDescription:

Related Sample Code

• AlbumToSlideshow
• iSpend
• People
• Sketch-112
• Squiggles

Declared In

NSPropertyList.h

Constants

NSPropertyListMutabilityOptions

These constants specify mutability options in property lists.

typedef enum {
   NSPropertyListImmutable = kCFPropertyListImmutable,
   NSPropertyListMutableContainers = kCFPropertyListMutableContainers,
   NSPropertyListMutableContainersAndLeaves = kCFPropertyListMutableContainersAndLeaves
} NSPropertyListMutabilityOptions;

Constants

NSPropertyListImmutable

Causes the returned property list to contain immutable objects.

Available in Mac OS X v10.2 and later.

Declared in NSPropertyList.h.

NSPropertyListMutableContainers

Causes the returned property list to have mutable containers but immutable leaves.

Available in Mac OS X v10.2 and later.

Declared in NSPropertyList.h.

NSPropertyListMutableContainersAndLeaves

Causes the returned property list to have mutable containers and leaves.

Available in Mac OS X v10.2 and later.

Declared in NSPropertyList.h.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

NSPropertyList.h

NSPropertyListFormat

These constants are used to specify a property list serialization format.

typedef enum {
   NSPropertyListOpenStepFormat = kCFPropertyListOpenStepFormat,
   NSPropertyListXMLFormat_v1_0 = kCFPropertyListXMLFormat_v1_0,
   NSPropertyListBinaryFormat_v1_0 = kCFPropertyListBinaryFormat_v1_0
} NSPropertyListFormat;

Constants

NSPropertyListOpenStepFormat

Specifies the old-style ASCII property list format inherited from the OpenStep APIs.

Important: The NSPropertyListOpenStepFormat constant is not supported for writing. It can be used only for reading old-style property lists.

Available in Mac OS X v10.2 and later.

Declared in NSPropertyList.h.

NSPropertyListXMLFormat_v1_0

Specifies the XML property list format.

Available in Mac OS X v10.2 and later.

Declared in NSPropertyList.h.

NSPropertyListBinaryFormat_v1_0

Specifies the binary property list format.

Available in Mac OS X v10.2 and later.

Declared in NSPropertyList.h.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

NSPropertyList.h

---