Up

# NSArchiver class reference

### Authors

Andrew Kachites McCallum (`mccallum@gnu.ai.mit.edu`)
Richard Frith-Macdonald (`rfm@gnu.org`)

Date: Generated at 2025-02-13 06:02:40 +0000

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

- -directDataAccess
- -resetArchiver
- -serializeHeaderAt:version:classes:objects:pointers:
- +archiveRootObject:toFile:
- +archivedDataWithRootObject:
- -archiverData
- -classNameEncodedForTrueClassName:
- -encodeClassName:intoClassName:
- -initForWritingWithMutableData:
- -replaceObject:withObject:

### 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

- -cursor
- -deserializeHeaderAt:version:classes:objects:pointers:
- -directDataAccess
- -resetUnarchiverWithData:atIndex:
- +classNameDecodedForArchiveClassName:
- +decodeClassName:asClassName:
- +unarchiveObjectWithData:
- +unarchiveObjectWithFile:
- -classNameDecodedForArchiveClassName:
- -decodeClassName:asClassName:
- -initForReadingWithData:
- -isAtEnd
- -objectZone
- -replaceObject:withObject:
- -setObjectZone:
- -systemVersion

### 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
- -resetArchiver
- -serializeHeaderAt:version:classes:objects:pointers:

### 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
- -deserializeHeaderAt:version:classes:objects:pointers:
- -directDataAccess
- -resetUnarchiverWithData:atIndex:

### 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