1
/* Interface for NSCoder for GNUStep
2
Copyright (C) 1995, 1996 Free Software Foundation, Inc.
4
Written by: Andrew Kachites McCallum <mccallum@gnu.ai.mit.edu>
7
This file is part of the GNUstep Base Library.
9
This library is free software; you can redistribute it and/or
10
modify it under the terms of the GNU Library General Public
11
License as published by the Free Software Foundation; either
12
version 2 of the License, or (at your option) any later version.
14
This library is distributed in the hope that it will be useful,
15
but WITHOUT ANY WARRANTY; without even the implied warranty of
16
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17
Library General Public License for more details.
19
You should have received a copy of the GNU Library General Public
20
License along with this library; if not, write to the Free
21
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA.
24
#ifndef __NSCoder_h_GNUSTEP_BASE_INCLUDE
25
#define __NSCoder_h_GNUSTEP_BASE_INCLUDE
27
#include <Foundation/NSObject.h>
28
#include <Foundation/NSGeometry.h>
29
#include <Foundation/NSZone.h>
31
@class NSMutableData, NSData, NSString;
34
* <p>Top-level class defining methods for use when archiving (encoding)
35
* objects to a byte array or file, and when restoring (decoding) objects.
36
* Generally only subclasses of this class are used directly - [NSArchiver],
37
* [NSUnarchiver], [NSKeyedArchiver], [NSKeyedUnarchiver], or [NSPortCoder].
39
* <p><code>NSPortCoder</code> is used within the distributed objects
40
* framework. For archiving to/from disk, the <em>Keyed...</em> classes are
41
* preferred for new implementations, since they provide greater
42
* forward/backward compatibility in the face of class changes.</p>
44
@interface NSCoder : NSObject
48
* Encodes array of count structures or objects of given type, which may be
49
* obtained through the '<code>@encode(...)</code>' compile-time operator.
50
* Usually this is used for primitives though it can be used for objects as
53
- (void) encodeArrayOfObjCType: (const char*)type
54
count: (unsigned)count
55
at: (const void*)array;
60
- (void) encodeBycopyObject: (id)anObject;
64
- (void) encodeByrefObject: (id)anObject;
67
* Stores bytes directly into archive.
69
- (void) encodeBytes: (void*)d length: (unsigned)l;
72
* Encode object if it is/will be encoded unconditionally by this coder,
73
* otherwise store a nil.
75
- (void) encodeConditionalObject: (id)anObject;
78
* Encode an instance of [NSData].
80
- (void) encodeDataObject: (NSData*)data;
83
* Encodes a generic object. This will usually result in an
84
* [(NSCoding)-encodeWithCoder:] message being sent to anObject so it
87
- (void) encodeObject: (id)anObject;
90
* Encodes a property list by calling [NSSerializer -serializePropertyList:],
91
* then encoding the resulting [NSData] object.
93
- (void) encodePropertyList: (id)plist;
96
* Encodes a point structure.
98
- (void) encodePoint: (NSPoint)point;
101
* Encodes a rectangle structure.
103
- (void) encodeRect: (NSRect)rect;
106
* Store object and objects it refers to in archive (i.e., complete object
109
- (void) encodeRootObject: (id)rootObject;
112
* Encodes a size structure.
114
- (void) encodeSize: (NSSize)size;
117
* Encodes structure or object of given type, which may be obtained
118
* through the '<code>@encode(...)</code>' compile-time operator. Usually
119
* this is used for primitives though it can be used for objects as well.
121
- (void) encodeValueOfObjCType: (const char*)type
122
at: (const void*)address;
125
* Multiple version of [-encodeValueOfObjCType:at:].
127
- (void) encodeValuesOfObjCTypes: (const char*)types,...;
132
* Decodes array of count structures or objects of given type, which may be
133
* obtained through the '<code>@encode(...)</code>' compile-time operator.
134
* Usually this is used for primitives though it can be used for objects as
135
* well. Objects will be retained and you must release them.
137
- (void) decodeArrayOfObjCType: (const char*)type
138
count: (unsigned)count
142
* Retrieve bytes directly from archive.
144
- (void*) decodeBytesWithReturnedLength: (unsigned*)l;
147
* Decode an instance of [NSData].
149
- (NSData*) decodeDataObject;
152
* Decodes a generic object. Usually the class will be read from the
153
* archive, an object will be created through an <code>alloc</code> call,
154
* then that class will be sent an [(NSCoding)-initWithCoder:] message.
159
* Decodes a property list from the archive previously stored through a call
160
* to [-encodePropertyList:].
162
- (id) decodePropertyList;
165
* Decodes a point structure.
167
- (NSPoint) decodePoint;
170
* Decodes a rectangle structure.
172
- (NSRect) decodeRect;
175
* Decodes a size structure.
177
- (NSSize) decodeSize;
180
* Decodes structure or object of given type, which may be obtained
181
* through the '<code>@encode(...)</code>' compile-time operator. Usually
182
* this is used for primitives though it can be used for objects as well,
183
* in which case you are responsible for releasing them.
185
- (void) decodeValueOfObjCType: (const char*)type
189
* Multiple version of [-decodeValueOfObjCType:at:].
191
- (void) decodeValuesOfObjCTypes: (const char*)types,...;
196
* Returns zone being used to allocate memory for decoded objects.
198
- (NSZone*) objectZone;
201
* Sets zone to use for allocating memory for decoded objects.
203
- (void) setObjectZone: (NSZone*)zone;
208
* Returns *Step version, which is not the release version, but a large number,
209
* by specification <1000 for pre-OpenStep. This implementation returns
210
* a number based on the GNUstep major, minor, and subminor versions.
212
- (unsigned int) systemVersion;
215
* Returns current version of class (when encoding) or version of decoded
216
* class (decoded). Version comes from [NSObject -getVersion].
219
- (unsigned int) versionForClassName: (NSString*)className;
221
#ifndef STRICT_OPENSTEP
223
* Include GSConfig.h for typedefs/defines of uint8_t, int32_t int64_t
225
#include <GSConfig.h>
228
/** <override-subclass />
229
* Returns a flag indicating whether the receiver supported keyed coding.
230
* the default implementation returns NO. Subclasses supporting keyed
231
* coding must override this to return YES.
233
- (BOOL) allowsKeyedCoding;
235
/** <override-subclass />
236
* Returns a class indicating whether an encoded value corresponding
239
- (BOOL) containsValueForKey: (NSString*)aKey;
241
/** <override-subclass />
242
* Returns a boolean value associated with aKey. This value must previously
243
* have been encoded using -encodeBool:forKey:
245
- (BOOL) decodeBoolForKey: (NSString*)aKey;
247
/** <override-subclass />
248
* Returns a pointer to a byte array associated with aKey.<br />
249
* Returns the length of the data in aLength.<br />
250
* This value must previously have been encoded using
251
* -encodeBytes:length:forKey:
253
- (const uint8_t*) decodeBytesForKey: (NSString*)aKey
254
returnedLength: (unsigned*)alength;
256
/** <override-subclass />
257
* Returns a double value associated with aKey. This value must previously
258
* have been encoded using -encodeDouble:forKey: or -encodeFloat:forKey:
260
- (double) decodeDoubleForKey: (NSString*)aKey;
262
/** <override-subclass />
263
* Returns a float value associated with aKey. This value must previously
264
* have been encoded using -encodeFloat:forKey: or -encodeDouble:forKey:<br />
265
* Precision may be lost (or an exception raised if the value will not fit
266
* in a float) if the value was encoded using -encodeDouble:forKey:,
268
- (float) decodeFloatForKey: (NSString*)aKey;
270
/** <override-subclass />
271
* Returns an integer value associated with aKey. This value must previously
272
* have been encoded using -encodeInt:forKey:, -encodeInt32:forKey:, or
273
* -encodeInt64:forKey:.<br />
274
* An exception will be raised if the value does not fit in an integer.
276
- (int) decodeIntForKey: (NSString*)aKey;
278
/** <override-subclass />
279
* Returns a 32-bit integer value associated with aKey. This value must
280
* previously have been encoded using -encodeInt:forKey:,
281
* -encodeInt32:forKey:, or -encodeInt64:forKey:.<br />
282
* An exception will be raised if the value does not fit in a 32-bit integer.
284
- (int32_t) decodeInt32ForKey: (NSString*)aKey;
286
/** <override-subclass />
287
* Returns a 64-bit integer value associated with aKey. This value must
288
* previously have been encoded using -encodeInt:forKey:,
289
* -encodeInt32:forKey:, or -encodeInt64:forKey:.
291
- (int64_t) decodeInt64ForKey: (NSString*)aKey;
293
/** <override-subclass />
294
* Returns an object value associated with aKey. This value must
295
* previously have been encoded using -encodeObject:forKey: or
296
* -encodeConditionalObject:forKey:
298
- (id) decodeObjectForKey: (NSString*)aKey;
300
/** <override-subclass />
301
* Encodes aBool and associates the encoded value with aKey.
303
- (void) encodeBool: (BOOL) aBool forKey: (NSString*)aKey;
305
/** <override-subclass />
306
* Encodes the data of the specified length and pointed to by aPointer,
307
* and associates the encoded value with aKey.
309
- (void) encodeBytes: (const uint8_t*)aPointer
310
length: (unsigned)length
311
forKey: (NSString*)aKey;
313
/** <override-subclass />
314
* Encodes anObject and associates the encoded value with aKey, but only
315
* if anObject has already been encoded using -encodeObject:forKey:
317
- (void) encodeConditionalObject: (id)anObject forKey: (NSString*)aKey;
319
/** <override-subclass />
320
* Encodes aDouble and associates the encoded value with aKey.
322
- (void) encodeDouble: (double)aDouble forKey: (NSString*)aKey;
324
/** <override-subclass />
325
* Encodes aFloat and associates the encoded value with aKey.
327
- (void) encodeFloat: (float)aFloat forKey: (NSString*)aKey;
329
/** <override-subclass />
330
* Encodes anInteger and associates the encoded value with aKey.
332
- (void) encodeInt: (int)anInteger forKey: (NSString*)aKey;
334
/** <override-subclass />
335
* Encodes anInteger and associates the encoded value with aKey.
337
- (void) encodeInt32: (int32_t)anInteger forKey: (NSString*)aKey;
339
/** <override-subclass />
340
* Encodes anInteger and associates the encoded value with aKey.
342
- (void) encodeInt64: (int64_t)anInteger forKey: (NSString*)aKey;
344
/** <override-subclass />
345
* Encodes anObject and associates the encoded value with aKey.
347
- (void) encodeObject: (id)anObject forKey: (NSString*)aKey;
354
* GNUstep extensions to [NSCoder], supporting compatibility with libObjects.
356
@interface NSCoder (GNUstep)
357
/* Compatibility with libObjects */
358
- (void) decodeArrayOfObjCType: (const char*)type
359
count: (unsigned)count
362
- (void) decodeIndent;
363
- (void) decodeObjectAt: (id*)anObject
365
- (void) decodeValueOfCType: (const char*)type
368
- (void) decodeValueOfObjCType: (const char*)type
371
- (void) encodeArrayOfObjCType: (const char*)type
372
count: (unsigned)count
375
- (void) encodeIndent;
376
- (void) encodeObjectAt: (id*)anObject
378
- (void) encodeValueOfCType: (const char*)type
381
- (void) encodeValueOfObjCType: (const char*)type
386
#endif /* NO_GNUSTEP */
388
#endif /* __NSCoder_h_GNUSTEP_BASE_INCLUDE */