Inherits from | |
Conforms to | |
Framework | /System/Library/Frameworks/Foundation.framework |
Availability | Available in Mac OS X v10.2 and later. |
Companion guide | |
Declared in | NSKeyedArchiver.h |
Related sample code |
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.
+ archivedDataWithRootObject:
+ archiveRootObject:toFile:
– finishEncoding
– outputFormat
– setOutputFormat:
– archiver:didEncodeObject:
delegate method
– archiverDidFinish:
delegate method
– archiver:willEncodeObject:
delegate method
– archiverWillFinish:
delegate method
– archiver:willReplaceObject:withObject:
delegate method
– encodeBool:forKey:
– encodeBytes:length:forKey:
– encodeConditionalObject:forKey:
– encodeDouble:forKey:
– encodeFloat:forKey:
– encodeInt:forKey:
– encodeInt32:forKey:
– encodeInt64:forKey:
– encodeObject:forKey:
Returns an NSData
object containing the encoded form of the object graph whose root object is given.
+ (NSData *)archivedDataWithRootObject:(id)rootObject
The root of the object graph to archive.
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
.
NSKeyedArchiver.h
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
The root of the object graph to archive.
The path of the file in which to write the archive.
YES
if the operation was successful, otherwise NO
.
The format of the archive is NSPropertyListBinaryFormat_v1_0
.
NSKeyedArchiver.h
Returns the class name with which NSKeyedArchiver
encodes instances of a given class.
+ (NSString *)classNameForClass:(Class)cls
The class for which to determine the translation mapping.
The class name with which NSKeyedArchiver
encodes instances of cls. Returns nil
if NSKeyedArchiver
does not have a translation mapping for cls.
NSKeyedArchiver.h
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
The name of the class that NSKeyedArchiver
uses in place of cls
.
The class for which to set up a translation mapping.
When encoding, the class’s translation mapping is used only if no translation is found first in an instance’s separate translation map.
NSKeyedArchiver.h
Returns the class name with which the receiver encodes instances of a given class.
- (NSString *)classNameForClass:(Class)cls
The class for which to determine the translation mapping.
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.
NSKeyedArchiver.h
Returns the receiver’s delegate.
- (id)delegate
The receiver's delegate.
NSKeyedArchiver.h
Encodes a given Boolean value and associates it with a given key.
- (void)encodeBool:(BOOL)boolv forKey:(NSString *)key
The value to encode.
The key with which to associate boolv. This value must not be nil
.
decodeBoolForKey:
(NSKeyedUnarchiver
)NSKeyedArchiver.h
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
A C array of bytes to encode.
The number of bytes from bytesp to encode.
The key with which to associate the encoded value. This value must not be nil
.
decodeBytesForKey:returnedLength:
(NSKeyedUnarchiver
)NSKeyedArchiver.h
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
The object to encode.
The key with which to associate the encoded value. This value must not be nil
.
NSKeyedArchiver.h
Encodes a given double
value and associates it with a given key.
- (void)encodeDouble:(double)realv forKey:(NSString *)key
The value to encode.
The key with which to associate realv. This value must not be nil
.
decodeDoubleForKey:
(NSKeyedUnarchiver
)decodeFloatForKey:
(NSKeyedUnarchiver
)NSKeyedArchiver.h
Encodes a given float
value and associates it with a given key.
- (void)encodeFloat:(float)realv forKey:(NSString *)key
The value to encode.
The key with which to associate realv. This value must not be nil
.
decodeFloatForKey:
(NSKeyedUnarchiver
)decodeDoubleForKey:
(NSKeyedUnarchiver
)NSKeyedArchiver.h
Encodes a given 32-bit integer value and associates it with a given key.
- (void)encodeInt32:(int32_t)intv forKey:(NSString *)key
The value to encode.
The key with which to associate intv. This value must not be nil
.
decodeInt32ForKey:
(NSKeyedUnarchiver
)NSKeyedArchiver.h
Encodes a given 64-bit integer value and associates it with a given key.
- (void)encodeInt64:(int64_t)intv forKey:(NSString *)key
The value to encode.
The key with which to associate intv. This value must not be nil
.
decodeInt64ForKey:
(NSKeyedUnarchiver
)NSKeyedArchiver.h
Encodes a given int
value and associates it with a given key.
- (void)encodeInt:(int)intv forKey:(NSString *)key
The value to encode.
The key with which to associate intv. This value must not be nil
.
decodeIntForKey:
(NSKeyedUnarchiver
)NSKeyedArchiver.h
Encodes a given object and associates it with a given key.
- (void)encodeObject:(id)objv forKey:(NSString *)key
The value to encode. This value may be nil
.
The key with which to associate objv. This value must not be nil
.
decodeObjectForKey:
(NSKeyedUnarchiver
)NSKeyedArchiver.h
Instructs the receiver to construct the final data stream.
- (void)finishEncoding
No more values can be encoded after this method is called. You must call this method when finished.
NSKeyedArchiver.h
Returns the receiver, initialized for encoding an archive into a given a mutable-data object.
- (id)initForWritingWithMutableData:(NSMutableData *)data
The mutable-data object into which the archive is written.
The receiver, initialized for encoding an archive into data.
When you finish encoding data, you must invoke finishEncoding
at which point data is filled. The format of the receiver is NSPropertyListBinaryFormat_v1_0
.
NSKeyedArchiver.h
Returns the format in which the receiver encodes its data.
- (NSPropertyListFormat)outputFormat
The format in which the receiver encodes its data. The available formats are NSPropertyListXMLFormat_v1_0
and NSPropertyListBinaryFormat_v1_0
.
NSKeyedArchiver.h
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
The name of the class that the receiver uses uses in place of cls
.
The class for which to set up a translation mapping.
When encoding, the receiver’s translation map overrides any translation that may also be present in the class’s map.
NSKeyedArchiver.h
Sets the delegate for the receiver.
- (void)setDelegate:(id)delegate
The delegate for the receiver.
NSKeyedArchiver.h
Sets the format in which the receiver encodes its data.
- (void)setOutputFormat:(NSPropertyListFormat)format
The format in which the receiver encodes its data. format can be NSPropertyListXMLFormat_v1_0
or NSPropertyListBinaryFormat_v1_0
.
NSKeyedArchiver.h
Informs the delegate that a given object has been encoded.
- (void)archiver:(NSKeyedArchiver *)archiver didEncodeObject:(id)object
The archiver that sent the message.
The object that has been encoded. object may be nil
.
The delegate might restore some state it had modified previously, or use this opportunity to keep track of the objects that are encoded.
This method is not called for conditional objects until they are actually encoded (if ever).
NSKeyedArchiver.h
Informs the delegate that object is about to be encoded.
- (id)archiver:(NSKeyedArchiver *)archiver willEncodeObject:(id)object
The archiver that sent the message.
The object that is about to be encoded. This value is never nil
.
Either object or a different object to be encoded in its stead. The delegate can also modify the coder state. If the delegate returns nil
, nil
is encoded.
This method is called after the original object may have replaced itself with replacementObjectForKeyedArchiver:
.
This method is called whether or not the object is being encoded conditionally.
This method is not called for an object once a replacement mapping has been set up for that object (either explicitly, or because the object has previously been encoded). This method is also not called when nil
is about to be encoded.
NSKeyedArchiver.h
Informs the delegate that one given object is being substituted for another given object.
- (void)archiver:(NSKeyedArchiver *)archiver willReplaceObject:(id)object withObject:(id)newObject
The archiver that sent the message.
The object being replaced in the archive.
The object replacing object in the archive.
This method is called even when the delegate itself is doing, or has done, the substitution. The delegate may use this method if it is keeping track of the encoded or decoded objects.
NSKeyedArchiver.h
Notifies the delegate that encoding has finished.
- (void)archiverDidFinish:(NSKeyedArchiver *)archiver
The archiver that sent the message.
NSKeyedArchiver.h
Notifies the delegate that encoding is about to finish.
- (void)archiverWillFinish:(NSKeyedArchiver *)archiver
The archiver that sent the message.
NSKeyedArchiver.h
Names of exceptions that are raised by NSKeyedArchiver
if there is a problem creating an archive.
extern NSString *NSInvalidArchiveOperationException;
NSInvalidArchiveOperationException
The name of the exception raised by NSKeyedArchiver
if there is a problem creating an archive.
Available in Mac OS X v10.2 and later.
Declared in NSKeyedArchiver.h
.
NSKeyedArchiver.h
© 2008 Apple Inc. All Rights Reserved. (Last updated: 2008-10-15)