Class

NSCoder

An abstract class that serves as the basis for objects that enable archiving and distribution of other objects.

Declaration

@interface NSCoder : NSObject

Overview

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 AVFoundation 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.

Topics

Inspecting a Coder

allowsKeyedCoding

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.

Encoding General Data

- 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.

- encodeInt:forKey:

Encodes intv and associates it with the string key.

- encodeInteger:forKey:

Encodes a given NSInteger and associates it with a given 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.

- encodeNXObject:

Encodes an old-style object onto the coder.

Deprecated
- encodeObject:

Encodes object.

- encodeObject:forKey:

Encodes the object objv and associates it with the string key.

- encodePoint:

Encodes point.

- encodePoint:forKey:

Encodes point and associates it with the string key.

- encodePropertyList:

Encodes the property list aPropertyList.

- encodeRect:

Encodes rect.

- encodeRect:forKey:

Encodes rect 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.

- encodeSize:

Encodes size.

- encodeSize:forKey:

Encodes size and associates it with the string key.

- 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.

Encoding Geometry-Based Data

- encodeCGPoint:forKey:

Encodes a point and associates it with the specified key in the receiver’s archive.

- encodeCGRect:forKey:

Encodes a rectangle and associates it with the specified key in the receiver’s archive.

- encodeCGSize:forKey:

Encodes size information and associates it with the specified key in the receiver’s archive.

- encodeCGAffineTransform:forKey:

Encodes an affine transform and associates it with the specified key in the receiver’s archive.

- encodeUIEdgeInsets:forKey:

Encodes edge inset data and associates it with the specified key in the receiver’s archive.

- encodeUIOffset:forKey:

Encodes offset data and associates it with the specified key in the receiver’s archive.

- encodeCGVector:forKey:

Encodes vector data and associates it with the specified key in the coder’s archive.

Encoding Core Media Time Structures

- encodeCMTime:forKey:

Encodes a given CMTime structure and associates it with a specified key.

- encodeCMTimeRange:forKey:

Encodes a given CMTimeRange structure and associates it with a specified key.

- encodeCMTimeMapping:forKey:

Encodes a given CMTimeMapping structure and associates it with a specified key.

Decoding General Data

- 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:. Subclasses must override this method.

- 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.

- 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.

- 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.

- 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.

- decodeNXObject

Decodes an object previously written with encodeNXObject:.

Deprecated
- 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.

- decodePoint

Decodes and returns an NSPoint structure that was previously encoded with encodePoint:.

- decodePointForKey:

Decodes and returns an NSPoint structure that was previously encoded with encodePoint:forKey:.

- decodePropertyList

Decodes a property list that was previously encoded with encodePropertyList:.

- decodeRect

Decodes and returns an NSRect structure that was previously encoded with encodeRect:.

- decodeRectForKey:

Decodes and returns an NSRect structure that was previously encoded with encodeRect:forKey:.

- decodeSize

Decodes and returns an NSSize structure that was previously encoded with encodeSize:.

- decodeSizeForKey:

Decodes and returns an NSSize structure that was previously encoded with encodeSize:forKey:.

- decodeValueOfObjCType:at:

Decodes a single value, whose Objective-C type is given by valueType.

Deprecated
- decodeValuesOfObjCTypes:

Decodes a series of potentially different Objective-C types.

- 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.

Decoding Color Struct Data

- decodeNXColor

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

Deprecated

Decoding Geometry-Based Data

- decodeCGPointForKey:

Decodes and returns the CGPoint structure associated with the specified key in the receiver’s archive.

- decodeCGRectForKey:

Decodes and returns the CGRect structure associated with the specified key in the receiver’s archive.

- decodeCGSizeForKey:

Decodes and returns the CGSize structure associated with the specified key in the receiver’s archive.

- decodeCGAffineTransformForKey:

Decodes and returns the CGAffineTransform structure associated with the specified key in the receiver’s archive.

- decodeUIEdgeInsetsForKey:

Decodes and returns the UIEdgeInsets structure associated with the specified key in the receiver’s archive.

- decodeUIOffsetForKey:

Decodes and returns the UIOffset structure associated with the specified key in the receiver’s archive.

- decodeCGVectorForKey:

Decodes and returns the CGVector data associated with the specified key in the coder’s archive.

Decoding Core Media Time Structures

- decodeCMTimeForKey:

Returns the CMTime structure associated with a given key.

- decodeCMTimeRangeForKey:

Returns the CMTimeRange structure associated with a given key.

- decodeCMTimeMappingForKey:

Returns the CMTimeMapping structure associated with a given key.

Secure Coding

requiresSecureCoding

Boolean value that indicates whether the coder requires secure coding.

allowedClasses

The set of coded classes allowed for secure coding.

Getting Version Information

systemVersion

The system version in effect for the archive.

- versionForClassName:

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

Managing Zones

- objectZone

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

- setObjectZone:

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

Error Codes

NSCoderErrorMaximum

The end of the range of error codes reserved for coder errors.

NSCoderErrorMinimum

The start of the range of error codes reserved for coder errors.

NSCoderReadCorruptError

Decoding failed due to corrupt data.

NSCoderValueNotFoundError

The requested data wasn’t found.

Instance Properties

Relationships

Inherits From

See Also

Keyed Archivers

NSKeyedArchiver

A coder that stores an object's data to an archive referenced by keys.

NSKeyedArchiverDelegate

The optional methods implemented by the delegate of a keyed archiver.

NSKeyedUnarchiver

A decoder that restores data from an archive referenced by keys.

NSKeyedUnarchiverDelegate

The optional methods implemented by the delegate of a keyed unarchiver.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software