Up
Authors
- Richard Frith-Macdonald (
rfm@gnu.org
)
-
Copyright: (C) 2004 Free Software Foundation, Inc.
- Declared in:
- Foundation/NSKeyedArchiver.h
Availability: MacOS-X 10.0.0
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.
Method summary
+ (BOOL)
archiveRootObject: (id)anObject
toFile: (
NSString*)aPath;
Availability: MacOS-X 10.0.0
Encodes anObject and writes the resulting data ti aPath.
+ (
NSData*)
archivedDataWithRootObject: (id)anObject;
Availability: MacOS-X 10.0.0
Encodes anObject and returns the resulting data object.
+ (
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.
+ (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.
- (
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:
- (id)
delegate;
Availability: MacOS-X 10.0.0
Returns the delegate set for the receiver, or nil
of none is set.
- (void)
encodeBool: (BOOL)aBool
forKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
Encodes aBool and associates the encoded value with aKey.
- (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.
- (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:
- (void)
encodeDouble: (double)aDouble
forKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
Encodes aDouble and associates the encoded value with aKey.
- (void)
encodeFloat: (float)aFloat
forKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
Encodes aFloat and associates the encoded value with aKey.
- (void)
encodeInt32: (int32_t)anInteger
forKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
Encodes anInteger and associates the encoded value with aKey.
- (void)
encodeInt64: (int64_t)anInteger
forKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
Encodes anInteger and associates the encoded value with aKey.
- (void)
encodeInt: (int)anInteger
forKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
Encodes anInteger and associates the encoded value with aKey.
- (void)
encodeObject: (id)anObject
forKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
Encodes anObject and associates the encoded value with aKey.
- (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.
- (id)
initForWritingWithMutableData: (
NSMutableData*)data;
Availability: MacOS-X 10.0.0
Initialise the receiver to encode an archive into the supplied data object.
- (
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.
- (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.
- (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.
- (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.
- Declared in:
- Foundation/NSKeyedArchiver.h
Availability: MacOS-X 10.0.0
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.
Method summary
+ (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.
+ (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.
+ (id)
unarchiveObjectWithData: (
NSData*)data;
Availability: MacOS-X 10.0.0
Decodes from byte array in data and returns resulting root object.
+ (id)
unarchiveObjectWithFile: (
NSString*)aPath;
Availability: MacOS-X 10.0.0
Decodes from file contents at aPath and returns resulting root object.
- (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.
- (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.
- (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:
- (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:
- (double)
decodeDoubleForKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
- (float)
decodeFloatForKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
- (int32_t)
decodeInt32ForKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
- (int64_t)
decodeInt64ForKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
- (int)
decodeIntForKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
- (id)
decodeObjectForKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
- (id)
delegate;
Availability: MacOS-X 10.0.0
Returns the delegate of the unarchiver.
- (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.
- (id)
initForReadingWithData: (
NSData*)data;
Availability: MacOS-X 10.0.0
- (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.
- (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.
- Declared in:
- Foundation/NSKeyedArchiver.h
Availability: MacOS-X 10.0.0
Methods for encoding/decoding points, rectangles, and sizes.
Method summary
- (
NSPoint)
decodePointForKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
Decodes an NSPoint
object.
- (
NSRect)
decodeRectForKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
Decodes an NSRect
object.
- (
NSSize)
decodeSizeForKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
Decodes an NSSize
object.
- (void)
encodePoint: (
NSPoint)aPoint
forKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
Encodes an NSPoint
object.
- (void)
encodeRect: (
NSRect)aRect
forKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
Encodes an NSRect
object.
- (void)
encodeSize: (
NSSize)aSize
forKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
Encodes an NSSize
object.
- Declared in:
- Foundation/NSKeyedArchiver.h
Availability: MacOS-X 10.0.0
Internal methods. Do not use.
Method summary
- (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.
- (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.
- Declared in:
- Foundation/NSKeyedArchiver.h
Availability: MacOS-X 10.0.0
Internal methods. Do not use.
Method summary
- (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.
- (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.
- Declared in:
- Foundation/NSKeyedArchiver.h
Availability: MacOS-X 10.0.0
Method summary
- (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.
- (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.
- (void)
archiver: (
NSKeyedArchiver*)anArchiver
willReplaceObject: (id)anObject
withObject: (id)newObject;
Availability: MacOS-X 10.0.0
An empty method provided for subclasses to override.
- (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.
- (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.
- Declared in:
- Foundation/NSKeyedArchiver.h
Availability: MacOS-X 10.0.0
Methods by which a class may control its archiving by the
NSKeyedArchiver
.
Method summary
- (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.
- (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.
- Declared in:
- Foundation/NSKeyedArchiver.h
Availability: MacOS-X 10.0.0
Method summary
- (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.
- (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.
- (void)
unarchiver: (
NSKeyedUnarchiver*)anUnarchiver
willReplaceObject: (id)anObject
withObject: (id)newObject;
Availability: MacOS-X 10.0.0
An empty method provided for subclasses to override.
- (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.
- (void)
unarchiverWillFinish: (
NSKeyedUnarchiver*)anUnarchiver;
Availability: MacOS-X 10.0.0
An empty method provided for subclasses to override.
Sent when unarchiving has been completed.
- Declared in:
- Foundation/NSKeyedArchiver.h
Availability: MacOS-X 10.0.0
Methods by which a class may control its unarchiving by the
NSKeyedArchiver
.
Method summary
+ (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.
Up