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
36NS_ASSUME_NONNULL_BEGIN
37
38CF_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 **/
45extern NSString *const GPBCodedInputStreamException;
46
47/** The key under which the underlying NSError from the exception is stored. */
48extern NSString *const GPBCodedInputStreamUnderlyingErrorKey;
49
50/** NSError domain used for @c GPBCodedInputStream errors. */
51extern NSString *const GPBCodedInputStreamErrorDomain;
52
53/**
54 * Error code for NSError with @c GPBCodedInputStreamErrorDomain.
55 **/
56typedef 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
73CF_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
253NS_ASSUME_NONNULL_END
254