Object encoding

Object encoding converts an object’s class identity and state to a format that can be stored or transferred between processes. The class type and instance data are written to a byte stream that can persist after a program terminates. When the program is launched again, a newly allocated object can decode the stored representation of itself and restore itself to its previous runtime state. Encoding usually occurs in concert with archiving, which puts a graph of objects into a format (an archive) that can be written to the file system; unarchiving operates on an archive, asking each object in the stored graph to decode itself.

Object encoding is also used in the Mac OS X distributed objects API for transferring objects from one process to another. However, its most common use is for archiving, which like a property list, is a mechanism for object persistence.

How to Encode and Decode Objects

For your subclass to encode and decode its instances, it must conform to the NSCoding protocol and implement two methods: initWithCoder: and encodeWithCoder:. When a program unarchives or archives an object graph, these methods are invoked. In the encodeWithCoder: method, you encode the values of an object‚Äôs important instance variables; in the initWithCoder: method, you decode those values and reassign them to their instance variables. If an object receives an initWithCoder: message, none of its initializer methods are invoked.

The sole argument of initWithCoder: and encodeWithCoder: is an NSCoder object whose purpose is to perform the actual decoding or encoding. Because NSCoder is an abstract class, the coder object is in most cases an instance of one of the following concrete subclasses: NSKeyedArchiver, NSKeyedUnarchiver, NSArchiver, NSUnarchiver. The archiver classes declare methods for encoding an object‚Äôs instance variables; the unarchiver classes declare methods for decoding instance variables.

The NSCoder methods work on objects, scalars, C arrays, structures, and strings, and on pointers to these types. Before you encode or decode an instance variable of your own class, be sure to first invoke the superclass implementation of initWithCoder: or encodeWithCoder:. When you decode objects from the byte stream, be sure to retain or copy them when you assign them to their instance variables.

Keyed Versus Sequential Archiving

Two of the concrete NSCoder subclasses are different from each other in a fundamental way. The ‚Äúkeyed‚Äù archiver class (NSKeyedArchiver and NSKeyedUnarchiver) associate an encoded value with a string key and use that same key when decoding that value; thus instance variables can be encoded and decoded in any sequence. With the other type of coder (NSArchiver and NSUnarchiver) you encode instance variables in a certain sequence, and you must decode them in the same sequence. The sequential coders should be used only with legacy code; new subclasses should use keyed archive coders.