Adopted by: No Cocoa classes
Declared in:
- Foundation/NSSerialization.h
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 Cocoa'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 serialize 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 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];
Because 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]; }
- (void)deserializeObjectAt:(id
*)object
ofObjCType:(const char *)type
fromData:(NSData *)data
atCursor:(unsigned *)cursor
See Also: - deserializeDataAt:ofObjCType:atCursor:context: (NSData)
- (void)serializeObjectAt:(id
*)object
ofObjCType:(const char *)type
intoData:(NSMutableData *)data
See Also: - serializeDataAt:ofObjCType:context: (NSMutableData)