1 // Protocol Buffers - Google's data interchange format 2 // Copyright 2008 Google Inc. All rights reserved. 3 // https://developers.google.com/protocol-buffers/ 4 // 5 // Redistribution and use in source and binary forms, with or without 6 // modification, are permitted provided that the following conditions are 7 // met: 8 // 9 // * Redistributions of source code must retain the above copyright 10 // notice, this list of conditions and the following disclaimer. 11 // * Redistributions in binary form must reproduce the above 12 // copyright notice, this list of conditions and the following disclaimer 13 // in the documentation and/or other materials provided with the 14 // distribution. 15 // * Neither the name of Google Inc. nor the names of its 16 // contributors may be used to endorse or promote products derived from 17 // this software without specific prior written permission. 18 // 19 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 24 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 25 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 31 #import <Foundation/Foundation.h> 32 33 #import "GPBRuntimeTypes.h" 34 #import "GPBWireFormat.h" 35 36 @class GPBBoolArray; 37 @class GPBDoubleArray; 38 @class GPBEnumArray; 39 @class GPBFloatArray; 40 @class GPBMessage; 41 @class GPBInt32Array; 42 @class GPBInt64Array; 43 @class GPBUInt32Array; 44 @class GPBUInt64Array; 45 @class GPBUnknownFieldSet; 46 47 NS_ASSUME_NONNULL_BEGIN 48 49 /// Writes out protocol message fields. 50 /// 51 /// The common uses of protocol buffers shouldn't need to use this class. 52 /// @c GPBMessage's provide a @c -data method that will serialize the message 53 /// for you. 54 /// 55 /// @note Subclassing of GPBCodedOutputStream is NOT supported. 56 @interface GPBCodedOutputStream : NSObject 57 58 /// Creates a stream to fill in the given data. Data must be sized to fit or 59 /// an error will be raised when out of space. 60 + (instancetype)streamWithData:(NSMutableData *)data; 61 62 /// Creates a stream to write into the given @c NSOutputStream. 63 + (instancetype)streamWithOutputStream:(NSOutputStream *)output; 64 65 /// Initializes a stream to fill in the given data. Data must be sized to fit 66 /// or an error will be raised when out of space. 67 - (instancetype)initWithData:(NSMutableData *)data; 68 69 /// Initializes a stream to write into the given @c NSOutputStream. 70 - (instancetype)initWithOutputStream:(NSOutputStream *)output; 71 72 /// Flush any buffered data out. 73 - (void)flush; 74 75 /// Write the raw byte out. 76 - (void)writeRawByte:(uint8_t)value; 77 78 /// Write the tag for the given field number and wire format. 79 /// 80 /// @param fieldNumber The field number. 81 /// @param format The wire format the data for the field will be in. 82 - (void)writeTag:(uint32_t)fieldNumber format:(GPBWireFormat)format; 83 84 /// Write a 32bit value out in little endian format. 85 - (void)writeRawLittleEndian32:(int32_t)value; 86 /// Write a 64bit value out in little endian format. 87 - (void)writeRawLittleEndian64:(int64_t)value; 88 89 /// Write a 32bit value out in varint format. 90 - (void)writeRawVarint32:(int32_t)value; 91 /// Write a 64bit value out in varint format. 92 - (void)writeRawVarint64:(int64_t)value; 93 94 /// Write a size_t out as a 32bit varint value. 95 /// 96 /// @note This will truncate 64 bit values to 32. 97 - (void)writeRawVarintSizeTAs32:(size_t)value; 98 99 /// Writes the contents of an @c NSData out. 100 - (void)writeRawData:(NSData *)data; 101 /// Writes out the given data. 102 /// 103 /// @param data The data blob to write out. 104 /// @param offset The offset into the blob to start writing out. 105 /// @param length The number of bytes from the blob to write out. 106 - (void)writeRawPtr:(const void *)data 107 offset:(size_t)offset 108 length:(size_t)length; 109 110 //%PDDM-EXPAND _WRITE_DECLS() 111 // This block of code is generated, do not edit it directly. 112 113 /// Write a double for the given field number. 114 - (void)writeDouble:(int32_t)fieldNumber value:(double)value; 115 /// Write a packed array of double for the given field number. 116 - (void)writeDoubleArray:(int32_t)fieldNumber 117 values:(GPBDoubleArray *)values 118 tag:(uint32_t)tag; 119 /// Write a double without any tag. 120 - (void)writeDoubleNoTag:(double)value; 121 122 /// Write a float for the given field number. 123 - (void)writeFloat:(int32_t)fieldNumber value:(float)value; 124 /// Write a packed array of float for the given field number. 125 - (void)writeFloatArray:(int32_t)fieldNumber 126 values:(GPBFloatArray *)values 127 tag:(uint32_t)tag; 128 /// Write a float without any tag. 129 - (void)writeFloatNoTag:(float)value; 130 131 /// Write a uint64_t for the given field number. 132 - (void)writeUInt64:(int32_t)fieldNumber value:(uint64_t)value; 133 /// Write a packed array of uint64_t for the given field number. 134 - (void)writeUInt64Array:(int32_t)fieldNumber 135 values:(GPBUInt64Array *)values 136 tag:(uint32_t)tag; 137 /// Write a uint64_t without any tag. 138 - (void)writeUInt64NoTag:(uint64_t)value; 139 140 /// Write a int64_t for the given field number. 141 - (void)writeInt64:(int32_t)fieldNumber value:(int64_t)value; 142 /// Write a packed array of int64_t for the given field number. 143 - (void)writeInt64Array:(int32_t)fieldNumber 144 values:(GPBInt64Array *)values 145 tag:(uint32_t)tag; 146 /// Write a int64_t without any tag. 147 - (void)writeInt64NoTag:(int64_t)value; 148 149 /// Write a int32_t for the given field number. 150 - (void)writeInt32:(int32_t)fieldNumber value:(int32_t)value; 151 /// Write a packed array of int32_t for the given field number. 152 - (void)writeInt32Array:(int32_t)fieldNumber 153 values:(GPBInt32Array *)values 154 tag:(uint32_t)tag; 155 /// Write a int32_t without any tag. 156 - (void)writeInt32NoTag:(int32_t)value; 157 158 /// Write a uint32_t for the given field number. 159 - (void)writeUInt32:(int32_t)fieldNumber value:(uint32_t)value; 160 /// Write a packed array of uint32_t for the given field number. 161 - (void)writeUInt32Array:(int32_t)fieldNumber 162 values:(GPBUInt32Array *)values 163 tag:(uint32_t)tag; 164 /// Write a uint32_t without any tag. 165 - (void)writeUInt32NoTag:(uint32_t)value; 166 167 /// Write a uint64_t for the given field number. 168 - (void)writeFixed64:(int32_t)fieldNumber value:(uint64_t)value; 169 /// Write a packed array of uint64_t for the given field number. 170 - (void)writeFixed64Array:(int32_t)fieldNumber 171 values:(GPBUInt64Array *)values 172 tag:(uint32_t)tag; 173 /// Write a uint64_t without any tag. 174 - (void)writeFixed64NoTag:(uint64_t)value; 175 176 /// Write a uint32_t for the given field number. 177 - (void)writeFixed32:(int32_t)fieldNumber value:(uint32_t)value; 178 /// Write a packed array of uint32_t for the given field number. 179 - (void)writeFixed32Array:(int32_t)fieldNumber 180 values:(GPBUInt32Array *)values 181 tag:(uint32_t)tag; 182 /// Write a uint32_t without any tag. 183 - (void)writeFixed32NoTag:(uint32_t)value; 184 185 /// Write a int32_t for the given field number. 186 - (void)writeSInt32:(int32_t)fieldNumber value:(int32_t)value; 187 /// Write a packed array of int32_t for the given field number. 188 - (void)writeSInt32Array:(int32_t)fieldNumber 189 values:(GPBInt32Array *)values 190 tag:(uint32_t)tag; 191 /// Write a int32_t without any tag. 192 - (void)writeSInt32NoTag:(int32_t)value; 193 194 /// Write a int64_t for the given field number. 195 - (void)writeSInt64:(int32_t)fieldNumber value:(int64_t)value; 196 /// Write a packed array of int64_t for the given field number. 197 - (void)writeSInt64Array:(int32_t)fieldNumber 198 values:(GPBInt64Array *)values 199 tag:(uint32_t)tag; 200 /// Write a int64_t without any tag. 201 - (void)writeSInt64NoTag:(int64_t)value; 202 203 /// Write a int64_t for the given field number. 204 - (void)writeSFixed64:(int32_t)fieldNumber value:(int64_t)value; 205 /// Write a packed array of int64_t for the given field number. 206 - (void)writeSFixed64Array:(int32_t)fieldNumber 207 values:(GPBInt64Array *)values 208 tag:(uint32_t)tag; 209 /// Write a int64_t without any tag. 210 - (void)writeSFixed64NoTag:(int64_t)value; 211 212 /// Write a int32_t for the given field number. 213 - (void)writeSFixed32:(int32_t)fieldNumber value:(int32_t)value; 214 /// Write a packed array of int32_t for the given field number. 215 - (void)writeSFixed32Array:(int32_t)fieldNumber 216 values:(GPBInt32Array *)values 217 tag:(uint32_t)tag; 218 /// Write a int32_t without any tag. 219 - (void)writeSFixed32NoTag:(int32_t)value; 220 221 /// Write a BOOL for the given field number. 222 - (void)writeBool:(int32_t)fieldNumber value:(BOOL)value; 223 /// Write a packed array of BOOL for the given field number. 224 - (void)writeBoolArray:(int32_t)fieldNumber 225 values:(GPBBoolArray *)values 226 tag:(uint32_t)tag; 227 /// Write a BOOL without any tag. 228 - (void)writeBoolNoTag:(BOOL)value; 229 230 /// Write a int32_t for the given field number. 231 - (void)writeEnum:(int32_t)fieldNumber value:(int32_t)value; 232 /// Write a packed array of int32_t for the given field number. 233 - (void)writeEnumArray:(int32_t)fieldNumber 234 values:(GPBEnumArray *)values 235 tag:(uint32_t)tag; 236 /// Write a int32_t without any tag. 237 - (void)writeEnumNoTag:(int32_t)value; 238 239 /// Write a NSString for the given field number. 240 - (void)writeString:(int32_t)fieldNumber value:(NSString *)value; 241 /// Write an array of NSString for the given field number. 242 - (void)writeStringArray:(int32_t)fieldNumber values:(NSArray<NSString*> *)values; 243 /// Write a NSString without any tag. 244 - (void)writeStringNoTag:(NSString *)value; 245 246 /// Write a GPBMessage for the given field number. 247 - (void)writeMessage:(int32_t)fieldNumber value:(GPBMessage *)value; 248 /// Write an array of GPBMessage for the given field number. 249 - (void)writeMessageArray:(int32_t)fieldNumber values:(NSArray<GPBMessage*> *)values; 250 /// Write a GPBMessage without any tag. 251 - (void)writeMessageNoTag:(GPBMessage *)value; 252 253 /// Write a NSData for the given field number. 254 - (void)writeBytes:(int32_t)fieldNumber value:(NSData *)value; 255 /// Write an array of NSData for the given field number. 256 - (void)writeBytesArray:(int32_t)fieldNumber values:(NSArray<NSData*> *)values; 257 /// Write a NSData without any tag. 258 - (void)writeBytesNoTag:(NSData *)value; 259 260 /// Write a GPBMessage for the given field number. 261 - (void)writeGroup:(int32_t)fieldNumber 262 value:(GPBMessage *)value; 263 /// Write an array of GPBMessage for the given field number. 264 - (void)writeGroupArray:(int32_t)fieldNumber values:(NSArray<GPBMessage*> *)values; 265 /// Write a GPBMessage without any tag (but does write the endGroup tag). 266 - (void)writeGroupNoTag:(int32_t)fieldNumber 267 value:(GPBMessage *)value; 268 269 /// Write a GPBUnknownFieldSet for the given field number. 270 - (void)writeUnknownGroup:(int32_t)fieldNumber 271 value:(GPBUnknownFieldSet *)value; 272 /// Write an array of GPBUnknownFieldSet for the given field number. 273 - (void)writeUnknownGroupArray:(int32_t)fieldNumber values:(NSArray<GPBUnknownFieldSet*> *)values; 274 /// Write a GPBUnknownFieldSet without any tag (but does write the endGroup tag). 275 - (void)writeUnknownGroupNoTag:(int32_t)fieldNumber 276 value:(GPBUnknownFieldSet *)value; 277 278 //%PDDM-EXPAND-END _WRITE_DECLS() 279 280 /// Write a MessageSet extension field to the stream. For historical reasons, 281 /// the wire format differs from normal fields. 282 - (void)writeMessageSetExtension:(int32_t)fieldNumber value:(GPBMessage *)value; 283 284 /// Write an unparsed MessageSet extension field to the stream. For 285 /// historical reasons, the wire format differs from normal fields. 286 - (void)writeRawMessageSetExtension:(int32_t)fieldNumber value:(NSData *)value; 287 288 @end 289 290 NS_ASSUME_NONNULL_END 291 292 // Write methods for types that can be in packed arrays. 293 //%PDDM-DEFINE _WRITE_PACKABLE_DECLS(NAME, ARRAY_TYPE, TYPE) 294 //%/// Write a TYPE for the given field number. 295 //%- (void)write##NAME:(int32_t)fieldNumber value:(TYPE)value; 296 //%/// Write a packed array of TYPE for the given field number. 297 //%- (void)write##NAME##Array:(int32_t)fieldNumber 298 //% NAME$S values:(GPB##ARRAY_TYPE##Array *)values 299 //% NAME$S tag:(uint32_t)tag; 300 //%/// Write a TYPE without any tag. 301 //%- (void)write##NAME##NoTag:(TYPE)value; 302 //% 303 // Write methods for types that aren't in packed arrays. 304 //%PDDM-DEFINE _WRITE_UNPACKABLE_DECLS(NAME, TYPE) 305 //%/// Write a TYPE for the given field number. 306 //%- (void)write##NAME:(int32_t)fieldNumber value:(TYPE *)value; 307 //%/// Write an array of TYPE for the given field number. 308 //%- (void)write##NAME##Array:(int32_t)fieldNumber values:(NSArray<##TYPE##*> *)values; 309 //%/// Write a TYPE without any tag. 310 //%- (void)write##NAME##NoTag:(TYPE *)value; 311 //% 312 // Special write methods for Groups. 313 //%PDDM-DEFINE _WRITE_GROUP_DECLS(NAME, TYPE) 314 //%/// Write a TYPE for the given field number. 315 //%- (void)write##NAME:(int32_t)fieldNumber 316 //% NAME$S value:(TYPE *)value; 317 //%/// Write an array of TYPE for the given field number. 318 //%- (void)write##NAME##Array:(int32_t)fieldNumber values:(NSArray<##TYPE##*> *)values; 319 //%/// Write a TYPE without any tag (but does write the endGroup tag). 320 //%- (void)write##NAME##NoTag:(int32_t)fieldNumber 321 //% NAME$S value:(TYPE *)value; 322 //% 323 324 // One macro to hide it all up above. 325 //%PDDM-DEFINE _WRITE_DECLS() 326 //%_WRITE_PACKABLE_DECLS(Double, Double, double) 327 //%_WRITE_PACKABLE_DECLS(Float, Float, float) 328 //%_WRITE_PACKABLE_DECLS(UInt64, UInt64, uint64_t) 329 //%_WRITE_PACKABLE_DECLS(Int64, Int64, int64_t) 330 //%_WRITE_PACKABLE_DECLS(Int32, Int32, int32_t) 331 //%_WRITE_PACKABLE_DECLS(UInt32, UInt32, uint32_t) 332 //%_WRITE_PACKABLE_DECLS(Fixed64, UInt64, uint64_t) 333 //%_WRITE_PACKABLE_DECLS(Fixed32, UInt32, uint32_t) 334 //%_WRITE_PACKABLE_DECLS(SInt32, Int32, int32_t) 335 //%_WRITE_PACKABLE_DECLS(SInt64, Int64, int64_t) 336 //%_WRITE_PACKABLE_DECLS(SFixed64, Int64, int64_t) 337 //%_WRITE_PACKABLE_DECLS(SFixed32, Int32, int32_t) 338 //%_WRITE_PACKABLE_DECLS(Bool, Bool, BOOL) 339 //%_WRITE_PACKABLE_DECLS(Enum, Enum, int32_t) 340 //%_WRITE_UNPACKABLE_DECLS(String, NSString) 341 //%_WRITE_UNPACKABLE_DECLS(Message, GPBMessage) 342 //%_WRITE_UNPACKABLE_DECLS(Bytes, NSData) 343 //%_WRITE_GROUP_DECLS(Group, GPBMessage) 344 //%_WRITE_GROUP_DECLS(UnknownGroup, GPBUnknownFieldSet) 345