Added Android code
[wl-app.git] / iOS / Pods / Protobuf / objectivec / GPBCodedInputStream.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 @class GPBMessage;
34 @class GPBExtensionRegistry;
35
36 NS_ASSUME_NONNULL_BEGIN
37
38 CF_EXTERN_C_BEGIN
39
40 /**
41  * @c GPBCodedInputStream exception name. Exceptions raised from
42  * @c GPBCodedInputStream contain an underlying error in the userInfo dictionary
43  * under the GPBCodedInputStreamUnderlyingErrorKey key.
44  **/
45 extern NSString *const GPBCodedInputStreamException;
46
47 /** The key under which the underlying NSError from the exception is stored. */
48 extern NSString *const GPBCodedInputStreamUnderlyingErrorKey;
49
50 /** NSError domain used for @c GPBCodedInputStream errors. */
51 extern NSString *const GPBCodedInputStreamErrorDomain;
52
53 /**
54  * Error code for NSError with @c GPBCodedInputStreamErrorDomain.
55  **/
56 typedef NS_ENUM(NSInteger, GPBCodedInputStreamErrorCode) {
57   /** The size does not fit in the remaining bytes to be read. */
58   GPBCodedInputStreamErrorInvalidSize = -100,
59   /** Attempted to read beyond the subsection limit. */
60   GPBCodedInputStreamErrorSubsectionLimitReached = -101,
61   /** The requested subsection limit is invalid. */
62   GPBCodedInputStreamErrorInvalidSubsectionLimit = -102,
63   /** Invalid tag read. */
64   GPBCodedInputStreamErrorInvalidTag = -103,
65   /** Invalid UTF-8 character in a string. */
66   GPBCodedInputStreamErrorInvalidUTF8 = -104,
67   /** Invalid VarInt read. */
68   GPBCodedInputStreamErrorInvalidVarInt = -105,
69   /** The maximum recursion depth of messages was exceeded. */
70   GPBCodedInputStreamErrorRecursionDepthExceeded = -106,
71 };
72
73 CF_EXTERN_C_END
74
75 /**
76  * Reads and decodes protocol message fields.
77  *
78  * The common uses of protocol buffers shouldn't need to use this class.
79  * @c GPBMessage's provide a @c +parseFromData:error: and
80  * @c +parseFromData:extensionRegistry:error: method that will decode a
81  * message for you.
82  *
83  * @note Subclassing of @c GPBCodedInputStream is NOT supported.
84  **/
85 @interface GPBCodedInputStream : NSObject
86
87 /**
88  * Creates a new stream wrapping some data.
89  *
90  * @param data The data to wrap inside the stream.
91  *
92  * @return A newly instanced GPBCodedInputStream.
93  **/
94 + (instancetype)streamWithData:(NSData *)data;
95
96 /**
97  * Initializes a stream wrapping some data.
98  *
99  * @param data The data to wrap inside the stream.
100  *
101  * @return A newly initialized GPBCodedInputStream.
102  **/
103 - (instancetype)initWithData:(NSData *)data;
104
105 /**
106  * Attempts to read a field tag, returning zero if we have reached EOF.
107  * Protocol message parsers use this to read tags, since a protocol message
108  * may legally end wherever a tag occurs, and zero is not a valid tag number.
109  *
110  * @return The field tag, or zero if EOF was reached.
111  **/
112 - (int32_t)readTag;
113
114 /**
115  * @return A double read from the stream.
116  **/
117 - (double)readDouble;
118 /**
119  * @return A float read from the stream.
120  **/
121 - (float)readFloat;
122 /**
123  * @return A uint64 read from the stream.
124  **/
125 - (uint64_t)readUInt64;
126 /**
127  * @return A uint32 read from the stream.
128  **/
129 - (uint32_t)readUInt32;
130 /**
131  * @return An int64 read from the stream.
132  **/
133 - (int64_t)readInt64;
134 /**
135  * @return An int32 read from the stream.
136  **/
137 - (int32_t)readInt32;
138 /**
139  * @return A fixed64 read from the stream.
140  **/
141 - (uint64_t)readFixed64;
142 /**
143  * @return A fixed32 read from the stream.
144  **/
145 - (uint32_t)readFixed32;
146 /**
147  * @return An enum read from the stream.
148  **/
149 - (int32_t)readEnum;
150 /**
151  * @return A sfixed32 read from the stream.
152  **/
153 - (int32_t)readSFixed32;
154 /**
155  * @return A fixed64 read from the stream.
156  **/
157 - (int64_t)readSFixed64;
158 /**
159  * @return A sint32 read from the stream.
160  **/
161 - (int32_t)readSInt32;
162 /**
163  * @return A sint64 read from the stream.
164  **/
165 - (int64_t)readSInt64;
166 /**
167  * @return A boolean read from the stream.
168  **/
169 - (BOOL)readBool;
170 /**
171  * @return A string read from the stream.
172  **/
173 - (NSString *)readString;
174 /**
175  * @return Data read from the stream.
176  **/
177 - (NSData *)readBytes;
178
179 /**
180  * Read an embedded message field value from the stream.
181  *
182  * @param message           The message to set fields on as they are read.
183  * @param extensionRegistry An optional extension registry to use to lookup
184  *                          extensions for message.
185  **/
186 - (void)readMessage:(GPBMessage *)message
187   extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry;
188
189 /**
190  * Reads and discards a single field, given its tag value.
191  *
192  * @param tag The tag number of the field to skip.
193  *
194  * @return NO if the tag is an endgroup tag (in which case nothing is skipped),
195  *         YES in all other cases.
196  **/
197 - (BOOL)skipField:(int32_t)tag;
198
199 /**
200  * Reads and discards an entire message. This will read either until EOF or
201  * until an endgroup tag, whichever comes first.
202  **/
203 - (void)skipMessage;
204
205 /**
206  * Check to see if the logical end of the stream has been reached.
207  *
208  * @note This can return NO when there is no more data, but the current parsing
209  *       expected more data.
210  *
211  * @return YES if the logical end of the stream has been reached, NO otherwise.
212  **/
213 - (BOOL)isAtEnd;
214
215 /**
216  * @return The offset into the stream.
217  **/
218 - (size_t)position;
219
220 /**
221  * Moves the limit to the given byte offset starting at the current location.
222  *
223  * @exception GPBCodedInputStreamException If the requested bytes exceeed the
224  *            current limit.
225  *
226  * @param byteLimit The number of bytes to move the limit, offset to the current
227  *                  location.
228  *
229  * @return The limit offset before moving the new limit.
230  */
231 - (size_t)pushLimit:(size_t)byteLimit;
232
233 /**
234  * Moves the limit back to the offset as it was before calling pushLimit:.
235  *
236  * @param oldLimit The number of bytes to move the current limit. Usually this
237  *                 is the value returned by the pushLimit: method.
238  */
239 - (void)popLimit:(size_t)oldLimit;
240
241 /**
242  * Verifies that the last call to -readTag returned the given tag value. This
243  * is used to verify that a nested group ended with the correct end tag.
244  *
245  * @exception NSParseErrorException If the value does not match the last tag.
246  *
247  * @param expected The tag that was expected.
248  **/
249 - (void)checkLastTagWas:(int32_t)expected;
250
251 @end
252
253 NS_ASSUME_NONNULL_END