Overview
NSUnarchiver, a concrete subclass of NSCoder, defines methods for decoding a set of Objective-C objects from an archive. Such archives are produced by objects of the NSArchiver class.
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 NSUnarchiver
- – initForReadingWithData:
Decoding Objects
- + unarchiveObjectWithData:
- + unarchiveObjectWithFile:
Managing an NSUnarchiver
- – isAtEnd
- – objectZone
- – setObjectZone:
- – systemVersion
Substituting Classes or Objects
- + classNameDecodedForArchiveClassName:
- + decodeClassName:asClassName:
- – classNameDecodedForArchiveClassName:
- – decodeClassName:asClassName:
- – replaceObject:withObject:
Class Methods
classNameDecodedForArchiveClassName:
Returns the name of the class used when instantiating objects whose ostensible class, according to the archived data, is a given name.
+ (NSString *)classNameDecodedForArchiveClassName:(NSString *)nameInArchive
Parameters
nameInArchive
The name of a class.
Return Value
The name of the class used when instantiating objects whose ostensible class, according to the archived data, is nameInArchive. Returns nameInArchive if no substitute name has been specified using the class method (not the instance method) decodeClassName:asClassName:.
Discussion
Note that each individual instance of NSUnarchiver can be given its own class name mappings by invoking the instance method decodeClassName:asClassName:. The NSUnarchiver class has no information about these instance-specific mappings, however, so they don’t affect the return value of classNameDecodedForArchiveClassName:.
Availability
- Available in OS X v10.0 and later.
See Also
- – classNameDecodedForArchiveClassName:
Declared In
NSArchiver.h
decodeClassName:asClassName:
Instructs instances of NSUnarchiver to use the class with a given name when instantiating objects whose ostensible class, according to the archived data, is another given name.
+ (void)decodeClassName:(NSString *)nameInArchive asClassName:(NSString *)trueName
Parameters
nameInArchive
The ostensible name of a class in an archive.
trueName
The name of the class to use when instantiating objects whose ostensible class, according to the archived data, is nameInArchive.
Discussion
This method enables easy conversion of unarchived data when the name of a class has changed since the archive was created.
Note that there is also an instance method of the same name. An instance of NSUnarchiver can maintain its own mapping of class names. However, if both the class method and the instance method have been invoked using an identical value for nameInArchive, the class method takes precedence.
Availability
- Available in OS X v10.0 and later.
See Also
- + classNameDecodedForArchiveClassName:
- – decodeClassName:asClassName:
Declared In
NSArchiver.h
unarchiveObjectWithData:
Decodes and returns the object archived in a given NSData object.
+ (id)unarchiveObjectWithData:(NSData *)data
Parameters
data
An NSData object that contains an archive created using NSArchiver.
Return Value
The object, or object graph, that was archived in data. Returns nil if data cannot be unarchived.
Discussion
This method invokes initForReadingWithData: and decodeObject to create a temporary NSUnarchiver object that decodes the object. If the archived object is the root of a graph of objects, the entire graph is unarchived.
Availability
- Available in OS X v10.0 and later.
See Also
- encodeRootObject: (NSArchiver)
Related Sample Code
Declared In
NSArchiver.h
unarchiveObjectWithFile:
Decodes and returns the object archived in the file path.
+ (id)unarchiveObjectWithFile:(NSString *)path
Parameters
path
The path to a file than contains an archive created using NSArchiver.
Return Value
The object, or object graph, that was archived in the file at path. Returns nil if the file at path cannot be unarchived.
Discussion
This convenience method reads the file by invoking the NSData method dataWithContentsOfFile: and then invokes unarchiveObjectWithData:.
Availability
- Available in OS X v10.0 and later.
Declared In
NSArchiver.h
Instance Methods
classNameDecodedForArchiveClassName:
Returns the name of the class that will be used when instantiating objects whose ostensible class, according to the archived data, is a given name.
- (NSString *)classNameDecodedForArchiveClassName:(NSString *)nameInArchive
Parameters
nameInArchive
The ostensible name of a class in an archive.
Return Value
The name of the class that will be used when instantiating objects whose ostensible class, according to the archived data, is nameInArchive. Returns nameInArchive unless a substitute name has been specified using the instance method (not the class method) decodeClassName:asClassName:.
Availability
- Available in OS X v10.0 and later.
See Also
- + classNameDecodedForArchiveClassName:
Declared In
NSArchiver.h
decodeClassName:asClassName:
Instructs the receiver to use the class with a given name when instantiating objects whose ostensible class, according to the archived data, is another given name.
- (void)decodeClassName:(NSString *)nameInArchive asClassName:(NSString *)trueName
Parameters
nameInArchive
The ostensible name of a class in an archive.
trueName
The name of the class to use when instantiating objects whose ostensible class, according to the archived data, is nameInArchive.
Discussion
This method enables easy conversion of unarchived data when the name of a class has changed since the archive was created.
Note that there’s also a class method of the same name. The class method has precedence in case of conflicts.
Availability
- Available in OS X v10.0 and later.
See Also
- – classNameDecodedForArchiveClassName:
- + decodeClassName:asClassName:
Declared In
NSArchiver.h
initForReadingWithData:
Returns an NSUnarchiver object initialized to read an archive from a given data object.
- (id)initForReadingWithData:(NSData *)data
Parameters
data
The archive data.
Return Value
An NSUnarchiver object initialized to read an archive from data. Returns nil if data is not a valid archive.
Discussion
The method decodes the system version number that was archived in data prepares the NSUnarchiver object for a subsequent invocation of decodeObject.
Raises an NSInvalidArgumentException if data is nil.
Availability
- Available in OS X v10.0 and later.
See Also
- – systemVersion
Declared In
NSArchiver.h
isAtEnd
Returns a Boolean value that indicates whether the receiver has reached the end of the encoded data while decoding.
- (BOOL)isAtEnd
Return Value
YES if the receiver has reached the end of the encoded data while decoding, otherwise NO.
Discussion
You can invoke this method after invoking decodeObject to discover whether the archive contains extra data following the encoded object graph. If it does, you can either ignore this anomaly or consider it an error.
Availability
- Available in OS X v10.0 and later.
Declared In
NSArchiver.h
objectZone
Returns the memory zone used to allocate decoded objects.
- (NSZone *)objectZone
Return Value
The memory zone used to allocate decoded objects.
Availability
- Available in OS X v10.0 and later.
See Also
- – setObjectZone:
Declared In
NSArchiver.h
replaceObject:withObject:
Causes the receiver to substitute one given object for another whenever the latter is extracted from the archive.
- (void)replaceObject:(id)object withObject:(id)newObject
Parameters
object
The archived object to replace.
newObject
The object with which to replace object.
Discussion
newObject can be of a different class from object, and the class mappings set by classNameDecodedForArchiveClassName: and decodeClassName:asClassName: are ignored.
Availability
- Available in OS X v10.0 and later.
Declared In
NSArchiver.h
setObjectZone:
Sets the memory zone used to allocate decoded objects.
- (void)setObjectZone:(NSZone *)zone
Parameters
zone
The memory zone used to allocate decoded objects.
Discussion
If zone is nil, or if this method is never invoked, the default zone is used, as given by NSDefaultMallocZone().
Availability
- Available in OS X v10.0 and later.
See Also
- – objectZone
Declared In
NSArchiver.h
systemVersion
Returns the system version number in effect when the archive was created.
- (unsigned)systemVersion
Return Value
The system version number in effect when the archive was created.
Discussion
This information is available as soon as the receiver has been initialized.
Availability
- Available in OS X v10.0 and later.
Declared In
NSArchiver.h
Copyright © 2006 Apple Computer, Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2006-05-23