NSPropertyListSerialization Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 2.0 and later.
Declared in
NSPropertyList.h
Companion guides
Archives and Serializations Programming Guide
Property List Programming Guide
Related sample code

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”.

Tasks

Serializing a Property List

Deserializing a Property List

Validating a Property List

Obsolete Methods

Class Methods

dataFromPropertyList:format:errorDescription:

This method is obsolete and will be deprecated soon. (Deprecated. Use dataWithPropertyList:format:options:error: instead.)

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

A property list object.

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.

Return Value

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

Special Considerations

This method is obsolete and will be deprecated soon. Use dataWithPropertyList:format:options:error: instead.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
NSPropertyList.h

dataWithPropertyList:format:options:error:

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

+ (NSData *)dataWithPropertyList:(id)plist format:(NSPropertyListFormat)format options:(NSPropertyListWriteOptions)opt error:(NSError **)error
Parameters
plist

A property list object. Passing nil for this value will cause an exception to be raised.

format

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

opt

The opt parameter is currently unused and should be set to 0.

error

If the method does not complete successfully, upon return contains an NSError object that describes the problem.

Return Value

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

Availability
  • Available in iOS 4.0 and later.
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 iOS 2.0 and later.
Declared In
NSPropertyList.h

propertyListFromData:mutabilityOption:format:errorDescription:

This method is obsolete and will be deprecated soon. (Deprecated. Use propertyListWithData:options:format:error: instead.)

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

A data object containing a serialized property list.

opt

The opt parameter is currently unused and should be set to 0.

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.

Return Value

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

Special Considerations

This method is obsolete and will be deprecated soon. Use propertyListWithData:options:format:error: instead.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
NSPropertyList.h

propertyListWithData:options:format:error:

Creates and returns a property list from the specified data.

+ (id)propertyListWithData:(NSData *)data options:(NSPropertyListReadOptions)opt format:(NSPropertyListFormat *)format error:(NSError **)error
Parameters
data

A data object containing a serialized property list.

opt

The options can be any of those listed in “NSPropertyListMutabilityOptions.”

format

Upon return, contains the format that the property list was stored in.

Pass NULL, if you do not need to know the format. Possible values are described in NSPropertyListFormat.

error

If the method does not complete successfully, upon return contains an NSError object that describes the problem.

Return Value

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

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
NSPropertyList.h

propertyListWithStream:options:format:error:

Creates and returns a property list by reading from the specified stream.

+ (id)propertyListWithStream:(NSInputStream *)stream options:(NSPropertyListReadOptions)opt format:(NSPropertyListFormat *)format error:(NSError **)error
Parameters
stream

An NSStream object. The stream should be open and configured for reading.

opt

The options can be any of those listed in “NSPropertyListMutabilityOptions.”

format

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

error

Upon return, contains the format that the property list was stored in.

Pass NULL, if you do not need to know the format. Possible values are described in NSPropertyListFormat.

Return Value

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

Availability
  • Available in iOS 4.0 and later.
Declared In
NSPropertyList.h

writePropertyList:toStream:format:options:error:

Writes the specified property list to the specified stream.

+ (NSInteger)writePropertyList:(id)plist toStream:(NSOutputStream *)stream format:(NSPropertyListFormat)format options:(NSPropertyListWriteOptions)opt error:(NSError **)error
Parameters
plist

A property list object. Passing nil for this value will cause an exception to be raised.

stream

An NSStream object. The stream should be open and configured for reading.

format

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

opt

The opt parameter is currently unused and should be set to 0.

error

If the method does not complete successfully, upon return contains an NSError object that describes the problem.

Return Value

Returns the number of bytes written to the stream. If the value is 0 an error occurred.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSPropertyList.h

Constants

NSPropertyListMutabilityOptions

These constants specify mutability options in property lists.

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

Causes the returned property list to contain immutable objects.

Available in iOS 2.0 and later.

Declared in NSPropertyList.h.

NSPropertyListMutableContainers

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

Available in iOS 2.0 and later.

Declared in NSPropertyList.h.

NSPropertyListMutableContainersAndLeaves

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

Available in iOS 2.0 and later.

Declared in NSPropertyList.h.

NSPropertyListFormat

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

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

Specifies the 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 iOS 2.0 and later.

Declared in NSPropertyList.h.

NSPropertyListXMLFormat_v1_0

Specifies the XML property list format.

Available in iOS 2.0 and later.

Declared in NSPropertyList.h.

NSPropertyListBinaryFormat_v1_0

Specifies the binary property list format.

Available in iOS 2.0 and later.

Declared in NSPropertyList.h.

NSPropertyListReadOptions

The read options are not currently implemented and the value should be set to 0.

typedef NSUInteger NSPropertyListReadOptions;
Availability
  • Available in iOS 4.0 and later.
Declared In
NSPropertyList.h

NSPropertyListWriteOptions

The write options should be set to one of the “NSPropertyListMutabilityOptions” constants.

typedef NSUInteger NSPropertyListWriteOptions;
Availability
  • Available in iOS 4.0 and later.
Declared In
NSPropertyList.h


© 2010 Apple Inc. All Rights Reserved. (Last updated: 2010-09-08)

Did this document help you? Yes It's good, but... Not helpful...