This is NSCoder.rtf in view mode; [Download] [Up]
paperh18648 margl-907 margr0 margt0 margb0 fi0 ri0 ql sb0 f1 fs24 Copyright f3 'e3f1 1994 by NeXT Computer, Inc. All Rights Reserved.
s4 li100 fi0 ri1007 ql f0 b fs36 fs100
fs36 NSCoder
pard s11 li2872 fi-2771 ri1007 ql tx2872 f1 b0 fs28 fs48
fs28 f0 b fs24 Inherits From:tab b0 fs28 f1 NSObject
fs20
fs28 s6 f0 b fs24 Conforms To:tab b0 fs28 f1 NSObject (NSObject)
fs20
fs28 s7 f0 b fs24 Declared In:tab b0 fs28 f1 Foundation/NSCoder.h
fi0 Foundation/NSGeometry.h
fs20
fs28 pard s16 li100 fi0 ri1007 ql f0 b fs28 fs20
fs28 Class Description
fs14
fs28 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs2
fs28 NSCoder is an abstract class that declares the interface used by subclasses to take objects from dynamic memory and code them into and out of some other format. 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). See the NSArchiver and NSUnarchiver class specifications for more information on archiving.
fs16
fs28 NSCoder operates on the basic C and Objective C types'd0b intb0 , b floatb0 , b idb0 , and so on (but excluding b void *b0 and b unionb0 )'d0as well as on user-defined structures and pointers to these types.
fs16
fs28 NSCoder declares methods that a subclass can override if it wants:
fs16
fs28 pard s3 li1231 fi-376 ri1007 ql tx1231 tx2872 tx3250 'b7tab To encode or decode an object only under certain conditions, such as it being an intrinsic part of a larger structure (b encodeRootObject:b0 and b encodeConditionalObject:b0 ).
fs16
fs28 'b7tab To allow decoded objects to be allocated from a specific memory zone (b setObjectZone:b0 ).
fs16
fs28 'b7tab To allow system versioning (b systemVersionb0 ).
fs16
fs28 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 NSCoder differs from the NSSerializer and NSDeserializer classes in that NSCoders aren'27t restricted to operating on property list objects (objects of the NSData, NSString, NSArray, and NSDictionary classes). Also, unlike NSSerializers, NSCoders store type information along with the data. Thus, an object decoded from a stream of bytes will be of the same class as the object that was originally encoded into the stream.
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Encoding and Decoding Objects
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 In OpenStep, coding is facilitated by methods declared in several places, most notably the NSCoder class, the NSObject class, and the NSCoding protocol.
fs16
fs28 The NSCoding protocol declares the two methods (b encodeWithCoder:b0 andb initWithCoder:b0 ) that a class must implement so that objects of that class can be encoded and decoded. When an object receives an b encodeWithCoder:b0 message, it should send a message to b superb0 to encode inherited instance variables before it encodes the instance variables that it'27s class declares. For example, a fictitious MapView class that displays a legend and a map at various magnifications, might implement b encodeWithCoder:b0 like this:
fs16
fs28 pard s5 li1231 fi0 ri1007 ql f2 fs20 - (void)encodeWithCoder:(NSCoder *)coder
{
[super encodeWithCoder:coder];
[coder encodeValuesOfObjCTypes:"si@", &mapName, &magnification, &legendView];
}
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 fs28 fs16
fs28 Objects are decoded in two steps. First, an object of the appropriate class is allocated and then it'27s sent an b initWithCoder:b0 messages to allow it to initialize its instance variables. Again, the object should first send a message to b superb0 to initialized inherited instance variables, and then it should initialize its own. MapView'27s implementation of this method looks like this:
fs16
fs28 pard s5 li1231 fi0 ri1007 ql f2 fs20 - (id)initWithCoder:(NSCoder *)coder
{
self = [super initWithCoder:coder];
[coder decodeValuesOfObjCTypes:"si@", &mapName, &magnification, &legendView];
return self;
}
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 fs28 fs16
fs28 Note the assignment of the return value of b initWithCoder:b0 to b selfb0 in the example above. This is done in the subclass because the superclass, in its implementation of b initWithCoder:b0 , may decide to return a object other than itself.
fs16
fs28 There are other methods that allow an object to customize its response to encoding or decoding. NSObject declares these methods:
fs16
fs28 pard s19 li854 fi0 ri1007 ql tx4509 tx10180 f0 b fs24 Methodtab Typical Use
fs6
fs24 pard s18 li4509 fi-3655 ri1007 ql tx4509 tx10432 f1 b0 fs28 fs10
fs28 fi-3655 classForCoder:tab Allows an object, when being encoded, to substitute a class other than its own. For example, the private subclasses of a class cluster substitute the name of their public superclass when being archived.
fs16
fs28 fi-3655 fi-3655 replacementObjectForCoder:tab Allows an object, when being encoded, to substitute another object for itself. For example, an object might encode itself into an archive, but encode a proxy for itself if it'27s being encoded for distribution.
fs16
fs28 fi-3655 fi-3655 awakeAfterUsingCoder:tab Allows an object, when being decoded, to substitute another object for itself. For example, an object that represents a font might, upon being decoded, release itself and return an existing object having the same font description as itself. In this way, redundant objects can be eliminated.
fs16
fs28 fi-3655 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 See the NSObject class specification for more information.
fs16
fs28 pard s16 li100 fi0 ri1007 ql f0 b fs24
fs28 Encoding Data
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (void)b encodeArrayOfObjCType:b0 (const char *)i typesi0 tab
s9 li7030 fi-6553 fi-5796 b count:b0 (unsigned int)i counti0 tab Encodes data of Objective C types listed in i typesi0 having
b at:b0 (const void *)i arrayi0 tab i tab counti0 elements residing at address i arrayi0 .
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b encodeBycopyObject:b0 (id)i anObjecti0 tab Overridden by subclasses to encode the supplied Objective C object so that a copy rather than a proxy of i anObjecti0 is created upon decoding. NSCoder'27s implementation simply invokes b encodeObject:b0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b encodeConditionalObject:b0 (id)i anObjecti0 tab Overridden by subclasses to conditionally encode the supplied Objective C object. The object should be encoded only if it is an intrinsic member of the larger data structure. NSCoder'27s implementation simply invokes b encodeObject:b0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b encodeDataObject:b0 (NSData *)i datai0 tab Encodes the NSData object i datai0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b encodeObject:b0 (id)i anObjecti0 tab Encodes the supplied Objective C object.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b encodePropertyList:b0 (id)i aPropertyListi0 tab Encodes the supplied property list (NSData, NSArray, NSDictionary, or NSString objects).
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b encodePoint:b0 (NSPoint)i pointi0 tab Encodes the supplied point structure.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b encodeRect:b0 (NSRect)i recti0 tab Encodes the supplied rectangle structure.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b encodeRootObject:b0 (id)i rootObjecti0 tab Overridden by subclasses to start encoding an interconnected group of Objective C objects, starting with i rootObjecti0 . NSCoder'27s implementation simply invokes b encodeObject:b0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b encodeSize:b0 (NSSize)i sizei0 tab Encodes the supplied size structure.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b encodeValueOfObjCType:b0 (const char *)i typei0 tab Encodes data of the specified Objective C type
s9 li7030 fi-6553 fi-5796 b at:b0 (const void *)i addri0 esstab tab residing at i addressi0 .
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b encodeValuesOfObjCTypes:b0 (const char *)i types,..i0 .
s9 li7030 fi-6553 fi-5796 tab Encodes values corresponding to the Objective C types listed in i typesi0 argument list.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Decoding Data
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (void)b decodeArrayOfObjCType:b0 (const char *)i types
s9 li7030 fi-6553 fi-5796 i0 b count:b0 (unsigned)i counti0 tab Decodes data of Objective C types listed in i typei0 having
b at:b0 (void *)i addressi0 tab i tab counti0 elements residing at i addressi0 .
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (NSData *)b decodeDataObjectb0 tab Decodes and returns an NSData object.
fi-6552 fs16
fs28 fi-6552 {f3 -} (id)b decodeObjectb0 tab Decodes an Objective C object.
fi-6552 fs16
fs28 fi-6552 {f3 -} (id)b decodePropertyListb0 tab Decodes a property list (NSData, NSArray, NSDictionary, or NSString objects).
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSPoint)b decodePointb0 tab Decodes a point structure.
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSRect)b decodeRectb0 tab Decodes a rectangle structure.
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSSize)b decodeSizeb0 tab Decodes a size structure.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b decodeValueOfObjCType:b0 (const char *)i type
s9 li7030 fi-6553 fi-5796 i0 b at:b0 (void *)i addressi0 tab Decodes data of the specified Objective C i typei0 residing at i addressi0 . You are responsible for releasing the resulting objects.
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b decodeValuesOfObjCTypes:b0 (const char *)i types,...
s9 li7030 fi-6553 fi-5796 i0 tab Decodes values corresponding to the Objective C types listed in i typesi0 argument list. You are responsible for releasing the resulting objects.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Managing Zones
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (NSZone *)b objectZoneb0 tab Returns the memory zone used by decoded objects. For instances of NSCoder, this is the default memory zone, the one returned by b NSDefaultMallocZone()b0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setObjectZone:b0 (NSZone *)i zonei0 tab Sets the memory zone used by decoded objects. Instances of NSCoder always use the default memory zone, the one returned by b NSDefaultMallocZone()b0 , and so ignore this method.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Getting a Version
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (unsigned int)b systemVersiontab b0 Returns the system version number as of the time the archive was created.
fi-6552 fs16
fs28 fi-6552 {f3 -} (unsigned int)b versionForClassName:b0 (NSString *)i classNamei0 tab
s9 li7030 fi-6553 fi-5796 tab Returns the version number of the class i classNamei0 as of the time it was archived.
}These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.