# NSKeyedArchiver documentation

rfm@gnu.org
Generated at 2025-02-13 06:02:40 +0000
2004 Free Software Foundation, Inc.
Software documentation for the NSKeyedArchiver class
Foundation/NSKeyedArchiver.h
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:
anObject
toFile:
aPath
Encodes anObject and writes the resulting data ti aPath.
archivedDataWithRootObject:
anObject
Encodes anObject and returns the resulting data object.
archivedDataWithRootObject:
anObject
requiringSecureCoding:
requiresSecureCoding
error:
error
Encodes anObject and returns the resulting data object. Allows secure coding if specified. Returns an error if an object violates secure coding rules.
classNameForClass:
aClass
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:
aString
forClass:
aClass
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:
aClass
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
Returns the delegate set for the receiver, or `nil` of none is set.
encodeBool:
aBool
forKey:
aKey
Encodes aBool and associates the encoded value with aKey.
encodeBytes:
aPointer
length:
length
forKey:
aKey
Encodes the data of the specified length and pointed to by aPointer, and associates the encoded value with aKey.
encodeConditionalObject:
anObject
forKey:
aKey
Encodes anObject and associates the encoded value with aKey, but only if anObject has already been encoded using -encodeObject:forKey:
encodeDouble:
aDouble
forKey:
aKey
Encodes aDouble and associates the encoded value with aKey.
encodeFloat:
aFloat
forKey:
aKey
Encodes aFloat and associates the encoded value with aKey.
encodeInt32:
anInteger
forKey:
aKey
Encodes anInteger and associates the encoded value with aKey.
encodeInt64:
anInteger
forKey:
aKey
Encodes anInteger and associates the encoded value with aKey.
encodeInt:
anInteger
forKey:
aKey
Encodes anInteger and associates the encoded value with aKey.
encodeObject:
anObject
forKey:
aKey
Encodes anObject and associates the encoded value with aKey.
finishEncoding
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:
data
Initialise the receiver to encode an archive into the supplied data object.
outputFormat
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.
requiresSecureCoding
Returns whether the current instance of the archiver needs secure coding.
setClassName:
aString
forClass:
aClass
Sets the name with which instances of aClass are encoded.
The value of aString must be the name of an existing class.
setDelegate:
anObject
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:
format
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.
setRequiresSecureCoding:
flag
Sets whether the current instance of the archiver needs secure coding.
Software documentation for the NSKeyedUnarchiver class
Foundation/NSKeyedArchiver.h
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:
aString
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:
aClass
forClassName:
aString
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:
data
Decodes from byte array in data and returns resulting root object.
unarchiveObjectWithFile:
aPath
Decodes from file contents at aPath and returns resulting root object.
unarchivedArrayOfObjectsOfClass:
cls
fromData:
data
error:
error
Description forthcoming.
unarchivedArrayOfObjectsOfClasses:
classes
fromData:
data
error:
error
Description forthcoming.
unarchivedDictionaryWithKeysOfClass:
keyCls
objectsOfClass:
valueCls
fromData:
data
error:
error
Description forthcoming.
unarchivedDictionaryWithKeysOfClasses:
keyClasses
objectsOfClasses:
valueClasses
fromData:
data
error:
error
Description forthcoming.
unarchivedObjectOfClass:
cls
fromData:
data
error:
error
Description forthcoming.
unarchivedObjectOfClasses:
classes
fromData:
data
error:
error
Description forthcoming.
classForClassName:
aString
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:
aKey
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:
aKey
Returns a boolean value associated with aKey. This value must previously have been encoded using -encodeBool:forKey:
decodeBytesForKey:
aKey
returnedLength:
length
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:
aKey
Returns a double value associated with aKey. This value must previously have been encoded using -encodeDouble:forKey: or -encodeFloat:forKey:
decodeFloatForKey:
aKey
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:
aKey
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:
aKey
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:
aKey
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:
aKey
Returns an object value associated with aKey. This value must previously have been encoded using -encodeObject:forKey: or -encodeConditionalObject:forKey:
delegate
Returns the delegate of the unarchiver.
finishDecoding
Tells receiver that you are done retrieving from archive, so the delegate should be allowed to perform close-up operations.
initForReadingWithData:
data
Prepare to read data from key archive (created by NSKeyedArchiver ). Be sure to call -finishDecoding when done.
requiresSecureCoding
Returns whether the current instance of the archiver needs secure coding.
setClass:
aClass
forClassName:
aString
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.
setDelegate:
delegate
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.
setRequiresSecureCoding:
flag
Sets whether the current instance of the archiver needs secure coding.
Software documentation for the NSCoder(NSGeometryKeyedCoding) category
Foundation/NSKeyedArchiver.h
Methods for encoding/decoding points, rectangles, and sizes.
decodePointForKey:
aKey
Decodes an `NSPoint` object.
decodeRectForKey:
aKey
Decodes an `NSRect` object.
decodeSizeForKey:
aKey
Decodes an `NSSize` object.
encodePoint:
aPoint
forKey:
aKey
Encodes an `NSPoint` object.
encodeRect:
aRect
forKey:
aKey
Encodes an `NSRect` object.
encodeSize:
aSize
forKey:
aKey
Encodes an `NSSize` object.
Software documentation for the NSKeyedArchiver(Internal) category
Foundation/NSKeyedArchiver.h
Internal methods. Do not use.
_encodeArrayOfObjects:
anArray
forKey:
aKey
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:
anObject
forKey:
aKey
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
Foundation/NSKeyedArchiver.h
Internal methods. Do not use.
_decodeArrayOfObjectsForKey:
aKey
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:
aKey
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.
replaceObject:
oldObj
withObject:
newObj
This method is used to replace oldObj with newObj in the map that is maintained in NSKeyedUnarchiver.
Software documentation for the NSObject(NSKeyedArchiverDelegate) category
Foundation/NSKeyedArchiver.h
Informal protocol implemented by delegates of NSKeyedArchiver .
archiver:
anArchiver
didEncodeObject:
anObject
Sent when encoding of anObject has completed except in the case of conditional encoding.
archiver:
anArchiver
willEncodeObject:
anObject
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:
anArchiver
willReplaceObject:
anObject
withObject:
newObject
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:
anArchiver
Sent when the encoding process is complete.
archiverWillFinish:
anArchiver
Sent when the encoding process is about to finish.
Software documentation for the NSObject(NSKeyedArchiverObjectSubstitution) category
Foundation/NSKeyedArchiver.h
Methods by which a class may control its archiving by the NSKeyedArchiver .
classForKeyedArchiver
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:
archiver
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
Foundation/NSKeyedArchiver.h
Informal protocol implemented by delegates of NSKeyedUnarchiver .
unarchiver:
anUnarchiver
cannotDecodeObjectOfClassName:
aName
originalClasses:
classNames
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:
anUnarchiver
didDecodeObject:
anObject
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:
anUnarchiver
willReplaceObject:
anObject
withObject:
newObject
Sent whenever object replacement occurs during decoding, eg by the -replacementObjectForKeyedArchiver: method.
unarchiverDidFinish:
anUnarchiver
Sent when unarchiving is about to complete.
unarchiverWillFinish:
anUnarchiver
Sent when unarchiving has been completed.
Software documentation for the NSObject(NSKeyedUnarchiverObjectSubstitution) category
Foundation/NSKeyedArchiver.h
Methods by which a class may control its unarchiving by the NSKeyedArchiver .
classForKeyedUnarchiver
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.