1
/* Interface for NSData for GNUStep
2
Copyright (C) 1995 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 __NSData_h_GNUSTEP_BASE_INCLUDE
25
#define __NSData_h_GNUSTEP_BASE_INCLUDE
27
#include <Foundation/NSObject.h>
28
#include <Foundation/NSRange.h>
29
#include <Foundation/NSSerialization.h>
31
#ifndef STRICT_OPENSTEP
35
@interface NSData : NSObject <NSCoding, NSCopying, NSMutableCopying>
37
// Allocating and Initializing a Data Object
40
+ (id) dataWithBytes: (const void*)bytes
41
length: (unsigned int)length;
42
+ (id) dataWithBytesNoCopy: (void*)bytes
43
length: (unsigned int)length;
44
#ifndef STRICT_OPENSTEP
45
+ (id) dataWithBytesNoCopy: (void*)aBuffer
46
length: (unsigned int)bufferSize
47
freeWhenDone: (BOOL)shouldFree;
49
+ (id) dataWithContentsOfFile: (NSString*)path;
50
+ (id) dataWithContentsOfMappedFile: (NSString*)path;
51
#ifndef STRICT_OPENSTEP
52
+ (id) dataWithContentsOfURL: (NSURL*)url;
54
+ (id) dataWithData: (NSData*)data;
55
- (id) initWithBytes: (const void*)aBuffer
56
length: (unsigned int)bufferSize;
57
- (id) initWithBytesNoCopy: (void*)aBuffer
58
length: (unsigned int)bufferSize;
59
#ifndef STRICT_OPENSTEP
60
- (id) initWithBytesNoCopy: (void*)aBuffer
61
length: (unsigned int)bufferSize
62
freeWhenDone: (BOOL)shouldFree;
64
- (id) initWithContentsOfFile: (NSString*)path;
65
- (id) initWithContentsOfMappedFile: (NSString*)path;
66
#ifndef STRICT_OPENSTEP
67
- (id) initWithContentsOfURL: (NSURL*)url;
69
- (id) initWithData: (NSData*)data;
73
- (const void*) bytes;
74
- (NSString*) description;
75
- (void) getBytes: (void*)buffer;
76
- (void) getBytes: (void*)buffer
77
length: (unsigned int)length;
78
- (void) getBytes: (void*)buffer
79
range: (NSRange)aRange;
80
- (NSData*) subdataWithRange: (NSRange)aRange;
82
// Querying a Data Object
84
- (BOOL) isEqualToData: (NSData*)other;
85
- (unsigned int) length;
89
- (BOOL) writeToFile: (NSString*)path
90
atomically: (BOOL)useAuxiliaryFile;
92
#ifndef STRICT_OPENSTEP
93
- (BOOL) writeToURL: (NSURL*)anURL atomically: (BOOL)flag;
98
- (unsigned int) deserializeAlignedBytesLengthAtCursor: (unsigned int*)cursor;
99
- (void) deserializeBytes: (void*)buffer
100
length: (unsigned int)bytes
101
atCursor: (unsigned int*)cursor;
102
- (void) deserializeDataAt: (void*)data
103
ofObjCType: (const char*)type
104
atCursor: (unsigned int*)cursor
105
context: (id <NSObjCTypeSerializationCallBack>)callback;
106
- (int) deserializeIntAtCursor: (unsigned int*)cursor;
107
- (int) deserializeIntAtIndex: (unsigned int)index;
108
- (void) deserializeInts: (int*)intBuffer
109
count: (unsigned int)numInts
110
atCursor: (unsigned int*)cursor;
111
- (void) deserializeInts: (int*)intBuffer
112
count: (unsigned int)numInts
113
atIndex: (unsigned int)index;
120
* Extension methods for the NSData class- mainly conversion utilities.
122
@interface NSData (GSCategories)
125
* Returns an NSString object containing an ASCII hexadecimal representation
126
* of the receiver. This means that the returned object will contain
127
* exactly twice as many characters as there are bytes as the receiver,
128
* as each byte in the receiver is represented by two hexadecimal digits.<br />
129
* The high order four bits of each byte is encoded before the low
130
* order four bits. Capital letters 'A' to 'F' are used to represent
131
* values from 10 to 15.<br />
132
* If you need the hexadecimal representation as raw byte data, use code
135
* hexData = [[sourceData hexadecimalRepresentation]
136
* dataUsingEncoding: NSASCIIStringEncoding];
139
- (NSString*) hexadecimalRepresentation;
142
* Initialises the receiver with the supplied string data which contains
143
* a hexadecimal coding of the bytes. The parsing of the string is
144
* fairly tolerant, ignoring whitespace and permitting both upper and
145
* lower case hexadecimal digits (the -hexadecimalRepresentation method
146
* produces a string using only uppercase digits with no white spaqce).<br />
147
* If the string does not contain one or more pairs of hexadecimal digits
148
* then an exception is raised.
150
- (id) initWithHexadecimalRepresentation: (NSString*)string;
153
* Creates an MD5 digest of the information stored in the receiver and
154
* returns it as an autoreleased 16 byte NSData object.<br />
155
* If you need to produce a digest of string information, you need to
156
* decide what character encoding is to be used and convert your string
157
* to a data object of that encoding type first using the
158
* [NSString-dataUsingEncoding:] method -
160
* myDigest = [[myString dataUsingEncoding: NSUTF8StringEncoding] md5Digest];
162
* If you need to use the digest in a human readable form, you will
163
* probably want it to be seen as 32 hexadecimal digits, and can do that
164
* using the -hexadecimalRepresentation method.
166
- (NSData*) md5Digest;
169
* Decodes the source data from uuencoded and return the result.<br />
170
* Returns the encoded file name in namePtr if it is not null.
171
* Returns the encoded file mode in modePtr if it is not null.
173
- (BOOL) uudecodeInto: (NSMutableData*)decoded
174
name: (NSString**)namePtr
178
* Encode the source data to uuencoded.<br />
179
* Uses the supplied name as the filename in the encoded data,
180
* and says that the file mode is as specified.<br />
181
* If no name is supplied, uses <code>untitled</code> as the name.
183
- (BOOL) uuencodeInto: (NSMutableData*)encoded
184
name: (NSString*)name
189
* We include special support for coding/decoding - adding methods for
190
* serializing/deserializing type-tags and cross-references.
192
* A type-tag is a byte containing -
193
* Bit7 Set to indicate that the tag is for a cross-reference.
194
* Bit5-6 A value for the size of the type or cross-reference.
195
* Bit0-4 A value representing an Objective-C type.
198
#define _GSC_NONE 0x00 /* No type information. */
199
#define _GSC_XREF 0x80 /* Cross reference to an item. */
200
#define _GSC_SIZE 0x60 /* Type-size info mask. */
201
#define _GSC_MASK 0x1f /* Basic type info mask. */
204
* If the tag is for a cross-reference, the size field defines the
205
* size of the cross-reference value -
206
* _GSC_X_0 (no crossref), _GSC_X_1, _GSC_X_2, _GSC_X_4
208
#define _GSC_X_0 0x00 /* nil or null pointer */
209
#define _GSC_X_1 0x20 /* 8-bit cross-ref */
210
#define _GSC_X_2 0x40 /* 16-bit cross-ref */
211
#define _GSC_X_4 0x60 /* 32-bit cross-ref */
214
* If the tag is for an integer value, the size field defines the
215
* size of the the encoded integer -
216
* _GSC_I16, _GSC_I32, _GSC_I64, _GSC_I128
217
* The file GSConfig.h (produced by the configure script) defines the
218
* size codes for this machines 'natural' integers -
219
* _GSC_S_SHT, _GSC_S_INT, _GSC_S_LNG, _GSC_S_LNG_LNG
221
#define _GSC_I16 0x00
222
#define _GSC_I32 0x20
223
#define _GSC_I64 0x40
224
#define _GSC_I128 0x60
227
* For the first sixteen types, the size information applies to the
228
* size of the type, for the second sixteen it applies to the
229
* following cross-reference number (or is zero if no crossref follows).
231
#define _GSC_MAYX 0x10 /* Item may have crossref. */
234
* These are the types that can be archived -
236
#define _GSC_CHR 0x01
237
#define _GSC_UCHR 0x02
238
#define _GSC_SHT 0x03
239
#define _GSC_USHT 0x04
240
#define _GSC_INT 0x05
241
#define _GSC_UINT 0x06
242
#define _GSC_LNG 0x07
243
#define _GSC_ULNG 0x08
244
#define _GSC_LNG_LNG 0x09
245
#define _GSC_ULNG_LNG 0x0a
246
#define _GSC_FLT 0x0b
247
#define _GSC_DBL 0x0c
250
#define _GSC_CLASS 0x11
251
#define _GSC_SEL 0x12
252
#define _GSC_PTR 0x13
253
#define _GSC_CHARPTR 0x14
254
#define _GSC_ARY_B 0x15
255
#define _GSC_STRUCT_B 0x16
256
#define _GSC_CID 0x17 /* Class encoded as id */
258
@interface NSData (GNUstepExtensions)
259
+ (id) dataWithShmID: (int)anID length: (unsigned int) length;
260
+ (id) dataWithSharedBytes: (const void*)bytes length: (unsigned int) length;
263
* -deserializeTypeTag:andCrossRef:atCursor:
264
* This method is provided in order to give the GNUstep version of
265
* NSUnarchiver maximum possible performance.
267
- (void) deserializeTypeTag: (unsigned char*)tag
268
andCrossRef: (unsigned int*)ref
269
atCursor: (unsigned int*)cursor;
273
@interface NSMutableData : NSData
275
+ (id) dataWithCapacity: (unsigned int)numBytes;
276
+ (id) dataWithLength: (unsigned int)length;
277
- (id) initWithCapacity: (unsigned int)capacity;
278
- (id) initWithLength: (unsigned int)length;
280
// Adjusting Capacity
282
- (void) increaseLengthBy: (unsigned int)extraLength;
283
- (void) setLength: (unsigned int)size;
284
- (void*) mutableBytes;
288
- (void) appendBytes: (const void*)aBuffer
289
length: (unsigned int)bufferSize;
290
- (void) appendData: (NSData*)other;
294
- (void) replaceBytesInRange: (NSRange)aRange
295
withBytes: (const void*)bytes;
296
#ifndef STRICT_OPENSTEP
297
- (void) replaceBytesInRange: (NSRange)aRange
298
withBytes: (const void*)bytes
299
length: (unsigned int)length;
301
- (void) resetBytesInRange: (NSRange)aRange;
302
- (void) setData: (NSData*)data;
306
- (void) serializeAlignedBytesLength: (unsigned int)length;
307
- (void) serializeDataAt: (const void*)data
308
ofObjCType: (const char*)type
309
context: (id <NSObjCTypeSerializationCallBack>)callback;
310
- (void) serializeInt: (int)value;
311
- (void) serializeInt: (int)value
312
atIndex: (unsigned int)index;
313
- (void) serializeInts: (int*)intBuffer
314
count: (unsigned int)numInts;
315
- (void) serializeInts: (int*)intBuffer
316
count: (unsigned int)numInts
317
atIndex: (unsigned int)index;
323
@interface NSMutableData (GNUstepExtensions)
325
* Capacity management - GNUstep gives you control over the size of
326
* the data buffer as well as the 'length' of valid data in it.
328
- (unsigned int) capacity;
329
- (id) setCapacity: (unsigned int)newCapacity;
331
- (int) shmID; /* Shared memory ID for data buffer (if any) */
335
* -serializeTypeTag:andCrossRef:
336
* These methods are provided in order to give the GNUstep version of
337
* NSArchiver maximum possible performance.
339
- (void) serializeTypeTag: (unsigned char)tag;
340
- (void) serializeTypeTag: (unsigned char)tag
341
andCrossRef: (unsigned int)xref;
352
#endif /* __NSData_h_GNUSTEP_BASE_INCLUDE */
added
removed
Headers/Foundation/NSData.h
