| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/Foundation.framework |
| Availability | Available in Mac OS X v10.2 and later. |
| Declared in | NSPropertyList.h |
| Companion guides | |
| Related sample code |
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.
+ dataFromPropertyList:format:errorDescription:
+ dataWithPropertyList:format:options:error:
+ writePropertyList:toStream:format:options:error:
+ propertyListFromData:mutabilityOption:format:errorDescription:
+ propertyListWithData:options:format:error:
+ propertyListWithStream:options:format:error:
Returns an NSData object containing a given property list in a specified format.
+ (NSData *)dataFromPropertyList:(id)plist format:(NSPropertyListFormat)format errorDescription:(NSString **)errorString
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.
A property list format. Possible values for format are described in NSPropertyListFormat.
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.
An NSData object containing plist in the format specified by format.
Unlike the normal memory management rules for Cocoa, strings returned in errorString need to be released by the caller.
Important: This method is obsolete and will be deprecated soon. Use dataWithPropertyList:format:options:error: instead.
NSPropertyList.hReturns 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
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.
A property list format. Possible values for format are described in NSPropertyListFormat.
The opt parameter is currently unused and should be set to 0.
If the method does not complete successfully, upon return contains an NSError object that describes the problem.
An NSData object containing plist in the format specified by format.
NSPropertyList.hReturns a Boolean value that indicates whether a given property list is valid for a given format.
+ (BOOL)propertyList:(id)plist isValidForFormat:(NSPropertyListFormat)format
A property list object.
A property list format. Possible values for format are listed in NSPropertyListFormat.
YES if plist is a valid property list in format format, otherwise NO.
NSPropertyList.hReturns 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
A data object containing a serialized property list.
The opt parameter is currently unused and should be set to 0.
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.
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.
A property list object corresponding to the representation in data. If data is not in a supported format, returns nil.
Unlike the normal memory management rules for Cocoa, strings returned in errorString need to be released by the caller.
Important: This method is obsolete and will be deprecated soon. Use propertyListWithData:options:format:error: instead.
NSPropertyList.hCreates and returns a property list from the specified data.
+ (id)propertyListWithData:(NSData *)data options:(NSPropertyListReadOptions)opt format:(NSPropertyListFormat *)format error:(NSError **)error
A data object containing a serialized property list.
The opt parameter is currently unused and should be set to 0.
A property list format. Possible values for format are described in NSPropertyListFormat.
If the method does not complete successfully, upon return contains an NSError object that describes the problem.
A property list object corresponding to the representation in data. If data is not in a supported format, returns nil.
NSPropertyList.hCreates and returns a property list by reading from the specified stream.
+ (id)propertyListWithStream:(NSInputStream *)stream options:(NSPropertyListReadOptions)opt format:(NSPropertyListFormat *)format error:(NSError **)error
An NSStream. The stream should be open and configured for reading.
The opt parameter should be set to on one of the “NSPropertyListMutabilityOptions” options.
A property list format. Possible values for format are described in NSPropertyListFormat.
If the method does not complete successfully, upon return contains an NSError object that describes the problem.
A property list object corresponding to the representation in data. If data is not in a supported format, returns nil.
NSPropertyList.hWrites the specified property list to the specified stream.
+ (NSInteger)writePropertyList:(id)plist toStream:(NSOutputStream *)stream format:(NSPropertyListFormat)format options:(NSPropertyListWriteOptions)opt error:(NSError **)error
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.
An NSStream. The stream should be open and configured for writing.
A property list format. Possible values for format are described in NSPropertyListFormat.
The opt parameter is currently unused and should be set to 0.
If the method does not complete successfully, upon return contains an NSError object that describes the problem.
Returns the number of bytes written to the stream. If the value is 0 an error occurred.
NSPropertyList.hThese constants specify mutability options in property lists.
enum {
NSPropertyListImmutable = kCFPropertyListImmutable,
NSPropertyListMutableContainers = kCFPropertyListMutableContainers,
NSPropertyListMutableContainersAndLeaves = kCFPropertyListMutableContainersAndLeaves
};
typedef NSUInteger NSPropertyListMutabilityOptions;
NSPropertyListImmutableCauses the returned property list to contain immutable objects.
Available in Mac OS X v10.2 and later.
Declared in NSPropertyList.h.
NSPropertyListMutableContainersCauses the returned property list to have mutable containers but immutable leaves.
Available in Mac OS X v10.2 and later.
Declared in NSPropertyList.h.
NSPropertyListMutableContainersAndLeavesCauses the returned property list to have mutable containers and leaves.
Available in Mac OS X v10.2 and later.
Declared in NSPropertyList.h.
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;
NSPropertyListOpenStepFormatSpecifies 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_0Specifies the XML property list format.
Available in Mac OS X v10.2 and later.
Declared in NSPropertyList.h.
NSPropertyListBinaryFormat_v1_0Specifies the binary property list format.
Available in Mac OS X v10.2 and later.
Declared in NSPropertyList.h.
The read options are not currently implemented and the value should be set to 0.
typedef NSUInteger NSPropertyListReadOptions;
NSPropertyList.hThe write options should be set to one of the “NSPropertyListMutabilityOptions” constants.
typedef NSUInteger NSPropertyListWriteOptions;
NSPropertyList.hLast updated: 2009-10-08
Mac OS X Reference Library Data Management: File Management NSPropertyListSerialization Class Reference