Advanced Search

Log In | Not a Member?

Contact ADC

< Previous PageNext Page > Hide TOC

Binary Property Lists

This document describes binary representations of property lists and how to create and restore them.

As an alternative to the old-style ASCII or XML formats, you can store and retrieve property lists from a binary format introduced with Mac OS X v10.2. This format supports all property list types: NSString (java.lang.String in Java), NSData, NSArray, NSDictionary, and also NSNumber (number objects in Java) and NSDate. The NSPropertyListSerialization class provides methods for reading to and writing from this format.

In Java, NSPropertyListSerialization still uses an older binary property list format, which does not support date or number objects.

Contents:

Using Binary Property Lists in Objective-C
Using Binary Property Lists in Java

Using Binary Property Lists in Objective-C

The NSPropertyListSerialization class (available in Mac OS X v10.2 and later for Objective-C) provides methods for saving and restoring property lists from the three supported formats. To save a property list in binary format, use the dataFromPropertyList:format:errorDescription: method with the NSPropertyListBinaryFormat_v1_0 as the second parameter. This code fragment saves the property list plist to a binary plist file at path:

id plist;       // Assume this exists.

NSString *path; // Assume this is a valid path.

NSData *plistData;

NSString *error;

plistData = [NSPropertyListSerialization dataFromPropertyList:plist

                                    format:NSPropertyListBinaryFormat_v1_0

                                    errorDescription:&error];

if(plistData)

{

    NSLog(@"No error creating plist data.");

    [plistData writeToFile:path atomically:YES];

}

else

{

    NSLog(error);

    [error release];

}

To restore a property list from data, use the NSPropertyListSerialization methodpropertyListFromData:mutabilityOption:format:errorDescription:. The following code fragment creates an immutable property list from the file at path:

NSString *path; // Assume this is a path to a valid plist.

NSData *plistData;

NSString *error;

NSPropertyListFormat format;

id plist;

plistData = [NSData dataWithContentsOfFile:path];

plist = [NSPropertyListSerialization propertyListFromData:plistData

                                mutabilityOption:NSPropertyListImmutable

                                format:&format

                                errorDescription:&error];

if(!plist)

{

    NSLog(error);

    [error release];

}

Using Binary Property Lists in Java

The NSPropertyListSerialization class provides methods for saving and restoring property lists in the three property list formats. To create binary data from a property list, use the dataFromPropertyList static method. Note that property lists can only be serialized from object graphs containing only NSArray, NSDictionary, java.lang.String, and NSData objects. The following code fragment converts the property list plist into an NSData object, and stores the data to the file located at url:

Object plist;     // Assume this is a valid property list.

java.net.URL url; // Assume this is a well-formed local file URL.

NSData plistData;

plistData = NSPropertyListSerialization.dataFromPropertyList(plist);

plistData.writeToURL(url, true);

To restore binary data to a property list in memory, use the propertyListFromData static method. The following code fragment restores a property list from url:

java.net.URL url; // Assume this is a URL to a binary plist.

Object plist;

NSData plistData;

plistData = new NSData(url);

plist = NSPropertyListSerialization.propertyListFromData(plistData, NSPropertyListImmutable, null, null);

< Previous PageNext Page > Hide TOC

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice