Overview
NSArchiver, a concrete subclass of NSCoder, provides a way to encode objects into an architecture-independent format that can be stored in a file. When you archive a graph of objects, the class information and instance variables for each object are written to the archive. NSArchiver's companion class, NSUnarchiver, decodes the data in an archive and creates a graph of objects equivalent to the original set.
NSArchiver stores the archive data in a mutable data object (NSMutableData). After encoding the objects, you can have the NSArchiver object write this mutable data object immediately to a file, or you can retrieve the mutable data object for some other use.
In OS X v10.2 and later, NSArchiver and NSUnarchiver have been replaced by NSKeyedArchiver and NSKeyedUnarchiver respectively—see Archives and Serializations Programming Guide.
Tasks
Initializing an NSArchiver
- – initForWritingWithMutableData:
Archiving Data
- + archivedDataWithRootObject:
- + archiveRootObject:toFile:
- – encodeRootObject:
- – encodeConditionalObject:
Getting the Archived Data
- – archiverData
Substituting Classes or Objects
- – classNameEncodedForTrueClassName:
- – encodeClassName:intoClassName:
- – replaceObject:withObject:
Class Methods
archivedDataWithRootObject:
Returns a data object containing the encoded form of the object graph whose root object is given.
+ (NSData *)archivedDataWithRootObject:(id)rootObject
Parameters
rootObject
The root object of the object graph to archive.
Return Value
A data object containing the encoded form of the object graph whose root object is rootObject.
Discussion
This method invokes initForWritingWithMutableData: and encodeRootObject: to create a temporary archiver that encodes the object graph.
Availability
- Available in OS X v10.0 and later.
See Also
- – initForWritingWithMutableData:
- – encodeRootObject:
Related Sample Code
Declared In
NSArchiver.h
archiveRootObject:toFile:
Creates a temporary instance of NSArchiver and archives an object graph by encoding it into a data object and writing the resulting data object to a specified file.
+ (BOOL)archiveRootObject:(id)rootObject toFile:(NSString *)path
Parameters
rootObject
The root object of the object graph to archive.
path
The location of the the file into which to write the archive.
Return Value
YES if the archive was written successfully, otherwise NO.
Discussion
This convenience method invokes archivedDataWithRootObject: to get the encoded data, and then sends that data object the message writeToFile:atomically:, using path for the first argument and YES for the second.
The archived data should be retrieved from the archive by an NSUnarchiver object.
Availability
- Available in OS X v10.0 and later.
See Also
- + archivedDataWithRootObject:
- – writeToFile:atomically: (NSData)
Declared In
NSArchiver.h
Instance Methods
archiverData
Returns the receiver's archive data.
- (NSMutableData *)archiverData
Return Value
The receiver's archive data.
Discussion
The returned data object is the same one specified as the argument to initForWritingWithMutableData:. It contains whatever data has been encoded thus far by invocations of the various encoding methods. It is safest not to invoke this method until after encodeRootObject: has returned. In other words, although it is possible for a class to invoke this method from within its encodeWithCoder: method, that method must not alter the data.
Availability
- Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSArchiver.h
classNameEncodedForTrueClassName:
Returns the name of the class used to archive instances of the class with a given true name.
- (NSString *)classNameEncodedForTrueClassName:(NSString *)trueName
Parameters
trueName
The real name of an encoded class.
Return Value
The name of the class used to archive instances of the class trueName.
Availability
- Available in OS X v10.0 and later.
See Also
- – encodeClassName:intoClassName:
Declared In
NSArchiver.h
encodeClassName:intoClassName:
Encodes a substitute name for the class with a given true name.
- (void)encodeClassName:(NSString *)trueName intoClassName:(NSString *)inArchiveName
Parameters
trueName
The real name of a class in the object graph being archived.
inArchiveName
The name of the class to use in the archive in place of trueName.
Discussion
Any subsequently encountered objects of class trueName are archived as instances of class inArchiveName. It is safest not to invoke this method during the archiving process (that is, within an encodeWithCoder: method). Instead, invoke it before encodeRootObject:.
Availability
- Available in OS X v10.0 and later.
See Also
- – classNameEncodedForTrueClassName:
Declared In
NSArchiver.h
encodeConditionalObject:
Conditionally archives a given object.
- (void)encodeConditionalObject:(id)object
Parameters
object
The object to archive.
Discussion
This method overrides the superclass implementation to allow object to be encoded only if it is also encoded unconditionally by another object in the object graph. Conditional encoding lets you encode one part of a graph detached from the rest. (See Archives and Serializations Programming Guide for more information.)
This method should be invoked only from within an encodeWithCoder: method. If object is nil, the NSArchiver object encodes it unconditionally as nil. This method raises an NSInvalidArgumentException if no root object has been encoded.
Availability
- Available in OS X v10.0 and later.
Declared In
NSArchiver.h
encodeRootObject:
Archives a given object along with all the objects to which it is connected.
- (void)encodeRootObject:(id)rootObject
Parameters
rootObject
The root object of the object graph to archive.
Discussion
If any object is encountered more than once while traversing the graph, it is encoded only once, but the multiple references to it are stored. (See Archives and Serializations Programming Guide for more information.)
This message must not be sent more than once to a given NSArchiver object; an NSInvalidArgumentException is raised if a root object has already been encoded. If you need to encode multiple object graphs, therefore, don’t attempt to reuse an NSArchiver instance; instead, create a new one for each graph.
Availability
- Available in OS X v10.0 and later.
Declared In
NSArchiver.h
initForWritingWithMutableData:
Returns an archiver, initialized to encode stream and version information into a given mutable data object.
- (id)initForWritingWithMutableData:(NSMutableData *)data
Parameters
data
The mutable data object into which to write the archive. This value must not be nil.
Return Value
An archiver object, initialized to encode stream and version information into data.
Discussion
Raises an NSInvalidArgumentException if data is nil.
Availability
- Available in OS X v10.0 and later.
See Also
- – archiverData
Declared In
NSArchiver.h
replaceObject:withObject:
Causes the receiver to treat subsequent requests to encode a given object as though they were requests to encode another given object.
- (void)replaceObject:(id)object withObject:(id)newObject
Parameters
object
An object in the object graph being archived.
newObject
The object with which to replace object in the archive.
Discussion
Both object and newObject must be valid objects.
Availability
- Available in OS X v10.0 and later.
Declared In
NSArchiver.h
Constants
Archiving Exception Names
Raised by NSArchiver if there are problems initializing or encoding.
extern NSString *NSInconsistentArchiveException;
Constants
NSInconsistentArchiveException
The name of an exception raised by NSArchiver if there are problems initializing or encoding.
Available in OS X v10.0 and later.
Declared in NSArchiver.h.
Declared In
NSArchiver.h
Copyright © 2006 Apple Computer, Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2006-05-23