Up

NSArchiver class reference

Authors

Andrew Kachites McCallum (mccallum@gnu.ai.mit.edu)
Richard Frith-Macdonald (rfm@gnu.org)
Richard Frith-Macdonald (richard@brainstorm.co.uk)

Version: 35503

Date: 2012-09-03 14:36:45 +0100 (Mon, 03 Sep 2012)

Copyright: (C) 1995, 1996, 1997, 1998 Free Software Foundation, Inc.


Contents -

  1. Software documentation for the NSArchiver class
  2. Software documentation for the NSUnarchiver class
  3. Software documentation for the NSArchiver(GNUstep) category
  4. Software documentation for the NSUnarchiver(GNUstep) category

Software documentation for the NSArchiver class

NSArchiver : NSCoder

Declared in:
Foundation/NSArchiver.h
Availability: OpenStep

Implementation of NSCoder capable of creating sequential archives which must be read in the same order they were written. This class implements methods for saving to and restoring from a serial archive (usually a file on disk, but can be an NSData object) as well as methods that can be used by objects that need to write/restore themselves.

Note, the sibling class NSKeyedArchiver supports a form of archive that is more robust to class changes, and is recommended over this one.

Method summary

archiveRootObject: toFile: 

+ (BOOL) archiveRootObject: (id)rootObject toFile: (NSString*)path;
Availability: OpenStep

Writes out serialized representation of object and, recursively, any other objects it holds references to.

archivedDataWithRootObject: 

+ (NSData*) archivedDataWithRootObject: (id)rootObject;
Availability: OpenStep

Writes serialized representation of object and, recursively, any other objects it holds references to, to byte array.

archiverData 

- (NSMutableData*) archiverData;
Availability: OpenStep

Returns whatever data has been encoded thus far.

classNameEncodedForTrueClassName: 

- (NSString*) classNameEncodedForTrueClassName: (NSString*)trueName;
Availability: OpenStep

Returns substitute class used to encode objects of given class. This would have been set through an earlier call to [NSArchiver -encodeClassName:intoClassName:].

encodeClassName: intoClassName: 

- (void) encodeClassName: (NSString*)trueName intoClassName: (NSString*)inArchiveName;
Availability: OpenStep

Specify substitute class used in archiving objects of given class. This class is written to the archive as the class to use for restoring the object, instead of what is returned from [NSObject -classForArchiver]. This can be used to provide backward compatibility across class name changes. The object is still encoded by calling encodeWithCoder: as normal.

initForWritingWithMutableData: 

- (id) initForWritingWithMutableData: (NSMutableData*)mdata;
Availability: OpenStep

Init instance that will archive its data to mdata. (Even if [archiveRootObject:toFile:] is called, this still gets written to.)

replaceObject: withObject: 

- (void) replaceObject: (id)object withObject: (id)newObject;
Availability: MacOS-X 10.0.0

Set encoder to write out newObject in place of object.

Software documentation for the NSUnarchiver class

NSUnarchiver : NSCoder

Declared in:
Foundation/NSArchiver.h
Availability: OpenStep

This class reconstructs objects from an archive.


Re-using the archiver

The -resetUnarchiverWithData:atIndex: method lets you re-use the archive to decode a new data object or, in conjunction with the 'cursor' method (which reports the current decoding position in the archive), decode a second archive that exists in the data object after the first one.

Subclassing with different input format.

NSUnarchiver normally reads directly from an NSData object using the methods -

-deserializeTypeTag:andCrossRef:atCursor:
to decode type tags for data items, the tag is the first byte of the character encoding string for the data type (as provided by '@encode(xxx)'), possibly with the top bit set to indicate that what follows is a crossreference to an item already encoded.
Also decode a crossreference number either to identify the following item, or to refer to a previously encoded item. Objects, Classes, Selectors, CStrings and Pointer items have crossreference encoding, other types do not.
[NSData -deserializeDataAt:ofObjCType:atCursor:context:]
to decode all other information.

NSUnarchiver normally uses other NSData methods to read the archive header information from within the method: [-deserializeHeaderAt:version:classes:objects:pointers:] to read a fixed size header including archiver version (obtained by [self systemVersion]) and crossreference table sizes.

To subclass NSUnarchiver, you must implement your own versions of the four methods above, and override the 'directDataAccess' method to return NO so that the archiver knows to use your serialization methods rather than those in the NSData object.

Method summary

classNameDecodedForArchiveClassName: 

+ (NSString*) classNameDecodedForArchiveClassName: (NSString*)nameInArchive;
Availability: OpenStep

Returns class name unarchivers will use to instantiate encoded objects when they report their class name as nameInArchive.

decodeClassName: asClassName: 

+ (void) decodeClassName: (NSString*)nameInArchive asClassName: (NSString*)trueName;
Availability: OpenStep

Sets class name unarchivers will use to instantiate encoded objects when they report their class name as nameInArchive. This can be used to support backwards compatibility across class name changes.

unarchiveObjectWithData: 

+ (id) unarchiveObjectWithData: (NSData*)anObject;
Availability: OpenStep

Creates an NSUnarchiver to read from anObject and returns result of sending [NSCoder -decodeObject] to it.

unarchiveObjectWithFile: 

+ (id) unarchiveObjectWithFile: (NSString*)path;
Availability: OpenStep

Creates an NSUnarchiver to read from path and returns result of sending [NSCoder -decodeObject] to it.

classNameDecodedForArchiveClassName: 

- (NSString*) classNameDecodedForArchiveClassName: (NSString*)nameInArchive;
Availability: OpenStep

Returns class name this unarchiver uses to instantiate encoded objects when they report their class name as nameInArchive.

decodeClassName: asClassName: 

- (void) decodeClassName: (NSString*)nameInArchive asClassName: (NSString*)trueName;
Availability: OpenStep

Set class name this unarchiver uses to instantiate encoded objects when they report their class name as nameInArchive. This can be used to provide backward compatibility across class name changes.

initForReadingWithData: 

- (id) initForReadingWithData: (NSData*)anObject;
Availability: OpenStep

Set up to read objects from data buffer anObject.

isAtEnd 

- (BOOL) isAtEnd;
Availability: OpenStep

Returns whether have currently read through all of data buffer or file this unarchiver was initialized with.

objectZone 

- (NSZone*) objectZone;
Availability: OpenStep

Returns zone unarchived objects will be allocated from.

replaceObject: withObject: 

- (void) replaceObject: (id)anObject withObject: (id)replacement;
Availability: MacOS-X 10.0.0

Set unarchiver to replace anObject with replacement whenever it is found decoded from the archive.

setObjectZone: 

- (void) setObjectZone: (NSZone*)aZone;
Availability: OpenStep

Sets zone unarchived objects will be allocated from.

systemVersion 

- (unsigned int) systemVersion;
Availability: OpenStep

Returns system version archive was encoded by.

Software documentation for the NSArchiver(GNUstep) category

NSArchiver(GNUstep)

Declared in:
Foundation/NSArchiver.h
Availability: OpenStep, Base Likely to be changed/moved/removed at 1.17.0

Category for compatibility with old GNUstep encoding.
Method summary

directDataAccess 

- (BOOL) directDataAccess;
Availability: OpenStep, Base Likely to be changed/moved/removed at 1.17.0

Returns YES.

resetArchiver 

- (void) resetArchiver;
Availability: OpenStep, Base Likely to be changed/moved/removed at 1.17.0

Allow reuse of archiver (clears class substitution maps, etc.) but do not clear out current serialized data.

serializeHeaderAt: version: classes: objects: pointers: 

- (void) serializeHeaderAt: (unsigned)positionInData version: (unsigned)systemVersion classes: (unsigned)classCount objects: (unsigned)objectCount pointers: (unsigned)pointerCount;
Availability: OpenStep, Base Likely to be changed/moved/removed at 1.17.0

Writes out header for GNUstep archive format.

Software documentation for the NSUnarchiver(GNUstep) category

NSUnarchiver(GNUstep)

Declared in:
Foundation/NSArchiver.h
Availability: Not in OpenStep/MacOS-X, Base 0.0.1

Category for compatibility with old GNUstep encoding.
Method summary

cursor 

- (unsigned) cursor;
Availability: Not in OpenStep/MacOS-X, Base 0.0.1

Return current position within archive byte array.

deserializeHeaderAt: version: classes: objects: pointers: 

- (void) deserializeHeaderAt: (unsigned*)pos version: (unsigned*)v classes: (unsigned*)c objects: (unsigned*)o pointers: (unsigned*)p;
Availability: Not in OpenStep/MacOS-X, Base 0.0.1

Reads in header for GNUstep archive format.

directDataAccess 

- (BOOL) directDataAccess;
Availability: Not in OpenStep/MacOS-X, Base 0.0.1

Returns YES.

resetUnarchiverWithData: atIndex: 

- (void) resetUnarchiverWithData: (NSData*)anObject atIndex: (unsigned)pos;
Availability: Not in OpenStep/MacOS-X, Base 0.0.1

Prepare for reuse of the unarchiver to unpack a new archive, specified in anObject, starting at pos. Reads archive header.


Up