NSKeyedArchiver documentation

Implements keyed archiving of object graphs. This archiver should be used instead of NSArchiver for new implementations. Classes implementing <NSCoding> should check the [NSCoder -allowsKeyedCoding] method and if the response is YES, encode/decode their fields using the ...forKey: NSCoder methods, which provide for more robust forwards and backwards compatibility.

archiveRootObject: toFile:

+ (BOOL) archiveRootObject: (id)anObject toFile: (NSString*)aPath;

Availability: MacOS-X 10.0.0

Encodes anObject and writes the resulting data ti aPath.

archivedDataWithRootObject:

+ (NSData*) archivedDataWithRootObject: (id)anObject;

Availability: MacOS-X 10.0.0

Encodes anObject and returns the resulting data object.

classNameForClass:

+ (NSString*) classNameForClass: (Class)aClass;

Availability: MacOS-X 10.0.0

Returns the class name with which the NSKeyedArchiver class will encode instances of aClass, or nil if no name mapping has been set using the +setClassName:forClass: method.

setClassName: forClass:

+ (void) setClassName: (NSString*)aString forClass: (Class)aClass;

Availability: MacOS-X 10.0.0

Sets the class name with which the NSKeyedArchiver class will encode instances of aClass. This mapping is used only if no class name mapping has been set for the individual instance of NSKeyedArchiver being used.
The value of aString must be the name of an existing class.
If the value of aString is nil, any mapping for aClass is removed.

classNameForClass:

- (NSString*) classNameForClass: (Class)aClass;

Availability: MacOS-X 10.0.0

Returns any mapping for the name of aClass which was previously set for the receiver using the -setClassName:forClass: method.
Returns nil if no such mapping exists, even if one has been set using the class method +setClassName:forClass:

delegate

- (id) delegate;

Availability: MacOS-X 10.0.0

Returns the delegate set for the receiver, or nil of none is set.

encodeBool: forKey:

- (void) encodeBool: (BOOL)aBool forKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Encodes aBool and associates the encoded value with aKey.

encodeBytes: length: forKey:

- (void) encodeBytes: (const uint8_t*)aPointer length: (unsigned)length forKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Encodes the data of the specified length and pointed to by aPointer, and associates the encoded value with aKey.

encodeConditionalObject: forKey:

- (void) encodeConditionalObject: (id)anObject forKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Encodes anObject and associates the encoded value with aKey, but only if anObject has already been encoded using -encodeObject:forKey:

encodeDouble: forKey:

- (void) encodeDouble: (double)aDouble forKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Encodes aDouble and associates the encoded value with aKey.

encodeFloat: forKey:

- (void) encodeFloat: (float)aFloat forKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Encodes aFloat and associates the encoded value with aKey.

encodeInt32: forKey:

- (void) encodeInt32: (int32_t)anInteger forKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Encodes anInteger and associates the encoded value with aKey.

encodeInt64: forKey:

- (void) encodeInt64: (int64_t)anInteger forKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Encodes anInteger and associates the encoded value with aKey.

encodeInt: forKey:

- (void) encodeInt: (int)anInteger forKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Encodes anInteger and associates the encoded value with aKey.

encodeObject: forKey:

- (void) encodeObject: (id)anObject forKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Encodes anObject and associates the encoded value with aKey.

finishEncoding

- (void) finishEncoding;

Availability: MacOS-X 10.0.0

Ends the encoding process and causes the encoded archive to be placed in the mutable data object supplied when the receiver was initialised.
This method must be called at the end of encoding, and nothing may be encoded after this method is called.

initForWritingWithMutableData:

- (id) initForWritingWithMutableData: (NSMutableData*)data;

Availability: MacOS-X 10.0.0

Initialise the receiver to encode an archive into the supplied data object.

outputFormat

- (NSPropertyListFormat) outputFormat;

Availability: MacOS-X 10.0.0

Returns the output format of the archived data... this should default to the MacOS-X binary format, but we don't support that yet, so the -setOutputFormat: method should be used to set a supported format.

setClassName: forClass:

- (void) setClassName: (NSString*)aString forClass: (Class)aClass;

Availability: MacOS-X 10.0.0

Sets the name with which instances of aClass are encoded.
The value of aString must be the name of an existing class.

setDelegate:

- (void) setDelegate: (id)anObject;

Availability: MacOS-X 10.0.0

Sets the receivers delegate. The delegate should conform to the NSObject(NSKeyedArchiverDelegate) informal protocol.
NB. the delegate is not retained, so you must ensure that it is not deallocated before the archiver has finished with it.

setOutputFormat:

- (void) setOutputFormat: (NSPropertyListFormat)format;

Availability: MacOS-X 10.0.0

Specifies the output format of the archived data... this should default to the MacOS-X binary format, but we don't support that yet, so the -setOutputFormat: method should be used to set a supported format.

Software documentation for the NSKeyedUnarchiver class

NSKeyedUnarchiver : NSCoder

Implements keyed unarchiving of object graphs. The keyed archiver should be used instead of NSArchiver for new implementations. Classes implementing <NSCoding> should check the [NSCoder -allowsKeyedCoding] method and if the response is YES, encode/decode their fields using the ...forKey: NSCoder methods, which provide for more robust forwards and backwards compatibility.

classForClassName:

+ (Class) classForClassName: (NSString*)aString;

Availability: MacOS-X 10.0.0

Returns class substituted for class name specified by aString when encountered in the archive being decoded from, or nil if there is no specific translation mapping. Each instance also maintains a translation map, which is searched first for a match during decoding.

setClass: forClassName:

+ (void) setClass: (Class)aClass forClassName: (NSString*)aString;

Availability: MacOS-X 10.0.0

Sets class substituted for class name specified by aString when encountered in the archive being decoded from, or nil if there is no specific translation mapping. Each instance also maintains a translation map, which is searched first for a match during decoding.

unarchiveObjectWithData:

+ (id) unarchiveObjectWithData: (NSData*)data;

Availability: MacOS-X 10.0.0

Decodes from byte array in data and returns resulting root object.

unarchiveObjectWithFile:

+ (id) unarchiveObjectWithFile: (NSString*)aPath;

Availability: MacOS-X 10.0.0

Decodes from file contents at aPath and returns resulting root object.

classForClassName:

- (Class) classForClassName: (NSString*)aString;

Availability: MacOS-X 10.0.0

Returns class substituted for class name specified by aString when encountered in the archive being decoded from, or nil if there is no specific translation mapping. The class as a whole also maintains a translation map, which is searched on decoding if no match found here.

containsValueForKey:

- (BOOL) containsValueForKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Sets class substituted for class name specified by aString when encountered in the archive being decoded from, or nil if there is no specific translation mapping. Each instance also maintains a translation map, which is searched first for a match during decoding.

decodeBoolForKey:

- (BOOL) decodeBoolForKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Returns a boolean value associated with aKey. This value must previously have been encoded using -encodeBool:forKey:

decodeBytesForKey: returnedLength:

- (const uint8_t*) decodeBytesForKey: (NSString*)aKey returnedLength: (unsigned*)length;

Availability: MacOS-X 10.0.0

Returns a pointer to a byte array associated with aKey.
Returns the length of the data in aLength.
This value must previously have been encoded using -encodeBytes:length:forKey:

decodeDoubleForKey:

- (double) decodeDoubleForKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Returns a double value associated with aKey. This value must previously have been encoded using -encodeDouble:forKey: or -encodeFloat:forKey:

decodeFloatForKey:

- (float) decodeFloatForKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Returns a float value associated with aKey. This value must previously have been encoded using -encodeFloat:forKey: or -encodeDouble:forKey:
Precision may be lost (or an exception raised if the value will not fit in a float) if the value was encoded using -encodeDouble:forKey: ,

decodeInt32ForKey:

- (int32_t) decodeInt32ForKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Returns a 32-bit integer value associated with aKey. This value must previously have been encoded using -encodeInt:forKey: , -encodeInt32:forKey: , or -encodeInt64:forKey: .
An exception will be raised if the value does not fit in a 32-bit integer.

decodeInt64ForKey:

- (int64_t) decodeInt64ForKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Returns a 64-bit integer value associated with aKey. This value must previously have been encoded using -encodeInt:forKey: , -encodeInt32:forKey: , or -encodeInt64:forKey: .

decodeIntForKey:

- (int) decodeIntForKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Returns an integer value associated with aKey. This value must previously have been encoded using -encodeInt:forKey: , -encodeInt32:forKey: , or -encodeInt64:forKey: .
An exception will be raised if the value does not fit in an integer.

decodeObjectForKey:

- (id) decodeObjectForKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Returns an object value associated with aKey. This value must previously have been encoded using -encodeObject:forKey: or -encodeConditionalObject:forKey:

delegate

- (id) delegate;

Availability: MacOS-X 10.0.0

Returns the delegate of the unarchiver.

finishDecoding

- (void) finishDecoding;

Availability: MacOS-X 10.0.0

Tells receiver that you are done retrieving from archive, so the delegate should be allowed to perform close-up operations.

initForReadingWithData:

- (id) initForReadingWithData: (NSData*)data;

Availability: MacOS-X 10.0.0

Prepare to read data from key archive (created by NSKeyedArchiver ). Be sure to call -finishDecoding when done.

setClass: forClassName:

- (void) setClass: (Class)aClass forClassName: (NSString*)aString;

Availability: MacOS-X 10.0.0

setDelegate:

- (void) setDelegate: (id)delegate;

Availability: MacOS-X 10.0.0

Sets the receivers delegate. The delegate should conform to the NSObject(NSKeyedUnarchiverDelegate) informal protocol.
NB. the delegate is not retained, so you must ensure that it is not deallocated before the unarchiver has finished with it.

Software documentation for the NSCoder(NSGeometryKeyedCoding) category

NSCoder(NSGeometryKeyedCoding)

decodePointForKey:

- (NSPoint) decodePointForKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Decodes an NSPoint object.

decodeRectForKey:

- (NSRect) decodeRectForKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Decodes an NSRect object.

decodeSizeForKey:

- (NSSize) decodeSizeForKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Decodes an NSSize object.

encodePoint: forKey:

- (void) encodePoint: (NSPoint)aPoint forKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Encodes an NSPoint object.

encodeRect: forKey:

- (void) encodeRect: (NSRect)aRect forKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Encodes an NSRect object.

encodeSize: forKey:

- (void) encodeSize: (NSSize)aSize forKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Encodes an NSSize object.

Software documentation for the NSKeyedArchiver(Internal) category

NSKeyedArchiver(Internal)

_encodeArrayOfObjects: forKey:

- (void) _encodeArrayOfObjects: (NSArray*)anArray forKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Warning the underscore at the start of the name of this method indicates that it is private, for internal use only, and you should not use the method in your code.
Internal method used to encode an array relatively efficiently.
Some MacOS-X library classes seem to use this.

_encodePropertyList: forKey:

- (void) _encodePropertyList: (id)anObject forKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Warning the underscore at the start of the name of this method indicates that it is private, for internal use only, and you should not use the method in your code.

Software documentation for the NSKeyedUnarchiver(Internal) category

NSKeyedUnarchiver(Internal)

_decodeArrayOfObjectsForKey:

- (id) _decodeArrayOfObjectsForKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Warning the underscore at the start of the name of this method indicates that it is private, for internal use only, and you should not use the method in your code.
Internal method used to decode an array relatively efficiently.
Some MacOS-X library classes seem to use this.

_decodePropertyListForKey:

- (id) _decodePropertyListForKey: (NSString*)aKey;

Availability: MacOS-X 10.0.0

Warning the underscore at the start of the name of this method indicates that it is private, for internal use only, and you should not use the method in your code.

Software documentation for the NSObject(NSKeyedArchiverDelegate) category

NSObject(NSKeyedArchiverDelegate)

archiver: didEncodeObject:

- (void) archiver: (NSKeyedArchiver*)anArchiver didEncodeObject: (id)anObject;

Availability: MacOS-X 10.0.0

An empty method provided for subclasses to override.

Sent when encoding of anObject has completed except in the case of conditional encoding.

archiver: willEncodeObject:

- (id) archiver: (NSKeyedArchiver*)anArchiver willEncodeObject: (id)anObject;

Availability: MacOS-X 10.0.0

An empty method provided for subclasses to override.

Sent when anObject is about to be encoded (or conditionally encoded) and provides the receiver with an opportunity to change the actual object stored into the archive by returning a different value (otherwise it should return anObject ).
The method is not called for encoding of nil or for encoding of any object for which has already been called.
The method is called after the -replacementObjectForKeyedArchiver: method.

archiver: willReplaceObject: withObject:

- (void) archiver: (NSKeyedArchiver*)anArchiver willReplaceObject: (id)anObject withObject: (id)newObject;

Availability: MacOS-X 10.0.0

An empty method provided for subclasses to override.

Sent whenever object replacement occurs during encoding, either by the -replacementObjectForKeyedArchiver: method or because the delegate has returned a changed value using the -archiver:willEncodeObject: method.

archiverDidFinish:

- (void) archiverDidFinish: (NSKeyedArchiver*)anArchiver;

Availability: MacOS-X 10.0.0

An empty method provided for subclasses to override.

Sent when the encoding process is complete.

archiverWillFinish:

- (void) archiverWillFinish: (NSKeyedArchiver*)anArchiver;

Availability: MacOS-X 10.0.0

An empty method provided for subclasses to override.

Sent when the encoding process is about to finish.

Software documentation for the NSObject(NSKeyedArchiverObjectSubstitution) category

NSObject(NSKeyedArchiverObjectSubstitution)

classForKeyedArchiver

- (Class) classForKeyedArchiver;

Availability: MacOS-X 10.0.0

This message is sent to objects being encoded, to allow them to choose to be encoded a different class. If this returns nil it is treated as if it returned the class of the object.
After this method is applied, any class name mapping set in the archiver is applied to its result.
The default implementation returns the result of the -classForArchiver method.

replacementObjectForKeyedArchiver:

- (id) replacementObjectForKeyedArchiver: (NSKeyedArchiver*)archiver;

Availability: MacOS-X 10.0.0

This message is sent to objects being encoded, to allow them to choose to be encoded a different object by returning the alternative object.
The default implementation returns the result of calling the -replacementObjectForArchiver: method with a nil argument.
This is called only if no mapping has been set up in the archiver already.

Software documentation for the NSObject(NSKeyedUnarchiverDelegate) category

NSObject(NSKeyedUnarchiverDelegate)

unarchiver: cannotDecodeObjectOfClassName: originalClasses:

- (Class) unarchiver: (NSKeyedUnarchiver*)anUnarchiver cannotDecodeObjectOfClassName: (NSString*)aName originalClasses: (NSArray*)classNames;

Availability: MacOS-X 10.0.0

An empty method provided for subclasses to override.

Sent if the named class is not available during decoding.
The value of aName is the class name being decoded (after any name mapping has been applied).
The classNames array contains the original name of the class encoded in the archive, and is followed by each of its superclasses in turn.
The delegate may either return a class object for the unarchiver to use to continue decoding, or may return nil to abort the decoding process.

unarchiver: didDecodeObject:

- (id) unarchiver: (NSKeyedUnarchiver*)anUnarchiver didDecodeObject: (id)anObject;

Availability: MacOS-X 10.0.0

An empty method provided for subclasses to override.

Sent when anObject is decoded. The receiver may return either anObject or some other object (including nil). If a value other than anObject is returned, it is used to replace anObject.

unarchiver: willReplaceObject: withObject:

- (void) unarchiver: (NSKeyedUnarchiver*)anUnarchiver willReplaceObject: (id)anObject withObject: (id)newObject;

Availability: MacOS-X 10.0.0

An empty method provided for subclasses to override.

Sent whenever object replacement occurs during decoding, eg by the -replacementObjectForKeyedArchiver: method.

unarchiverDidFinish:

- (void) unarchiverDidFinish: (NSKeyedUnarchiver*)anUnarchiver;

Availability: MacOS-X 10.0.0

An empty method provided for subclasses to override.

Sent when unarchiving is about to complete.

unarchiverWillFinish:

- (void) unarchiverWillFinish: (NSKeyedUnarchiver*)anUnarchiver;

Availability: MacOS-X 10.0.0

An empty method provided for subclasses to override.

Sent when unarchiving has been completed.

Software documentation for the NSObject(NSKeyedUnarchiverObjectSubstitution) category

NSObject(NSKeyedUnarchiverObjectSubstitution)

classForKeyedUnarchiver

+ (Class) classForKeyedUnarchiver;

Availability: MacOS-X 10.0.0

Sent during unarchiving to permit classes to substitute a different class for decoded instances of themselves.
Default implementation returns the receiver.
Overrides the mappings set up within the receiver.

Authors

Contents -

NSKeyedArchiver : NSCoder

NSKeyedUnarchiver : NSCoder

NSCoder(NSGeometryKeyedCoding)

NSKeyedArchiver(Internal)

NSKeyedUnarchiver(Internal)

NSObject(NSKeyedArchiverDelegate)

NSObject(NSKeyedArchiverObjectSubstitution)

NSObject(NSKeyedUnarchiverDelegate)

NSObject(NSKeyedUnarchiverObjectSubstitution)