NSArchiver

Inherits From: NSCoder : NSObject

Conforms To: NSObject (NSObject)

Declared In: Foundation/NSArchiver.h

Class Description

NSArchiver, a concrete subclass of NSCoder, defines an object that encodes Objective C objects into an architecture-independent format that can be stored in a file. When objects are archived, their class information and the values of their instance variables are written to the archive. NSArchiver's companion class, NSUnarchiver, takes an archive file and decodes its contents into a set of objects equivalent to the original one.

Archiving is typically initiated by sending an NSArchiver an encodeRootObject: or archiveRootObject:toFile: message. These messages specify a single object that is the starting point for archiving. The root object receives an encodeWithCoder: message (see the NSCoding protocol) that allows it to begin archiving itself and the other objects that it's connected to. An object responds to an encodeWithCoder: message by writing its instance variables to the archiver.

An object doesn't have to archive the values of each of its instance variables. Some values may not be important to reestablish and others may be derivable from related state upon unarchiving. Other instance variables should be written to the archive only under certain conditions, as explained below.

NSArchiver overrides the inherited encodeRootObject: and encodeConditionalObject: methods to support the conditional archiving of members of a graph of objects. When an object receives an encodeWithCoder: message, it should respond by unconditionally archiving instance variables that are intrinsic to its nature (with the exceptions noted above) and conditionally archiving those that are not. For example, an NSView unconditionally archives its array of subviews (using encodeObject:, or the like) but conditionally archives its superview (using encodeConditionalObject:). The archiving system notes each reference to a conditional object, but doesn't actually archive the object unless some other object in the graph requests the object to be archived unconditionally. This ensures that an object is only archived once despite multiple references to it in the object graph. When the objects are extracted from the archive, the multiple references to objects are resolved, and an equivalent graph of objects is reestablished.

Initializing an NSArchiver

• - (id)initForWritingWithMutableData:(NSMutableData *)mdata Initializes an archiver, encoding stream and version information into mutable data mdata. Raises NSInvalidArgumentException if the mdata argument is nil.

• + (NSData *)archivedDataWithRootObject:(id)rootObject Creates and returns a data object after initializing an archiver with that object and encoding the archiver with rootObject.
• + (BOOL)archiveRootObject:(id)rootObject Archives rootObject by encoding it as a data object in toFile:(NSString *)path an archiver and writing that data object to file path. Returns YES upon success.
• - (void)encodeArrayOfObjCType:(const char *)type Encodes an array of count data elements of the same count:(unsigned int)count Objective C data type. at:(const void *)array
• - (void)encodeConditionalObject:(id)object Encodes into the linearized data a conditional object that points back toward a root object. If nil is specified for object, it encodes it as nil unconditionally. Raises an NSInvalidArgumentException if no root object has been encoded.
• - (void)encodeRootObject:(id)rootObject Encodes the rootObject at the start of the linearized data representing the object graph. Raises an NSInvalidArgumentException if the root object has already been encoded.

• - (NSMutableData *)archiverData Returns the data object, in mutable form, that is associated with the receiving NSArchiver.

• - (NSString *)classNameEncodedForTrueClassName:(NSString *)trueName Returns the class name used to archive instances of the class trueName. See encodeClassName:intoClassName.
• - (void)encodeClassName:(NSString *)trueName Encodes in the archive a substitute class name intoClassName:(NSString *)inArchiveName) for the real class name (trueName).