Mac Developer Library

Developer

Foundation Framework Reference NSCoder Class Reference

Options
Deployment Target:

On This Page
Language:

NSCoder

The NSCoder abstract class declares the interface used by concrete subclasses to transfer objects and other values 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.

NSCoder operates on objects, scalars, C arrays, structures, and strings, and on pointers to these types. It does not handle types whose implementation varies across platforms, such as union, void *, function pointers, and long chains of pointers. A coder object stores object type information along with the data, so an object decoded from a stream of bytes is normally of the same class as the object that was originally encoded into the stream. An object can change its class when encoded, however; this is described in Archives and Serializations Programming Guide.

The AV Foundation framework adds methods to the NSCoder class to make it easier to create archives including Core Media time structures, and extract Core Media time structure from archives.

Subclassing Notes

For details of how to create a subclass of NSCoder, see Subclassing NSCoder in Archives and Serializations Programming Guide.

  • A Boolean value that indicates whether the receiver supports keyed coding of objects. (read-only)

    Declaration

    Swift

    var allowsKeyedCoding: Bool { get }

    Objective-C

    @property(readonly) BOOL allowsKeyedCoding

    Discussion

    NOfalse by default. Concrete subclasses that support keyed coding, such as NSKeyedArchiver, need to override this property to return YEStrue.

    Availability

    Available in OS X v10.2 and later.

  • Returns a Boolean value that indicates whether an encoded value is available for a string.

    Declaration

    Swift

    func containsValueForKey(_ key: String) -> Bool

    Objective-C

    - (BOOL)containsValueForKey:(NSString *)key

    Discussion

    Subclasses must override this method if they perform keyed coding.

    The string is passed as key.

    Availability

    Available in OS X v10.2 and later.

  • - decodeNXColor (OS X v10.9)

    Decodes a color structure from NEXTSTEP Release 3 or earlier and returns an NSColor object.

    Declaration

    Objective-C

    - (NSColor *)decodeNXColor

    Return Value

    An autoreleased NSColor object. Returns nil if the archived color is invalid.

    Discussion

    This method does not have a matching method for encoding an NXColor structure. Encode an NSColor object instead.

    NXColor, a type that dates from pre-OpenStep versions of NEXTSTEP, was a struct. Its replacement, NSColor, is a class. The difficulties of converting from a struct to a class require a special method like decodeNXColor.

    The decodeNXColor method becomes part of the NSCoder class only for apps that use AppKit.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

  • Boolean value that indicates whether the coder requires secure coding. (read-only)

    Declaration

    Swift

    var requiresSecureCoding: Bool { get }

    Objective-C

    @property(readonly) BOOL requiresSecureCoding

    Discussion

    YEStrue if this coder requires secure coding; NOfalse otherwise.

    Secure coders check a set of allowed classes before decoding objects, and all objects must implement the NSSecureCoding protocol.

    Availability

    Available in OS X v10.8 and later.

  • The set of coded classes allowed for secure coding. (read-only)

    Declaration

    Swift

    var allowedClasses: Set<NSObject>? { get }

    Objective-C

    @property(readonly, copy) NSSet <Class> *allowedClasses

    Discussion

    Secure coders check this set of allowed classes before decoding objects, and all objects must implement the NSSecureCoding protocol.

    Availability

    Available in OS X v10.8 and later.

  • The system version in effect for the archive. (read-only)

    Declaration

    Swift

    var systemVersion: UInt32 { get }

    Objective-C

    @property(readonly) unsigned int systemVersion

    Discussion

    During encoding, the current version. During decoding, the version that was in effect when the data was encoded.

    Subclasses that implement decoding must override this property to return the system version of the data being decoded.

    Availability

    Available in OS X v10.0 and later.

  • This method is present for historical reasons and is not used with keyed archivers.

    Declaration

    Swift

    func versionForClassName(_ className: String) -> Int

    Objective-C

    - (NSInteger)versionForClassName:(NSString *)className

    Return Value

    The version in effect for the class named className or NSNotFound if no class named className exists.

    Discussion

    The version number does apply not to NSKeyedArchiver/NSKeyedUnarchiver. A keyed archiver does not encode class version numbers.

    Availability

    Available in OS X v10.0 and later.

  • This method is present for historical reasons and has no effect.

    Declaration

    Objective-C

    - (NSZone *)objectZone

    Discussion

    NSCoder’s implementation returns the default memory zone, as given by NSDefaultMallocZone().

    Availability

    Available in OS X v10.0 and later.

  • This method is present for historical reasons and has no effect.

    Declaration

    Objective-C

    - (void)setObjectZone:(NSZone *)zone

    Availability

    Available in OS X v10.0 and later.