1 /* Interface for NSData for GNUStep 2 Copyright (C) 1995 Free Software Foundation, Inc. 3 4 Written by: Andrew Kachites McCallum <mccallum@gnu.ai.mit.edu> 5 Date: 1995 6 7 This file is part of the GNUstep Base Library. 8 9 This library is free software; you can redistribute it and/or 10 modify it under the terms of the GNU Lesser 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. 13 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 Lesser General Public License for more details. 18 19 You should have received a copy of the GNU Lesser General Public 20 License along with this library; if not, write to the Free 21 Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 22 Boston, MA 02110 USA. 23 */ 24 25 #ifndef __NSData_h_GNUSTEP_BASE_INCLUDE 26 #define __NSData_h_GNUSTEP_BASE_INCLUDE 27 #import <GNUstepBase/GSVersionMacros.h> 28 29 #import <Foundation/NSObject.h> 30 #import <Foundation/NSRange.h> 31 #import <Foundation/NSSerialization.h> 32 #import <GNUstepBase/GSBlocks.h> 33 34 #if defined(__cplusplus) 35 extern "C" { 36 #endif 37 38 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST) 39 @class NSError; 40 @class NSURL; 41 #endif 42 43 #if OS_API_VERSION(MAC_OS_X_VERSION_10_9,GS_API_LATEST) 44 enum { 45 NSDataBase64DecodingIgnoreUnknownCharacters = (1UL << 0) 46 }; 47 typedef NSUInteger NSDataBase64DecodingOptions; 48 49 enum { 50 NSDataBase64Encoding64CharacterLineLength = (1UL << 0), 51 NSDataBase64Encoding76CharacterLineLength = (1UL << 1), 52 NSDataBase64EncodingEndLineWithCarriageReturn = (1UL << 4), 53 NSDataBase64EncodingEndLineWithLineFeed = (1UL << 5), 54 }; 55 typedef NSUInteger NSDataBase64EncodingOptions; 56 #endif 57 58 #if OS_API_VERSION(MAC_OS_X_VERSION_10_4,GS_API_LATEST) 59 enum { 60 NSMappedRead = 1, 61 NSUncachedRead = 2 62 }; 63 64 enum { 65 NSDataWritingAtomic = 1 66 }; 67 /* The original name for this was NSAtomicWrite ... need for backward comapat 68 */ 69 #define NSAtomicWrite NSDataWritingAtomic 70 #endif 71 72 #if OS_API_VERSION(MAC_OS_X_VERSION_10_9,GS_API_LATEST) 73 DEFINE_BLOCK_TYPE(GSDataDeallocatorBlock, void, void*, NSUInteger); 74 #endif 75 76 @interface NSData : NSObject <NSCoding, NSCopying, NSMutableCopying> 77 78 // Allocating and Initializing a Data Object 79 80 + (id) data; 81 + (id) dataWithBytes: (const void*)bytes 82 length: (NSUInteger)length; 83 + (id) dataWithBytesNoCopy: (void*)bytes 84 length: (NSUInteger)length; 85 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST) 86 + (id) dataWithBytesNoCopy: (void*)aBuffer 87 length: (NSUInteger)bufferSize 88 freeWhenDone: (BOOL)shouldFree; 89 #endif 90 + (id) dataWithContentsOfFile: (NSString*)path; 91 + (id) dataWithContentsOfMappedFile: (NSString*)path; 92 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST) 93 + (id) dataWithContentsOfURL: (NSURL*)url; 94 #endif 95 + (id) dataWithData: (NSData*)data; 96 #if OS_API_VERSION(MAC_OS_X_VERSION_10_9,GS_API_LATEST) 97 - (id) initWithBase64EncodedData: (NSData*)base64Data 98 options: (NSDataBase64DecodingOptions)options; 99 - (id) initWithBase64EncodedString: (NSString*)base64String 100 options: (NSDataBase64DecodingOptions)options; 101 /** 102 * <override-subclass/> 103 * Initialize the receiver to hold memory pointed to by bytes without copying. 104 * When the receiver is deallocated, the memory will be freed using the user 105 * supplied deallocBlock. Note that passing a block that (either directly or 106 * indirectly) holds a strong reference the receiver will cause a retain cycle. 107 */ 108 - (instancetype) initWithBytesNoCopy: (void*)bytes 109 length: (NSUInteger)length 110 deallocator: (GSDataDeallocatorBlock)deallocBlock; 111 #endif 112 - (id) initWithBytes: (const void*)aBuffer 113 length: (NSUInteger)bufferSize; 114 - (id) initWithBytesNoCopy: (void*)aBuffer 115 length: (NSUInteger)bufferSize; 116 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST) 117 - (id) initWithBytesNoCopy: (void*)aBuffer 118 length: (NSUInteger)bufferSize 119 freeWhenDone: (BOOL)shouldFree; 120 #endif 121 - (id) initWithContentsOfFile: (NSString*)path; 122 - (id) initWithContentsOfMappedFile: (NSString*)path; 123 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST) 124 - (id) initWithContentsOfURL: (NSURL*)url; 125 #endif 126 - (id) initWithData: (NSData*)data; 127 128 // Accessing Data 129 130 - (const void*) bytes; 131 - (NSString*) description; 132 - (void) getBytes: (void*)buffer; 133 - (void) getBytes: (void*)buffer 134 length: (NSUInteger)length; 135 - (void) getBytes: (void*)buffer 136 range: (NSRange)aRange; 137 - (NSData*) subdataWithRange: (NSRange)aRange; 138 139 // base64 140 #if OS_API_VERSION(MAC_OS_X_VERSION_10_9,GS_API_LATEST) 141 - (NSData *) base64EncodedDataWithOptions: (NSDataBase64EncodingOptions)options; 142 - (NSString *) base64EncodedStringWithOptions: (NSDataBase64EncodingOptions)options; 143 #endif 144 145 // Querying a Data Object 146 147 - (BOOL) isEqualToData: (NSData*)other; 148 - (NSUInteger) length; 149 150 /** 151 * <p>Writes a copy of the data encapsulated by the receiver to a file 152 * at path. If the useAuxiliaryFile flag is YES, this writes to a 153 * temporary file and then renames that to the file at path, thus 154 * ensuring that path exists and does not contain partially written 155 * data at any point. 156 * </p> 157 * <p>On success returns YES, on failure returns NO. 158 * </p> 159 */ 160 - (BOOL) writeToFile: (NSString*)path 161 atomically: (BOOL)useAuxiliaryFile; 162 163 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST) 164 /** 165 * Writes a copy of the contents of the receiver to the specified URL. 166 */ 167 - (BOOL) writeToURL: (NSURL*)anURL atomically: (BOOL)flag; 168 #endif 169 170 // Deserializing Data 171 172 - (unsigned int) deserializeAlignedBytesLengthAtCursor: (unsigned int*)cursor; 173 - (void) deserializeBytes: (void*)buffer 174 length: (unsigned int)bytes 175 atCursor: (unsigned int*)cursor; 176 - (void) deserializeDataAt: (void*)data 177 ofObjCType: (const char*)type 178 atCursor: (unsigned int*)cursor 179 context: (id <NSObjCTypeSerializationCallBack>)callback; 180 - (int) deserializeIntAtCursor: (unsigned int*)cursor; 181 - (int) deserializeIntAtIndex: (unsigned int)index; 182 - (void) deserializeInts: (int*)intBuffer 183 count: (unsigned int)numInts 184 atCursor: (unsigned int*)cursor; 185 - (void) deserializeInts: (int*)intBuffer 186 count: (unsigned int)numInts 187 atIndex: (unsigned int)index; 188 189 #if OS_API_VERSION(MAC_OS_X_VERSION_10_4,GS_API_LATEST) 190 /** 191 * <p>Writes a copy of the data encapsulated by the receiver to a file 192 * at path. If the NSDataWritingAtomic option is set, this writes to a 193 * temporary file and then renames that to the file at path, thus 194 * ensuring that path exists and does not contain partially written 195 * data at any point. 196 * </p> 197 * <p>On success returns YES, on failure returns NO. 198 * </p> 199 */ 200 - (BOOL) writeToFile: (NSString *)path 201 options: (NSUInteger)writeOptionsMask 202 error: (NSError **)errorPtr; 203 204 /** 205 * Writes a copy of the contents of the receiver to the specified URL. 206 */ 207 - (BOOL) writeToURL: (NSURL *)url 208 options: (NSUInteger)writeOptionsMask 209 error: (NSError **)errorPtr; 210 #endif 211 @end 212 213 #if OS_API_VERSION(GS_API_NONE, GS_API_NONE) 214 215 /* 216 * We include special support for coding/decoding - adding methods for 217 * serializing/deserializing type-tags and cross-references. 218 * 219 * A type-tag is a byte containing - 220 * Bit7 Set to indicate that the tag is for a cross-reference. 221 * Bit5-6 A value for the size of the type or cross-reference. 222 * Bit0-4 A value representing an Objective-C type. 223 */ 224 225 #define _GSC_NONE 0x00 /* No type information. */ 226 #define _GSC_XREF 0x80 /* Cross reference to an item. */ 227 #define _GSC_SIZE 0x60 /* Type-size info mask. */ 228 #define _GSC_MASK 0x1f /* Basic type info mask. */ 229 230 /* 231 * If the tag is for a cross-reference, the size field defines the 232 * size of the cross-reference value - 233 * _GSC_X_0 (no crossref), _GSC_X_1, _GSC_X_2, _GSC_X_4 234 */ 235 #define _GSC_X_0 0x00 /* nil or null pointer */ 236 #define _GSC_X_1 0x20 /* 8-bit cross-ref */ 237 #define _GSC_X_2 0x40 /* 16-bit cross-ref */ 238 #define _GSC_X_4 0x60 /* 32-bit cross-ref */ 239 240 /* 241 * If the tag is for an integer value, the size field defines the 242 * size of the the encoded integer - 243 * _GSC_I16, _GSC_I32, _GSC_I64, _GSC_I128 244 * The file GSConfig.h (produced by the configure script) defines the 245 * size codes for this machines 'natural' integers - 246 * _GSC_S_SHT, _GSC_S_INT, _GSC_S_LNG, _GSC_S_LNG_LNG 247 */ 248 #define _GSC_I16 0x00 249 #define _GSC_I32 0x20 250 #define _GSC_I64 0x40 251 #define _GSC_I128 0x60 252 253 /* 254 * For the first sixteen types, the size information applies to the 255 * size of the type, for the second sixteen it applies to the 256 * following cross-reference number (or is zero if no crossref follows). 257 */ 258 #define _GSC_MAYX 0x10 /* Item may have crossref. */ 259 260 /* 261 * These are the types that can be archived - 262 */ 263 #define _GSC_CHR 0x01 264 #define _GSC_UCHR 0x02 265 #define _GSC_SHT 0x03 266 #define _GSC_USHT 0x04 267 #define _GSC_INT 0x05 268 #define _GSC_UINT 0x06 269 #define _GSC_LNG 0x07 270 #define _GSC_ULNG 0x08 271 #define _GSC_LNG_LNG 0x09 272 #define _GSC_ULNG_LNG 0x0a 273 #define _GSC_FLT 0x0b 274 #define _GSC_DBL 0x0c 275 #define _GSC_BOOL 0x0d 276 277 #define _GSC_ID 0x10 278 #define _GSC_CLASS 0x11 279 #define _GSC_SEL 0x12 280 #define _GSC_PTR 0x13 281 #define _GSC_CHARPTR 0x14 282 #define _GSC_ARY_B 0x15 283 #define _GSC_STRUCT_B 0x16 284 #define _GSC_CID 0x17 /* Class encoded as id */ 285 286 @interface NSData (GNUstepExtensions) 287 + (id) dataWithShmID: (int)anID length: (NSUInteger) length; 288 + (id) dataWithSharedBytes: (const void*)bytes length: (NSUInteger) length; 289 290 /* 291 * -deserializeTypeTag:andCrossRef:atCursor: 292 * This method is provided in order to give the GNUstep version of 293 * NSUnarchiver maximum possible performance. 294 */ 295 - (void) deserializeTypeTag: (unsigned char*)tag 296 andCrossRef: (unsigned int*)ref 297 atCursor: (unsigned int*)cursor; 298 @end 299 #endif 300 301 @interface NSMutableData : NSData 302 303 + (id) dataWithCapacity: (NSUInteger)numBytes; 304 + (id) dataWithLength: (NSUInteger)length; 305 - (id) initWithCapacity: (NSUInteger)capacity; 306 - (id) initWithLength: (NSUInteger)length; 307 308 // Adjusting Capacity 309 310 - (void) increaseLengthBy: (NSUInteger)extraLength; 311 - (void) setLength: (NSUInteger)size; 312 - (void*) mutableBytes; 313 314 // Appending Data 315 316 - (void) appendBytes: (const void*)aBuffer 317 length: (NSUInteger)bufferSize; 318 - (void) appendData: (NSData*)other; 319 320 // Modifying Data 321 322 - (void) replaceBytesInRange: (NSRange)aRange 323 withBytes: (const void*)bytes; 324 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST) 325 - (void) replaceBytesInRange: (NSRange)aRange 326 withBytes: (const void*)bytes 327 length: (NSUInteger)length; 328 #endif 329 - (void) resetBytesInRange: (NSRange)aRange; 330 - (void) setData: (NSData*)data; 331 332 // Serializing Data 333 334 - (void) serializeAlignedBytesLength: (unsigned int)length; 335 - (void) serializeDataAt: (const void*)data 336 ofObjCType: (const char*)type 337 context: (id <NSObjCTypeSerializationCallBack>)callback; 338 - (void) serializeInt: (int)value; 339 - (void) serializeInt: (int)value 340 atIndex: (unsigned int)index; 341 - (void) serializeInts: (int*)intBuffer 342 count: (unsigned int)numInts; 343 - (void) serializeInts: (int*)intBuffer 344 count: (unsigned int)numInts 345 atIndex: (unsigned int)index; 346 347 @end 348 349 #if OS_API_VERSION(GS_API_NONE, GS_API_NONE) 350 351 @interface NSMutableData (GNUstepExtensions) 352 /* 353 * Capacity management - GNUstep gives you control over the size of 354 * the data buffer as well as the 'length' of valid data in it. 355 */ 356 - (NSUInteger) capacity; 357 - (id) setCapacity: (NSUInteger)newCapacity; 358 359 - (int) shmID; /* Shared memory ID for data buffer (if any) */ 360 361 /* 362 * -serializeTypeTag: 363 * -serializeTypeTag:andCrossRef: 364 * These methods are provided in order to give the GNUstep version of 365 * NSArchiver maximum possible performance. 366 */ 367 - (void) serializeTypeTag: (unsigned char)tag; 368 - (void) serializeTypeTag: (unsigned char)tag 369 andCrossRef: (unsigned int)xref; 370 371 @end 372 #endif 373 374 #if defined(__cplusplus) 375 } 376 #endif 377 378 #if !NO_GNUSTEP && !defined(GNUSTEP_BASE_INTERNAL) 379 #import <GNUstepBase/NSData+GNUstepBase.h> 380 #endif 381 382 #endif /* __NSData_h_GNUSTEP_BASE_INCLUDE */ 383