Class: NSCoder
Overview
The NSCoder abstract class declares the interface used by concrete subclasses to transfer objects and other Objective-C data items between memory and some other format. This capability provides the basis for archiving (where objects and data items are stored on disk) and distribution (where objects and data items are copied between different processes or threads). The concrete subclasses provided by Foundation for these purposes are NSArchiver, NSUnarchiver, NSKeyedArchiver, NSKeyedUnarchiver, and NSPortCoder. Concrete subclasses of NSCoder are referred to in general as coder classes, and instances of these classes as coder objects (or simply coders). A coder object that can only encode values is referred to as an encoder object, and one that can only decode values as a decoder object.
Direct Known Subclasses
Instance Method Summary (collapse)
-
- allowedClasses
Get the current set of coded classes that allow secured coding..
-
- allowsKeyedCoding
Returns a Boolean value that indicates whether the receiver supports keyed coding of objects.
-
- containsValueForKey:
Returns a Boolean value that indicates whether an encoded value is available for a string.
-
- decodeArrayOfObjCType:count:at:
Decodes an array of count items, whose Objective-C type is given by itemType.
-
- decodeBoolForKey:
Decodes and returns a boolean value that was previously encoded with encodeBool:forKey: and associated with the string key.
-
- decodeBytesForKey:returnedLength:
Decodes a buffer of data that was previously encoded with encodeBytes:length:forKey: and associated with the string key.
-
- decodeBytesWithReturnedLength:
Decodes a buffer of data whose types are unspecified.
-
- decodeDataObject
Decodes and returns an NSData object that was previously encoded with encodeDataObject:.
-
- decodeDoubleForKey:
Decodes and returns a double value that was previously encoded with either encodeFloat:forKey: or encodeDouble:forKey: and associated with the string key.
-
- decodeFloatForKey:
Decodes and returns a float value that was previously encoded with encodeFloat:forKey: or encodeDouble:forKey: and associated with the string key.
-
- decodeInt32ForKey:
Decodes and returns a 32-bit integer value that was previously encoded with encodeInt:forKey:, encodeInteger:forKey:, encodeInt32:forKey:, or encodeInt64:forKey: and associated with the string key.
-
- decodeInt64ForKey:
Decodes and returns a 64-bit integer value that was previously encoded with encodeInt:forKey:, encodeInteger:forKey:, encodeInt32:forKey:, or encodeInt64:forKey: and associated with the string key.
-
- decodeIntegerForKey:
Decodes and returns an NSInteger value that was previously encoded with encodeInt:forKey:, encodeInteger:forKey:, encodeInt32:forKey:, or encodeInt64:forKey: and associated with the string key.
-
- decodeIntForKey:
Decodes and returns an int value that was previously encoded with encodeInt:forKey:, encodeInteger:forKey:, encodeInt32:forKey:, or encodeInt64:forKey: and associated with the string key.
-
- decodeObject
Decodes an Objective-C object that was previously encoded with any of the encode…Object: methods.
-
- decodeObjectForKey:
Decodes and returns an Objective-C object that was previously encoded with encodeObject:forKey: or encodeConditionalObject:forKey: and associated with the string key.
-
- decodeObjectOfClass:forKey:
Decodes an object for the key, restricted to the specified class.
-
- decodeObjectOfClasses:forKey:
Decodes an object for the key, restricted to the specified classes.
-
- decodePropertyListForKey:
Returns a decoded property list for the specified key.
-
- decodeValueOfObjCType:at:
Decodes a single value, whose Objective-C type is given by valueType.
-
- decodeValuesOfObjCTypes:
Decodes a series of potentially different Objective-C types.
-
- encodeArrayOfObjCType:count:at:
Encodes an array of count items, whose Objective-C type is given by itemType.
-
- encodeBool:forKey:
Encodes boolv and associates it with the string key.
-
- encodeBycopyObject:
Can be overridden by subclasses to encode object so that a copy, rather than a proxy, is created upon decoding.
-
- encodeByrefObject:
Can be overridden by subclasses to encode object so that a proxy, rather than a copy, is created upon decoding.
-
- encodeBytes:length:
Encodes a buffer of data whose types are unspecified.
-
- encodeBytes:length:forKey:
Encodes a buffer of data, bytesp, whose length is specified by lenv, and associates it with the string key.
-
- encodeConditionalObject:
Can be overridden by subclasses to conditionally encode object, preserving common references to that object.
-
- encodeConditionalObject:forKey:
Conditionally encodes a reference to objv and associates it with the string key only if objv has been unconditionally encoded with encodeObject:forKey:.
-
- encodeDataObject:
Encodes a given NSData object.
-
- encodeDouble:forKey:
Encodes realv and associates it with the string key.
-
- encodeFloat:forKey:
Encodes realv and associates it with the string key.
-
- encodeInt32:forKey:
Encodes the 32-bit integer intv and associates it with the string key.
-
- encodeInt64:forKey:
Encodes the 64-bit integer intv and associates it with the string key.
-
- encodeInt:forKey:
Encodes intv and associates it with the string key.
-
- encodeInteger:forKey:
Encodes a given NSInteger and associates it with a given key.
-
- encodeObject:
Encodes object.
-
- encodeObject:forKey:
Encodes the object objv and associates it with the string key.
-
- encodeRootObject:
Can be overridden by subclasses to encode an interconnected group of Objective-C objects, starting with rootObject.
-
- encodeValueOfObjCType:at:
Must be overridden by subclasses to encode a single value residing at address, whose Objective-C type is given by valueType.
-
- encodeValuesOfObjCTypes:
Encodes a series of values of potentially differing Objective-C types.
-
- objectZone
This method is present for historical reasons and has no effect.
-
- requiresSecureCoding
Returns whether the coder requires secure coding.
-
- setObjectZone:
This method is present for historical reasons and has no effect.
-
- systemVersion
During encoding, this method should return the system version currently in effect.
-
- versionForClassName:
This method is present for historical reasons and is not used with keyed archivers.
Methods inherited from NSObject
#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version
Constructor Details
This class inherits a constructor from NSObject
Dynamic Method Handling
This class handles dynamic methods through the method_missing method in the class NSObject
Instance Method Details
- (NSSet) allowedClasses
Get the current set of coded classes that allow secured coding.. Secure coders check this set of allowed classes before decoding objects, and all objects must implement the NSSecureCoding protocol.
- (Boolean) allowsKeyedCoding
Returns a Boolean value that indicates whether the receiver supports keyed coding of objects. The default implementation returns NO. Concrete subclasses that support keyed coding, such as NSKeyedArchiver, need to override this method to return YES.
- (Boolean) containsValueForKey(key)
Returns a Boolean value that indicates whether an encoded value is available for a string. Subclasses must override this method if they perform keyed coding. The string is passed as key.
- (Object) decodeArrayOfObjCType(itemType, count:count, at:address)
Decodes an array of count items, whose Objective-C type is given by itemType. The items are decoded into the buffer beginning at address, which must be large enough to contain them all. itemType must contain exactly one type code. NSCoder’s implementation invokes decodeValueOfObjCType:at: to decode the entire array of items.This method matches an encodeArrayOfObjCType:count:at: message used during encoding.For information on creating an Objective-C type code suitable for itemType, see “Type Encodings”.
- (Boolean) decodeBoolForKey(key)
Decodes and returns a boolean value that was previously encoded with encodeBool:forKey: and associated with the string key. Subclasses must override this method if they perform keyed coding.
- (Integer) decodeBytesForKey(key, returnedLength:lengthp)
Decodes a buffer of data that was previously encoded with encodeBytes:length:forKey: and associated with the string key.
The buffer’s length is returned by reference in lengthp. The returned bytes are immutable. Subclasses must override this method if they perform keyed coding.- (Object) decodeBytesWithReturnedLength(numBytes)
Decodes a buffer of data whose types are unspecified. NSCoder’s implementation invokes decodeValueOfObjCType:at: to decode the data as a series of bytes, which this method then places into a buffer and returns. The buffer’s length is returned by reference in numBytes. If you need the bytes beyond the scope of the current @autoreleasepool block, you must copy them.This method matches an encodeBytes:length: message used during encoding.
- (NSData) decodeDataObject
Decodes and returns an NSData object that was previously encoded with encodeDataObject:. Subclasses must override this method. The implementation of your overriding method must match the implementation of your encodeDataObject: method. For example, a typical encodeDataObject: method encodes the number of bytes of data followed by the bytes themselves. Your override of this method must read the number of bytes, create an NSData object of the appropriate size, and decode the bytes into the new NSData object.
- (Float) decodeDoubleForKey(key)
Decodes and returns a double value that was previously encoded with either encodeFloat:forKey: or encodeDouble:forKey: and associated with the string key. Subclasses must override this method if they perform keyed coding.
- (Float) decodeFloatForKey(key)
Decodes and returns a float value that was previously encoded with encodeFloat:forKey: or encodeDouble:forKey: and associated with the string key. If the value was encoded as a double, the extra precision is lost. If the encoded real value does not fit into a float, the method raises an NSRangeException. Subclasses must override this method if they perform keyed coding.
- (Integer) decodeInt32ForKey(key)
Decodes and returns a 32-bit integer value that was previously encoded with encodeInt:forKey:, encodeInteger:forKey:, encodeInt32:forKey:, or encodeInt64:forKey: and associated with the string key. If the encoded integer does not fit into a 32-bit integer, the method raises an NSRangeException. Subclasses must override this method if they perform keyed coding.
- (Integer) decodeInt64ForKey(key)
Decodes and returns a 64-bit integer value that was previously encoded with encodeInt:forKey:, encodeInteger:forKey:, encodeInt32:forKey:, or encodeInt64:forKey: and associated with the string key. Subclasses must override this method if they perform keyed coding.
- (Integer) decodeIntegerForKey(key)
Decodes and returns an NSInteger value that was previously encoded with encodeInt:forKey:, encodeInteger:forKey:, encodeInt32:forKey:, or encodeInt64:forKey: and associated with the string key. If the encoded integer does not fit into the NSInteger size, the method raises an NSRangeException. Subclasses must override this method if they perform keyed coding.
- (Integer) decodeIntForKey(key)
Decodes and returns an int value that was previously encoded with encodeInt:forKey:, encodeInteger:forKey:, encodeInt32:forKey:, or encodeInt64:forKey: and associated with the string key. If the encoded integer does not fit into the default integer size, the method raises an NSRangeException. Subclasses must override this method if they perform keyed coding.
- (Object) decodeObject
Decodes an Objective-C object that was previously encoded with any of the encode…Object: methods. NSCoder’s implementation invokes decodeValueOfObjCType:at: to decode the object data.Subclasses may need to override this method if they override any of the corresponding encode…Object: methods. For example, if an object was encoded conditionally using the encodeConditionalObject: method, this method needs to check whether the object had actually been encoded.
- (Object) decodeObjectForKey(key)
Decodes and returns an Objective-C object that was previously encoded with encodeObject:forKey: or encodeConditionalObject:forKey: and associated with the string key. Subclasses must override this method if they perform keyed coding.
- (Object) decodeObjectOfClass(aClass, forKey:key)
Decodes an object for the key, restricted to the specified class. If the coder responds YES to requiresSecureCoding, then an exception will be thrown if the class to be decoded does not implement NSSecureCoding or is not isKindOfClass: of aClass.If the coder responds NO to requiresSecureCoding, then the class argument is ignored and no check of the class of the decoded object is performed, exactly as if decodeObjectForKey: had been called.
- (Object) decodeObjectOfClasses(classes, forKey:key)
Decodes an object for the key, restricted to the specified classes. The class of the object may be any class in the classes set, or a subclass of any class in the set. Otherwise, the behavior is the same as decodeObjectOfClass:forKey:.
- (Object) decodePropertyListForKey(key)
Returns a decoded property list for the specified key. This method calls decodeObjectOfClasses:forKey: with a set allowing only property list types.
- (Object) decodeValueOfObjCType(valueType, at:data)
Decodes a single value, whose Objective-C type is given by valueType.
valueType must contain exactly one type code, and the buffer specified by data must be large enough to hold the value corresponding to that type code. For information on creating an Objective-C type code suitable for valueType, see “Type Encodings”.Subclasses must override this method and provide an implementation to decode the value. In your overriding implementation, decode the value into the buffer beginning at data.This method matches an encodeValueOfObjCType:at: message used during encoding.- (Object) decodeValuesOfObjCTypes(valueTypes, ...)
Decodes a series of potentially different Objective-C types.
valueTypes is a single C string containing any number of type codes. The variable arguments to this method consist of one or more pointer arguments, each of which specifies the buffer in which to place a single decoded value. For each type code in valueTypes, you must specify a corresponding pointer argument whose buffer is large enough to hold the decoded value.This method matches an encodeValuesOfObjCTypes: message used during encoding.NSCoder’s implementation invokes decodeValueOfObjCType:at: to decode individual types. Subclasses that implement the decodeValueOfObjCType:at: method do not need to override this method.For information on creating Objective-C type codes suitable for valueTypes, see “Type Encodings”.- (Object) encodeArrayOfObjCType(itemType, count:count, at:address)
Encodes an array of count items, whose Objective-C type is given by itemType. The values are encoded from the buffer beginning at address. itemType must contain exactly one type code. NSCoder’s implementation invokes encodeValueOfObjCType:at: to encode the entire array of items. Subclasses that implement the encodeValueOfObjCType:at: method do not need to override this method.This method must be matched by a subsequent decodeArrayOfObjCType:count:at: message.For information on creating an Objective-C type code suitable for itemType, see “Type Encodings”.
- (Object) encodeBool(boolv, forKey:key)
Encodes boolv and associates it with the string key. Subclasses must override this method if they perform keyed coding.
- (Object) encodeBycopyObject(object)
Can be overridden by subclasses to encode object so that a copy, rather than a proxy, is created upon decoding. NSCoder’s implementation simply invokes encodeObject:.This method must be matched by a corresponding decodeObject message.
- (Object) encodeByrefObject(object)
Can be overridden by subclasses to encode object so that a proxy, rather than a copy, is created upon decoding. NSCoder’s implementation simply invokes encodeObject:.This method must be matched by a corresponding decodeObject message.
- (Object) encodeBytes(address, length:numBytes)
Encodes a buffer of data whose types are unspecified. The buffer to be encoded begins at address, and its length in bytes is given by numBytes.This method must be matched by a corresponding decodeBytesWithReturnedLength: message.
- (Object) encodeBytes(bytesp, length:lenv, forKey:key)
Encodes a buffer of data, bytesp, whose length is specified by lenv, and associates it with the string key. Subclasses must override this method if they perform keyed coding.
- (Object) encodeConditionalObject(object)
Can be overridden by subclasses to conditionally encode object, preserving common references to that object. In the overriding method, object should be encoded only if it’s unconditionally encoded elsewhere (with any other encode…Object: method).This method must be matched by a subsequent decodeObject message. Upon decoding, if object was never encoded unconditionally, decodeObject returns nil in place of object. However, if object was encoded unconditionally, all references to object must be resolved.NSCoder’s implementation simply invokes encodeObject:.
- (Object) encodeConditionalObject(objv, forKey:key)
Conditionally encodes a reference to objv and associates it with the string key only if objv has been unconditionally encoded with encodeObject:forKey:. Subclasses must override this method if they support keyed coding.The encoded object is decoded with the decodeObjectForKey: method. If objv was never encoded unconditionally, decodeObjectForKey: returns nil in place of objv.
- (Object) encodeDataObject(data)
Encodes a given NSData object. Subclasses must override this method.This method must be matched by a subsequent decodeDataObject message.
- (Object) encodeDouble(realv, forKey:key)
Encodes realv and associates it with the string key. Subclasses must override this method if they perform keyed coding.
- (Object) encodeFloat(realv, forKey:key)
Encodes realv and associates it with the string key. Subclasses must override this method if they perform keyed coding.
- (Object) encodeInt32(intv, forKey:key)
Encodes the 32-bit integer intv and associates it with the string key. Subclasses must override this method if they perform keyed coding.
- (Object) encodeInt64(intv, forKey:key)
Encodes the 64-bit integer intv and associates it with the string key. Subclasses must override this method if they perform keyed coding.
- (Object) encodeInt(intv, forKey:key)
Encodes intv and associates it with the string key. Subclasses must override this method if they perform keyed coding.
- (Object) encodeInteger(intv, forKey:key)
Encodes a given NSInteger and associates it with a given key. Subclasses must override this method if they perform keyed coding.
- (Object) encodeObject(object)
Encodes object. NSCoder’s implementation simply invokes encodeValueOfObjCType:at: to encode object. Subclasses can override this method to encode a reference to object instead of object itself. For example, NSArchiver detects duplicate objects and encodes a reference to the original object rather than encode the same object twice.This method must be matched by a subsequent decodeObject message.
- (Object) encodeObject(objv, forKey:key)
Encodes the object objv and associates it with the string key. Subclasses must override this method to identify multiple encodings of objv and encode a reference to objv instead. For example, NSKeyedArchiver detects duplicate objects and encodes a reference to the original object rather than encode the same object twice.
- (Object) encodeRootObject(rootObject)
Can be overridden by subclasses to encode an interconnected group of Objective-C objects, starting with rootObject. NSCoder’s implementation simply invokes encodeObject:.This method must be matched by a subsequent decodeObject message.
- (Object) encodeValueOfObjCType(valueType, at:address)
Must be overridden by subclasses to encode a single value residing at address, whose Objective-C type is given by valueType.
valueType must contain exactly one type code.This method must be matched by a subsequent decodeValueOfObjCType:at: message.For information on creating an Objective-C type code suitable for valueType, see “Type Encodings”.- (Object) encodeValuesOfObjCTypes(valueTypes, ...)
Encodes a series of values of potentially differing Objective-C types.
valueTypes is a C string containing any number of type codes. The variable arguments to this method consist of one or more pointer arguments, each of which specifies a buffer containing the value to be encoded. For each type code in valueTypes, you must specify a corresponding pointer argument.This method must be matched by a subsequent decodeValuesOfObjCTypes: message.NSCoder’s implementation invokes encodeValueOfObjCType:at: to encode individual types. Subclasses that implement the encodeValueOfObjCType:at: method do not need to override this method. However, subclasses that provide a more efficient approach for encoding a series of values may override this method to implement that approach.For information on creating Objective-C type codes suitable for valueTypes, see “Type Encodings”.- (NSZone) objectZone
This method is present for historical reasons and has no effect. NSCoder’s implementation returns the default memory zone, as given by NSDefaultMallocZone().
- (Boolean) requiresSecureCoding
Returns whether the coder requires secure coding. Secure coders check a set of allowed classes before decoding objects, and all objects must implement the NSSecureCoding protocol.
- (Object) setObjectZone(zone)
This method is present for historical reasons and has no effect.
- (unsigned) systemVersion
During encoding, this method should return the system version currently in effect. During decoding, this method should return the version that was in effect when the data was encoded.By default, this method returns the current system version, which is appropriate for encoding but not for decoding. Subclasses that implement decoding must override this method to return the system version of the data being decoded.
- (Integer) versionForClassName(className)
This method is present for historical reasons and is not used with keyed archivers. The version number does apply not to NSKeyedArchiver/NSKeyedUnarchiver. A keyed archiver does not encode class version numbers.