Overview
NSKeyedArchiver, a concrete subclass of NSCoder, provides a way to encode objects (and scalar values) into an architecture-independent format that can be stored in a file. When you archive a set of objects, the class information and instance variables for each object are written to the archive. NSKeyedArchiver’s companion class, NSKeyedUnarchiver, decodes the data in an archive and creates a set of objects equivalent to the original set.
A keyed archive differs from a non-keyed archive in that all the objects and values encoded into the archive are given names, or keys. When decoding a non-keyed archive, values have to be decoded in the same order in which they were encoded. When decoding a keyed archive, because values are requested by name, values can be decoded out of sequence or not at all. Keyed archives, therefore, provide better support for forward and backward compatibility.
The keys given to encoded values must be unique only within the scope of the current object being encoded. A keyed archive is hierarchical, so the keys used by object A to encode its instance variables do not conflict with the keys used by object B, even if A and B are instances of the same class. Within a single object, however, the keys used by a subclass can conflict with keys used in its superclasses.
An NSArchiver object can write the archive data to a file or to a mutable-data object (an instance of NSMutableData) that you provide.
Tasks
Initializing an NSKeyedArchiver Object
- – initForWritingWithMutableData:
Archiving Data
- + archivedDataWithRootObject:
- + archiveRootObject:toFile:
- – finishEncoding
- – outputFormat
- – setOutputFormat:
- – setRequiresSecureCoding:
Encoding Data and Objects
- – encodeBool:forKey:
- – encodeBytes:length:forKey:
- – encodeConditionalObject:forKey:
- – encodeDouble:forKey:
- – encodeFloat:forKey:
- – encodeInt:forKey:
- – encodeInt32:forKey:
- – encodeInt64:forKey:
- – encodeObject:forKey:
Managing Delegates
- – delegate
- – setDelegate:
Managing Classes and Class Names
- + setClassName:forClass:
- + classNameForClass:
- – setClassName:forClass:
- – classNameForClass:
Class Methods
archivedDataWithRootObject:
Returns an NSData object containing the encoded form of the object graph whose root object is given.
+ (NSData *)archivedDataWithRootObject:(id)rootObject
Parameters
rootObject
The root of the object graph to archive.
Return Value
An NSData object containing the encoded form of the object graph whose root object is rootObject. The format of the archive is NSPropertyListBinaryFormat_v1_0.
Availability
- Available in OS X v10.2 and later.
Related Sample Code
Declared In
NSKeyedArchiver.h
archiveRootObject:toFile:
Archives an object graph rooted at a given object by encoding it into a data object then atomically writes the resulting data object to a file at a given path, and returns a Boolean value that indicates whether the operation was successful.
+ (BOOL)archiveRootObject:(id)rootObject toFile:(NSString *)path
Parameters
rootObject
The root of the object graph to archive.
path
The path of the file in which to write the archive.
Return Value
YES if the operation was successful, otherwise NO.
Discussion
The format of the archive is NSPropertyListBinaryFormat_v1_0.
Availability
- Available in OS X v10.2 and later.
Declared In
NSKeyedArchiver.h
classNameForClass:
Returns the class name with which NSKeyedArchiver encodes instances of a given class.
+ (NSString *)classNameForClass:(Class)cls
Parameters
cls
The class for which to determine the translation mapping.
Return Value
The class name with which NSKeyedArchiver encodes instances of cls. Returns nil if NSKeyedArchiver does not have a translation mapping for cls.
Availability
- Available in OS X v10.2 and later.
See Also
- + setClassName:forClass:
- – classNameForClass:
Declared In
NSKeyedArchiver.h
setClassName:forClass:
Adds a class translation mapping to NSKeyedArchiver whereby instances of of a given class are encoded with a given class name instead of their real class names.
+ (void)setClassName:(NSString *)codedName forClass:(Class)cls
Parameters
codedName
The name of the class that NSKeyedArchiver uses in place of cls.
cls
The class for which to set up a translation mapping.
Discussion
When encoding, the class’s translation mapping is used only if no translation is found first in an instance’s separate translation map.
Availability
- Available in OS X v10.2 and later.
See Also
- + classNameForClass:
- – setClassName:forClass:
Declared In
NSKeyedArchiver.h
Instance Methods
classNameForClass:
Returns the class name with which the receiver encodes instances of a given class.
- (NSString *)classNameForClass:(Class)cls
Parameters
cls
The class for which to determine the translation mapping.
Return Value
The class name with which the receiver encodes instances of cls. Returns nil if the receiver does not have a translation mapping for cls. The class’s separate translation map is not searched.
Availability
- Available in OS X v10.2 and later.
See Also
- – setClassName:forClass:
- + classNameForClass:
Declared In
NSKeyedArchiver.h
delegate
Returns the receiver’s delegate.
- (id<NSKeyedArchiverDelegate>)delegate
Return Value
The receiver's delegate.
Availability
- Available in OS X v10.2 and later.
See Also
- – setDelegate:
Declared In
NSKeyedArchiver.h
encodeBool:forKey:
Encodes a given Boolean value and associates it with a given key.
- (void)encodeBool:(BOOL)boolv forKey:(NSString *)key
Parameters
boolv
The value to encode.
key
The key with which to associate boolv. This value must not be nil.
Availability
- Available in OS X v10.2 and later.
See Also
- decodeBoolForKey: (NSKeyedUnarchiver)
Declared In
NSKeyedArchiver.h
encodeBytes:length:forKey:
Encodes a given number of bytes from a given C array of bytes and associates them with the a given key.
- (void)encodeBytes:(const uint8_t *)bytesp length:(NSUInteger)lenv forKey:(NSString *)key
Parameters
bytesp
A C array of bytes to encode.
lenv
The number of bytes from bytesp to encode.
key
The key with which to associate the encoded value. This value must not be nil.
Availability
- Available in OS X v10.2 and later.
See Also
- decodeBytesForKey:returnedLength: (NSKeyedUnarchiver)
Declared In
NSKeyedArchiver.h
encodeConditionalObject:forKey:
Encodes a reference to a given object and associates it with a given key only if it has been unconditionally encoded elsewhere in the archive with encodeObject:forKey:.
- (void)encodeConditionalObject:(id)objv forKey:(NSString *)key
Parameters
objv
The object to encode.
key
The key with which to associate the encoded value. This value must not be nil.
Availability
- Available in OS X v10.2 and later.
Declared In
NSKeyedArchiver.h
encodeDouble:forKey:
Encodes a given double value and associates it with a given key.
- (void)encodeDouble:(double)realv forKey:(NSString *)key
Parameters
realv
The value to encode.
key
The key with which to associate realv. This value must not be nil.
Availability
- Available in OS X v10.2 and later.
See Also
- decodeDoubleForKey: (NSKeyedUnarchiver)
- decodeFloatForKey: (NSKeyedUnarchiver)
Declared In
NSKeyedArchiver.h
encodeFloat:forKey:
Encodes a given float value and associates it with a given key.
- (void)encodeFloat:(float)realv forKey:(NSString *)key
Parameters
realv
The value to encode.
key
The key with which to associate realv. This value must not be nil.
Availability
- Available in OS X v10.2 and later.
See Also
- decodeFloatForKey: (NSKeyedUnarchiver)
- decodeDoubleForKey: (NSKeyedUnarchiver)
Declared In
NSKeyedArchiver.h
encodeInt32:forKey:
Encodes a given 32-bit integer value and associates it with a given key.
- (void)encodeInt32:(int32_t)intv forKey:(NSString *)key
Parameters
intv
The value to encode.
key
The key with which to associate intv. This value must not be nil.
Availability
- Available in OS X v10.2 and later.
See Also
- decodeInt32ForKey: (NSKeyedUnarchiver)
Declared In
NSKeyedArchiver.h
encodeInt64:forKey:
Encodes a given 64-bit integer value and associates it with a given key.
- (void)encodeInt64:(int64_t)intv forKey:(NSString *)key
Parameters
intv
The value to encode.
key
The key with which to associate intv. This value must not be nil.
Availability
- Available in OS X v10.2 and later.
See Also
- decodeInt64ForKey: (NSKeyedUnarchiver)
Declared In
NSKeyedArchiver.h
encodeInt:forKey:
Encodes a given int value and associates it with a given key.
- (void)encodeInt:(int)intv forKey:(NSString *)key
Parameters
intv
The value to encode.
key
The key with which to associate intv. This value must not be nil.
Availability
- Available in OS X v10.2 and later.
See Also
- decodeIntForKey: (NSKeyedUnarchiver)
Declared In
NSKeyedArchiver.h
encodeObject:forKey:
Encodes a given object and associates it with a given key.
- (void)encodeObject:(id)objv forKey:(NSString *)key
Parameters
objv
The value to encode. This value may be nil.
key
The key with which to associate objv. This value must not be nil.
Availability
- Available in OS X v10.2 and later.
See Also
- decodeObjectForKey: (NSKeyedUnarchiver)
Related Sample Code
Declared In
NSKeyedArchiver.h
finishEncoding
Instructs the receiver to construct the final data stream.
- (void)finishEncoding
Discussion
No more values can be encoded after this method is called. You must call this method when finished.
Availability
- Available in OS X v10.2 and later.
See Also
- – initForWritingWithMutableData:
Related Sample Code
Declared In
NSKeyedArchiver.h
initForWritingWithMutableData:
Returns the receiver, initialized for encoding an archive into a given a mutable-data object.
- (id)initForWritingWithMutableData:(NSMutableData *)data
Parameters
data
The mutable-data object into which the archive is written.
Return Value
The receiver, initialized for encoding an archive into data.
Discussion
When you finish encoding data, you must invoke finishEncoding at which point data is filled. The format of the receiver is NSPropertyListBinaryFormat_v1_0.
Availability
- Available in OS X v10.2 and later.
Declared In
NSKeyedArchiver.h
outputFormat
Returns the format in which the receiver encodes its data.
- (NSPropertyListFormat)outputFormat
Return Value
The format in which the receiver encodes its data. The available formats are NSPropertyListXMLFormat_v1_0 and NSPropertyListBinaryFormat_v1_0.
Availability
- Available in OS X v10.2 and later.
See Also
- – setOutputFormat:
Declared In
NSKeyedArchiver.h
setClassName:forClass:
Adds a class translation mapping to the receiver whereby instances of of a given class are encoded with a given class name instead of their real class names.
- (void)setClassName:(NSString *)codedName forClass:(Class)cls
Parameters
codedName
The name of the class that the receiver uses uses in place of cls.
cls
The class for which to set up a translation mapping.
Discussion
When encoding, the receiver’s translation map overrides any translation that may also be present in the class’s map.
Availability
- Available in OS X v10.2 and later.
See Also
- – classNameForClass:
- + setClassName:forClass:
Declared In
NSKeyedArchiver.h
setDelegate:
Sets the delegate for the receiver.
- (void)setDelegate:(id<NSKeyedArchiverDelegate>)delegate
Parameters
delegate
The delegate for the receiver.
Availability
- Available in OS X v10.2 and later.
See Also
- – delegate
Declared In
NSKeyedArchiver.h
setOutputFormat:
Sets the format in which the receiver encodes its data.
- (void)setOutputFormat:(NSPropertyListFormat)format
Parameters
format
The format in which the receiver encodes its data. format can be NSPropertyListXMLFormat_v1_0 or NSPropertyListBinaryFormat_v1_0.
Availability
- Available in OS X v10.2 and later.
See Also
- – outputFormat
Declared In
NSKeyedArchiver.h
setRequiresSecureCoding:
Indicates whether the receiver requires all archived classes to conform to NSSecureCoding.
- (void)setRequiresSecureCoding:(BOOL)flag
Parameters
flag
YES if the receiver requires NSSecureCoding; NO if not.
Discussion
If you set the receiver to require secure coding, it will throw an exception if you attempt to archive a class which does not conform to NSSecureCoding.
Note that the getter is on the superclass, NSCoder. See NSCoder for more information about secure coding.
Availability
- Available in OS X v10.8 and later.
Declared In
NSKeyedArchiver.h
Constants
Keyed Archiving Exception Names
Names of exceptions that are raised by NSKeyedArchiver if there is a problem creating an archive.
extern NSString *NSInvalidArchiveOperationException;
Constants
NSInvalidArchiveOperationException
The name of the exception raised by NSKeyedArchiver if there is a problem creating an archive.
Available in OS X v10.2 and later.
Declared in NSKeyedArchiver.h.
Declared In
NSKeyedArchiver.h
Keyed Archiver Root Object Key
Keys that NSKeyedArchiver uses in the hierarchy of encoded objects.
extern NSString * const NSKeyedArchiveRootObjectKey;
Constants
NSKeyedArchiveRootObjectKey
Archives created using the class method archivedDataWithRootObject: use this key for the root object in the hierarchy of encoded objects. The NSKeyedUnarchiver class method unarchiveObjectWithData: looks for this root key as well.
Available in OS X v10.9 and later.
Declared in NSKeyedArchiver.h.
Copyright © 2013 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2013-09-18