added iOS source code
[wl-app.git] / iOS / Pods / Protobuf / objectivec / GPBMessage.h
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 "GPBBootstrap.h"
34
35 @class GPBDescriptor;
36 @class GPBCodedInputStream;
37 @class GPBCodedOutputStream;
38 @class GPBExtensionDescriptor;
39 @class GPBExtensionRegistry;
40 @class GPBFieldDescriptor;
41 @class GPBUnknownFieldSet;
42
43 NS_ASSUME_NONNULL_BEGIN
44
45 CF_EXTERN_C_BEGIN
46
47 /** NSError domain used for errors. */
48 extern NSString *const GPBMessageErrorDomain;
49
50 /** Error codes for NSErrors originated in GPBMessage. */
51 typedef NS_ENUM(NSInteger, GPBMessageErrorCode) {
52   /** Uncategorized error. */
53   GPBMessageErrorCodeOther = -100,
54   /** Message couldn't be serialized because it is missing required fields. */
55   GPBMessageErrorCodeMissingRequiredField = -101,
56 };
57
58 /**
59  * Key under which the GPBMessage error's reason is stored inside the userInfo
60  * dictionary.
61  **/
62 extern NSString *const GPBErrorReasonKey;
63
64 CF_EXTERN_C_END
65
66 /**
67  * Base class that each generated message subclasses from.
68  *
69  * @note @c NSCopying support is a "deep copy", in that all sub objects are
70  *       copied.  Just like you wouldn't want a UIView/NSView trying to
71  *       exist in two places, you don't want a sub message to be a property
72  *       property of two other messages.
73  *
74  * @note While the class support NSSecureCoding, if the message has any
75  *       extensions, they will end up reloaded in @c unknownFields as there is
76  *       no way for the @c NSCoding plumbing to pass through a
77  *       @c GPBExtensionRegistry. To support extensions, instead of passing the
78  *       calls off to the Message, simple store the result of @c data, and then
79  *       when loading, fetch the data and use
80  *       @c +parseFromData:extensionRegistry:error: to provide an extension
81  *       registry.
82  **/
83 @interface GPBMessage : NSObject<NSSecureCoding, NSCopying>
84
85 // If you add an instance method/property to this class that may conflict with
86 // fields declared in protos, you need to update objective_helpers.cc. The main
87 // cases are methods that take no arguments, or setFoo:/hasFoo: type methods.
88
89 /**
90  * The set of unknown fields for this message.
91  *
92  * Only messages from proto files declared with "proto2" syntax support unknown
93  * fields. For "proto3" syntax, any unknown fields found while parsing are
94  * dropped.
95  **/
96 @property(nonatomic, copy, nullable) GPBUnknownFieldSet *unknownFields;
97
98 /**
99  * Whether the message, along with all submessages, have the required fields
100  * set. This is only applicable for files declared with "proto2" syntax, as
101  * there are no required fields for "proto3" syntax.
102  **/
103 @property(nonatomic, readonly, getter=isInitialized) BOOL initialized;
104
105 /**
106  * @return An autoreleased message with the default values set.
107  **/
108 + (instancetype)message;
109
110 /**
111  * Creates a new instance by parsing the provided data. This method should be
112  * sent to the generated message class that the data should be interpreted as.
113  * If there is an error the method returns nil and the error is returned in
114  * errorPtr (when provided).
115  *
116  * @note In DEBUG builds, the parsed message is checked to be sure all required
117  *       fields were provided, and the parse will fail if some are missing.
118  *
119  * @note The errors returned are likely coming from the domain and codes listed
120  *       at the top of this file and GPBCodedInputStream.h.
121  *
122  * @param data     The data to parse.
123  * @param errorPtr An optional error pointer to fill in with a failure reason if
124  *                 the data can not be parsed.
125  *
126  * @return A new instance of the generated class.
127  **/
128 + (nullable instancetype)parseFromData:(NSData *)data error:(NSError **)errorPtr;
129
130 /**
131  * Creates a new instance by parsing the data. This method should be sent to
132  * the generated message class that the data should be interpreted as. If
133  * there is an error the method returns nil and the error is returned in
134  * errorPtr (when provided).
135  *
136  * @note In DEBUG builds, the parsed message is checked to be sure all required
137  *       fields were provided, and the parse will fail if some are missing.
138  *
139  * @note The errors returned are likely coming from the domain and codes listed
140  *       at the top of this file and GPBCodedInputStream.h.
141  *
142  * @param data              The data to parse.
143  * @param extensionRegistry The extension registry to use to look up extensions.
144  * @param errorPtr          An optional error pointer to fill in with a failure
145  *                          reason if the data can not be parsed.
146  *
147  * @return A new instance of the generated class.
148  **/
149 + (nullable instancetype)parseFromData:(NSData *)data
150                      extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry
151                                  error:(NSError **)errorPtr;
152
153 /**
154  * Creates a new instance by parsing the data from the given input stream. This
155  * method should be sent to the generated message class that the data should
156  * be interpreted as. If there is an error the method returns nil and the error
157  * is returned in errorPtr (when provided).
158  *
159  * @note In DEBUG builds, the parsed message is checked to be sure all required
160  *       fields were provided, and the parse will fail if some are missing.
161  *
162  * @note The errors returned are likely coming from the domain and codes listed
163  *       at the top of this file and GPBCodedInputStream.h.
164  *
165  * @param input             The stream to read data from.
166  * @param extensionRegistry The extension registry to use to look up extensions.
167  * @param errorPtr          An optional error pointer to fill in with a failure
168  *                          reason if the data can not be parsed.
169  *
170  * @return A new instance of the generated class.
171  **/
172 + (nullable instancetype)parseFromCodedInputStream:(GPBCodedInputStream *)input
173                                  extensionRegistry:
174                                      (nullable GPBExtensionRegistry *)extensionRegistry
175                                              error:(NSError **)errorPtr;
176
177 /**
178  * Creates a new instance by parsing the data from the given input stream. This
179  * method should be sent to the generated message class that the data should
180  * be interpreted as. If there is an error the method returns nil and the error
181  * is returned in errorPtr (when provided).
182  *
183  * @note Unlike the parseFrom... methods, this never checks to see if all of
184  *       the required fields are set. So this method can be used to reload
185  *       messages that may not be complete.
186  *
187  * @note The errors returned are likely coming from the domain and codes listed
188  *       at the top of this file and GPBCodedInputStream.h.
189  *
190  * @param input             The stream to read data from.
191  * @param extensionRegistry The extension registry to use to look up extensions.
192  * @param errorPtr          An optional error pointer to fill in with a failure
193  *                          reason if the data can not be parsed.
194  *
195  * @return A new instance of the generated class.
196  **/
197 + (nullable instancetype)parseDelimitedFromCodedInputStream:(GPBCodedInputStream *)input
198                                           extensionRegistry:
199                                               (nullable GPBExtensionRegistry *)extensionRegistry
200                                                       error:(NSError **)errorPtr;
201
202 /**
203  * Initializes an instance by parsing the data. This method should be sent to
204  * the generated message class that the data should be interpreted as. If
205  * there is an error the method returns nil and the error is returned in
206  * errorPtr (when provided).
207  *
208  * @note In DEBUG builds, the parsed message is checked to be sure all required
209  *       fields were provided, and the parse will fail if some are missing.
210  *
211  * @note The errors returned are likely coming from the domain and codes listed
212  *       at the top of this file and GPBCodedInputStream.h.
213  *
214  * @param data     The data to parse.
215  * @param errorPtr An optional error pointer to fill in with a failure reason if
216  *                 the data can not be parsed.
217  *
218  * @return An initialized instance of the generated class.
219  **/
220 - (nullable instancetype)initWithData:(NSData *)data error:(NSError **)errorPtr;
221
222 /**
223  * Initializes an instance by parsing the data. This method should be sent to
224  * the generated message class that the data should be interpreted as. If
225  * there is an error the method returns nil and the error is returned in
226  * errorPtr (when provided).
227  *
228  * @note In DEBUG builds, the parsed message is checked to be sure all required
229  *       fields were provided, and the parse will fail if some are missing.
230  *
231  * @note The errors returned are likely coming from the domain and codes listed
232  *       at the top of this file and GPBCodedInputStream.h.
233  *
234  * @param data              The data to parse.
235  * @param extensionRegistry The extension registry to use to look up extensions.
236  * @param errorPtr          An optional error pointer to fill in with a failure
237  *                          reason if the data can not be parsed.
238  *
239  * @return An initialized instance of the generated class.
240  **/
241 - (nullable instancetype)initWithData:(NSData *)data
242                     extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry
243                                 error:(NSError **)errorPtr;
244
245 /**
246  * Initializes an instance by parsing the data from the given input stream. This
247  * method should be sent to the generated message class that the data should
248  * be interpreted as. If there is an error the method returns nil and the error
249  * is returned in errorPtr (when provided).
250  *
251  * @note Unlike the parseFrom... methods, this never checks to see if all of
252  *       the required fields are set. So this method can be used to reload
253  *       messages that may not be complete.
254  *
255  * @note The errors returned are likely coming from the domain and codes listed
256  *       at the top of this file and GPBCodedInputStream.h.
257  *
258  * @param input             The stream to read data from.
259  * @param extensionRegistry The extension registry to use to look up extensions.
260  * @param errorPtr          An optional error pointer to fill in with a failure
261  *                          reason if the data can not be parsed.
262  *
263  * @return An initialized instance of the generated class.
264  **/
265 - (nullable instancetype)initWithCodedInputStream:(GPBCodedInputStream *)input
266                                 extensionRegistry:
267                                     (nullable GPBExtensionRegistry *)extensionRegistry
268                                             error:(NSError **)errorPtr;
269
270 /**
271  * Parses the given data as this message's class, and merges those values into
272  * this message.
273  *
274  * @param data              The binary representation of the message to merge.
275  * @param extensionRegistry The extension registry to use to look up extensions.
276  *
277  * @exception GPBCodedInputStreamException Exception thrown when parsing was
278  *                                         unsuccessful.
279  **/
280 - (void)mergeFromData:(NSData *)data
281     extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry;
282
283 /**
284  * Merges the fields from another message (of the same type) into this
285  * message.
286  *
287  * @param other Message to merge into this message.
288  **/
289 - (void)mergeFrom:(GPBMessage *)other;
290
291 /**
292  * Writes out the message to the given coded output stream.
293  *
294  * @param output The coded output stream into which to write the message.
295  *
296  * @note This can raise the GPBCodedOutputStreamException_* exceptions.
297  *
298  **/
299 - (void)writeToCodedOutputStream:(GPBCodedOutputStream *)output;
300
301 /**
302  * Writes out the message to the given output stream.
303  *
304  * @param output The output stream into which to write the message.
305  *
306  * @note This can raise the GPBCodedOutputStreamException_* exceptions.
307  **/
308 - (void)writeToOutputStream:(NSOutputStream *)output;
309
310 /**
311  * Writes out a varint for the message size followed by the the message to
312  * the given output stream.
313  *
314  * @param output The coded output stream into which to write the message.
315  *
316  * @note This can raise the GPBCodedOutputStreamException_* exceptions.
317  **/
318 - (void)writeDelimitedToCodedOutputStream:(GPBCodedOutputStream *)output;
319
320 /**
321  * Writes out a varint for the message size followed by the the message to
322  * the given output stream.
323  *
324  * @param output The output stream into which to write the message.
325  *
326  * @note This can raise the GPBCodedOutputStreamException_* exceptions.
327  **/
328 - (void)writeDelimitedToOutputStream:(NSOutputStream *)output;
329
330 /**
331  * Serializes the message to an NSData.
332  *
333  * If there is an error while generating the data, nil is returned.
334  *
335  * @note This value is not cached, so if you are using it repeatedly, cache
336  *       it yourself.
337  *
338  * @note In DEBUG ONLY, the message is also checked for all required field,
339  *       if one is missing, nil will be returned.
340  *
341  * @return The binary representation of the message.
342  **/
343 - (nullable NSData *)data;
344
345 /**
346  * Serializes a varint with the message size followed by the message data,
347  * returning that as an NSData.
348  *
349  * @note This value is not cached, so if you are using it repeatedly, it is
350  *       recommended to keep a local copy.
351  *
352  * @return The binary representation of the size along with the message.
353  **/
354 - (NSData *)delimitedData;
355
356 /**
357  * Calculates the size of the object if it were serialized.
358  *
359  * This is not a cached value. If you are following a pattern like this:
360  *
361  * ```
362  * size_t size = [aMsg serializedSize];
363  * NSMutableData *foo = [NSMutableData dataWithCapacity:size + sizeof(size)];
364  * [foo writeSize:size];
365  * [foo appendData:[aMsg data]];
366  * ```
367  *
368  * you would be better doing:
369  *
370  * ```
371  * NSData *data = [aMsg data];
372  * NSUInteger size = [aMsg length];
373  * NSMutableData *foo = [NSMutableData dataWithCapacity:size + sizeof(size)];
374  * [foo writeSize:size];
375  * [foo appendData:data];
376  * ```
377  *
378  * @return The size of the message in it's binary representation.
379  **/
380 - (size_t)serializedSize;
381
382 /**
383  * @return The descriptor for the message class.
384  **/
385 + (GPBDescriptor *)descriptor;
386
387 /**
388  * Return the descriptor for the message.
389  **/
390 - (GPBDescriptor *)descriptor;
391
392 /**
393  * @return An array with the extension descriptors that are currently set on the
394  * message.
395  **/
396 - (NSArray *)extensionsCurrentlySet;
397
398 /**
399  * Checks whether there is an extension set on the message which matches the
400  * given extension descriptor.
401  *
402  * @param extension Extension descriptor to check if it's set on the message.
403  *
404  * @return Whether the extension is currently set on the message.
405  **/
406 - (BOOL)hasExtension:(GPBExtensionDescriptor *)extension;
407
408 /*
409  * Fetches the given extension's value for this message.
410  *
411  * Extensions use boxed values (NSNumbers) for PODs and NSMutableArrays for
412  * repeated fields. If the extension is a Message one will be auto created for
413  * you and returned similar to fields.
414  *
415  * @param extension The extension descriptor of the extension to fetch.
416  *
417  * @return The extension matching the given descriptor, or nil if none found.
418  **/
419 - (nullable id)getExtension:(GPBExtensionDescriptor *)extension;
420
421 /**
422  * Sets the given extension's value for this message. This only applies for
423  * single field extensions (i.e. - not repeated fields).
424  *
425  * Extensions use boxed values (NSNumbers).
426  *
427  * @param extension The extension descriptor under which to set the value.
428  * @param value     The value to be set as the extension.
429  **/
430 - (void)setExtension:(GPBExtensionDescriptor *)extension
431                value:(nullable id)value;
432
433 /**
434  * Adds the given value to the extension for this message. This only applies
435  * to repeated field extensions. If the field is a repeated POD type, the value
436  * should be an NSNumber.
437  *
438  * @param extension The extension descriptor under which to add the value.
439  * @param value     The value to be added to the repeated extension.
440  **/
441 - (void)addExtension:(GPBExtensionDescriptor *)extension value:(id)value;
442
443 /**
444  * Replaces the value at the given index with the given value for the extension
445  * on this message. This only applies to repeated field extensions. If the field
446  * is a repeated POD type, the value is should be an NSNumber.
447  *
448  * @param extension The extension descriptor under which to replace the value.
449  * @param index     The index of the extension to be replaced.
450  * @param value     The value to be replaced in the repeated extension.
451  **/
452 - (void)setExtension:(GPBExtensionDescriptor *)extension
453                index:(NSUInteger)index
454                value:(id)value;
455
456 /**
457  * Clears the given extension for this message.
458  *
459  * @param extension The extension descriptor to be cleared from this message.
460  **/
461 - (void)clearExtension:(GPBExtensionDescriptor *)extension;
462
463 /**
464  * Resets all of the fields of this message to their default values.
465  **/
466 - (void)clear;
467
468 @end
469
470 NS_ASSUME_NONNULL_END