NSCoding

Characteristic	Description
Adopted By:	NSObject
Declared In:	Foundation/NSObject.h

Protocol Description

The NSCoding protocol declares the two methods that a class must implement so that objects of that class can be encoded and decoded. This capability provides the basis for archiving (where objects and other structures are stored on disk) and distribution (where objects are copied to different address spaces).

When an object receives an encodeWithCoder: message, it should write its instance variables (and, through a message to super, the instance variables that it inherits) to the supplied NSCoder. Similarly, when an object receives an initWithCoder: message, it should initialize its instance variables (and inherited instance variables, again through a message to super) from the data in the supplied NSCoder. See the NSCoder and NSArchiver class specifications for more complete information.

Instance Methods

encodeWithCoder:

- (void)encodeWithCoder:(NSCoder *)aCoder

Encodes the receiver using aCoder.

initWithCoder:

- (id)initWithCoder:(NSCoder *)aDecoder

Initializes and returns a new instance from data in aDecoder.

NSCopying

Characteristic	Description
Adopted By:	Various OpenStep classes
Declared In:	Foundation/NSObject.h

Protocol Description

A class whose instances provide functional copies of themselves should adopt the NSCopying protocol. The exact meaning of "copy" can vary from class to class, but a copy must be a functionally independent object, identical to the original at the time the copy was made. Where the concept "immutable vs. mutable" applies to an object, this protocol produces immutable copies; see the NSMutableCopying protocol for details on making mutable copies. Property list classes (NSString, NSData, NSArray, and NSDictionary) guarantee immutable returned values.

In most cases, to produce a copy that's independent of the original, a deep copy must be made. In a deep copy every instance variable of the receiver is duplicated, instead of referencing the variable in the original object. If the receiver's instance variables themselves have instance variables, those too must be duplicated, and so on. A deep copy is thus a completely separate object from the original; changes to it don't affect the original, and changes to the original don't affect it. Further, for an immutable copy, no part at any level may be changed, making a copy a "snapshot" of the original object.

Making a complete deep copy isn't always needed. Some objects can reasonably share instance variables among themselves--a static string object that gets replaced but not modified, for example. In such cases your class can implement NSCopying more cheaply than it might otherwise need to.

The typical usage of NSCopying is to create "passing by value" value objects.

---

Note - Contrary to most methods, the returned object is owned by the caller, which is responsible for releasing it.

---

Instance Methods

copyWithZone:

- (id)copyWithZone:(NSZone *)zone

Returns a new instance that's a functional copy of the receiver. Memory for the new instance is allocated from zone. For collections, creates a deep (recursive) copy. The copy returned is immutable if the consideration "immutable vs. mutable" applies to the receiving object; otherwise the exact nature of the copy is determined by the class. The returned object is owned by the caller, who is responsible for releasing it.

NSLocking

Characteristic	Description
Adopted By:	NSConditionLock NSLock NSRecursiveLock
Declared In:	Foundation/NSLock.h

Protocol Description

NSLocking protocol is used by classes that provide lock objects. The lock objects provided by OpenStep are used only for protecting critical sections of code: sections that manipulate shared data and that can be executed simultaneously in several threads. Lock objects--except for NSConditionLock objects--contain no useful data.

Although an object that isn't a lock could adopt the NSLocking protocol, it may be more desirable to design the object so that all locking is handled internally, through normal use rather than requiring that the object be explicitly locked and unlocked.

In order to enable clients to only have locks when processes become multithreaded, it is permissible to unlock a lock freshly created (i.e. that has not been locked)--unless it is a recursive lock. Three classes conform to the NSLocking protocol:

Table 6-1 NSLocking

Class	Use
NSLock	Protect critical sections of code.
NSConditionLock	Protects critical sections of code, but can also be used to postpone entry to a critical section until a condition is met. This class is functionally a superset of the NSLock class, though unlocking is slightly more expensive.
NSRecursiveLock	Protects critical sections from access by multiple threads, but allows a single thread to acquire a lock several times without deadlocking.

None of these classes busy-waits while the lock is unavailable. All classes may all be efficiently used for long sections of atomic code. See the class specifications for these classes for further information on their behavior and usage.

Instance Methods

lock

- (void)lock

Acquires a lock. Applications generally do this when entering a critical section of their code. A thread will sleep if it can't immediately acquire the lock.

unlock

- (void)unlock

Releases a lock. Applications generally do this when exiting a critical section of their code.

NSMutableCopying

Characteristic	Description
Adopted By:	various OpenStep classes
Declared In:	Foundation/NSObject.h

Protocol Description

A class that defines an "immutable vs. mutable" distinction adopts this protocol to allow mutable copies of its instances to be made. A mutable copy of an object is usually a shallow copy (as opposed to the deep copy defined in the NSCopying protocol specification). The original and its copy share references to the same instance variables, so that if a component of the copy is changed, for example, that change is reflected in the original.

A class that doesn't define an "immutable vs. mutable" distinction but that needs to offer both deep and shallow copying shouldn't adopt this protocol. The NSCopying methods should by default be assumed to produce deep copies; the class can then also implement methods to produce shallow copies.

---

Note - Contrary to most methods, the returned value is owned by the caller, which is responsible for releasing it.

---

Instance Methods

mutableCopyWithZone:

- (id)mutableCopyWithZone:(NSZone *)zone

Returns a new instance that's a top level, mutable copy of the receiver. For a collection, objects in the collection are retained. Memory for the new instance is allocated from zone. The returned object is owned by the caller, which is responsible for releasing it.

NSObjCTypeSerializationCallBack

Characteristic	Description
Adopted By:	No OpenStep classes
Declared In:	Foundation/NSSerialization.h

Protocol Description

An object conforms to the NSObjCTypeSerializationCallBack protocol so that it can intervene in the serialization and deserialization process. The primary purpose of this protocol is to allow for the serialization of objects and other data types that aren't directly supported by OpenStep's serialization facility. (See the NSSerializer class specification for information on serialization.)

NSMutableData declares the method that's used to begin the serialization process:

- (void)serializeDataAt:(const void *)data
  ofObjCType:(const char *)type
  context:(id <NSObjCTypeSerializationCallBack>)callback

This method can serialized all standard Objective C types (int, float, character strings, and so on) except for objects, union, and void *. If, during the serialization process, an object is encountered, the object passed as the callback argument above is asked to provide the serialization.

Suppose that the type being serialized is a structure of this description:

struct stockRecord {
  NSString *stockName;
  float value;
};

The Objective C type code for this structure is {@f}, so the serialization process begins with this message: (Assume that theData is the NSMutableData object that's doing the serialization and helper is an object that conforms to the NSObjCTypeSerializationCallBack protocol.)

struct stockRecord aRecord = {@"aCompany", 34.7};
[theData serializeDataAt:&aRecord
    ofObjCType:"{@f}" context:helper];

Since the first field of the structure is an unsupported type, the helper object is sent a serializeObjectAt:ofObjCType:intoData: message, letting it serialize the object. helper might implement the method in this way:

- (void)serializeObjectAt:(id *)objectPtr
    ofObjCType:(const char *)type
    intoData:(NSMutableData *)theMutableData
{
    NSString *nameObject;
    char *companyName

    nameObject = *objectPtr;
    companyName = [nameObject cString];

    [theData serializeDataAt:&companyName
        ofObjCType:@encode(typeof(companyName))
        context:nil]
}

The callback object is free to serialize the target object as it wishes. In this case, helper simply extracts the company name from the NSString object and then has that character string serialized. Once this callback method finishes executing, the original method (serializeDataAt:ofObjCType:context:) resumes execution and serializes the second field of the structure. Since this second field contains a supported type (float), the callback method is not invoked again.

Deserialization follows a similar pattern, except in this case NSData declares the central method

deserializeDataAt:ofObjCType:atCursor:context:. The
deserialization of the example structure starts with a message to the NSData
object that contains the serialized data:
(unsigned *)cursor = 0;

[theData deserializeDataAt:&aRecord ofObjCType:"{@f}"
    cursor:&cursor context:helper];

(The cursor argument is a pointer to zero since we're starting at the beginning of the data in the NSData object.)

When this method is invoked, the callback object receives a deserializeObjectAt:ofObjCType:fromData:atCursor: message, as declared in this protocol. The callback object can then reestablish the first field of the structure. For example, helper might implement the method in this way:

- (void) deserializeObjectAt:(id *)objectPtr
  ofObjCType:(const char *)type
  fromData:(NSData *)data
  atCursor:(unsigned *)cursor
{
  char *companyName;

  [theData deserializeDataAt:&companyName ofObjCType:"*"
     atCursor:cursor context:nil];
  *objectPtr = [[NSString stringWithCString:companyName] retain];
}

Instance Methods

deserializeObjectAt:ofObjCType: fromData:atCursor:

- (void)deserializeObjectAt:(id *)object
    ofObjCType:(const char *)type fromData:(NSData *)data
    atCursor:(unsigned int*)cursor

The implementor of this method decodes the referenced object (which should always be of type "@") located at the cursor position in the data object. The decoded object is not autoreleased. See the description of NSData method deserializeDataAt:ofObjCType:context:.

serializeObjectAt:ofObjCType:intoData:

- (void)serializeObjectAt:(id *)object
    ofObjCType:(const char *)type
    intoData:(NSMutableData *)data

The implementor of this method encodes the referenced object (which should always be of type "@") in the data object. See the description of NSMutableData method serializeDataAt:ofObjCType:context:.

NSObject

Characteristic	Description
Adopted By:	NSObject
Declared In:	Foundation/NSObject.h

Protocol Description

The NSObject protocol declares methods that all objects should implement within OpenStep, no matter which root class they descend from (NSObject, NSProxy, or another root class). Some of the methods in this protocol reveal an object's primary attributes: its position in the class hierarchy, its conformance to other protocols, and whether it responds to specific messages. Other methods let the object be manipulated in various ways. For example, it can be asked to perform methods that are detemined at runtime (using the performSelector:... methods) or to participate in OpenStep's automatic deallocation scheme (using the retain, release, and autorelease methods). By conforming to this protocol, an object advertises that it has the basic behaviors necessary to work with the OpenStep container classes (such as NSArray and NSDictionary).

Instance Methods

autorelease

- (id)autorelease

As defined in the NSObject class, decrements the receiver's reference count. When the count reaches 0, adds the object to the current autorelease pool. Returns self. Objects in the pool are released later, typically at the top of the event loop.

class

- (Class)class

Returns the receiver's class object. See also superclass.

conformsToProtocol:

- (BOOL) conformsToProtocol:(Protocol *aProtocol)

Returns YES if the receiver's class conforms to aProtocol.

description

- (NSString)description

Returns text information about the receiver.

hash

- (unsigned int)hash

Returns an unsigned int that can be used as a table address in a hash table structure. Two objects that are equal must hash to the same value.

isEqual:

- (BOOL)isEqual:(id)anObject

Returns YES if the receiver and anObject have equal values, and returns NO otherwise.

isKindOfClass:

- (BOOL)isKindOfClass:(Class)aClass

Returns YES if the receiver is an instance of aClass or an instance of any class that inherits from aClass. Returns NO otherwise.

isMemberOfClass:

- (BOOL)isMemberOfClass:(Class)aClass

Returns YES if the receiver is an instance of aClass. Returns NO otherwise.

isProxy

- (BOOL)isProxy

Returns YES is an NSProxy, rather than an object that descends from the NSObject class. Returns NO otherwise.

performSelector:

- (id)performSelector:(SEL)selector

Sends an aSelector messsage to the receiver and returns the result of the message. If aSelector is NULL, and NSInvalidArgumentException is raised.

performSelector:withObject:

- (id)performSelector:(SEL)selector withObject:(id)anObject

Sends an aSelector messsage to the receiver with anObject as an argument, and returns the message result. If aSelector is NULL, and NSInvalidArgumentException is raised.

performSelector:withObject:withObject:

- (id)performSelector:(SEL)selector withObject:(id)anObject
    withObject:anotherObject

Sends an aSelector messsage to the receiver with anObject and anotherObject as arguments, and returns the message result. If aSelector is NULL, and NSInvalidArgumentException is raised.

release

- (void)release

Decrements the receiver's reference count. When the count reaches 0, the object is automatically deallocated immediately.

respondsToSelector:

- (BOOL)respondsToSelector:(SEL)aSelector

Returns YES if the receiver implements or inherits a method that can respond to aSelector messages. Returns NO otherwise.

retain

- (id)retain

As defined in the NSObject class, increments the receiver's reference count. Send an object a retain message when you want to prevent it from being deallocated without your permission. Returns self as a convenience. See also retainCount, release, autorelease.

retainCount

- (unsigned int)retainCount

Returns the receiver's reference count. This is useful for debugging.

self

- (id)self

Returns the receiver.

superclass

- (Class)superclass

Returns the class object for the receiver's superclass. See also class.

zone

- (NSZone *)zone

Returns a pointer to memory zone from which the receiver was allocated.