OLD | NEW |
1 // Protocol Buffers - Google's data interchange format | 1 // Protocol Buffers - Google's data interchange format |
2 // Copyright 2008 Google Inc. All rights reserved. | 2 // Copyright 2008 Google Inc. All rights reserved. |
3 // https://developers.google.com/protocol-buffers/ | 3 // https://developers.google.com/protocol-buffers/ |
4 // | 4 // |
5 // Redistribution and use in source and binary forms, with or without | 5 // Redistribution and use in source and binary forms, with or without |
6 // modification, are permitted provided that the following conditions are | 6 // modification, are permitted provided that the following conditions are |
7 // met: | 7 // met: |
8 // | 8 // |
9 // * Redistributions of source code must retain the above copyright | 9 // * Redistributions of source code must retain the above copyright |
10 // notice, this list of conditions and the following disclaimer. | 10 // notice, this list of conditions and the following disclaimer. |
(...skipping 17 matching lines...) Expand all Loading... |
28 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | 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. | 29 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
30 | 30 |
31 #import <Foundation/Foundation.h> | 31 #import <Foundation/Foundation.h> |
32 | 32 |
33 @class GPBMessage; | 33 @class GPBMessage; |
34 @class GPBExtensionRegistry; | 34 @class GPBExtensionRegistry; |
35 | 35 |
36 NS_ASSUME_NONNULL_BEGIN | 36 NS_ASSUME_NONNULL_BEGIN |
37 | 37 |
38 CF_EXTERN_C_BEGIN | 38 /// Reads and decodes protocol message fields. |
39 | 39 /// |
40 /** | 40 /// The common uses of protocol buffers shouldn't need to use this class. |
41 * @c GPBCodedInputStream exception name. Exceptions raised from | 41 /// @c GPBMessage's provide a @c +parseFromData:error: and @c |
42 * @c GPBCodedInputStream contain an underlying error in the userInfo dictionary | 42 /// +parseFromData:extensionRegistry:error: method that will decode a |
43 * under the GPBCodedInputStreamUnderlyingErrorKey key. | 43 /// message for you. |
44 **/ | 44 /// |
45 extern NSString *const GPBCodedInputStreamException; | 45 /// @note Subclassing of GPBCodedInputStream is NOT supported. |
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 | 46 @interface GPBCodedInputStream : NSObject |
86 | 47 |
87 /** | 48 /// Creates a new stream wrapping some data. |
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; | 49 + (instancetype)streamWithData:(NSData *)data; |
95 | 50 |
96 /** | 51 /// Initializes a stream wrapping some data. |
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; | 52 - (instancetype)initWithData:(NSData *)data; |
104 | 53 |
105 /** | 54 /// Attempt to read a field tag, returning zero if we have reached EOF. |
106 * Attempts to read a field tag, returning zero if we have reached EOF. | 55 /// Protocol message parsers use this to read tags, since a protocol message |
107 * Protocol message parsers use this to read tags, since a protocol message | 56 /// may legally end wherever a tag occurs, and zero is not a valid tag number. |
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; | 57 - (int32_t)readTag; |
113 | 58 |
114 /** | 59 /// Read and return a double. |
115 * @return A double read from the stream. | |
116 **/ | |
117 - (double)readDouble; | 60 - (double)readDouble; |
118 /** | 61 /// Read and return a float. |
119 * @return A float read from the stream. | |
120 **/ | |
121 - (float)readFloat; | 62 - (float)readFloat; |
122 /** | 63 /// Read and return a uint64. |
123 * @return A uint64 read from the stream. | |
124 **/ | |
125 - (uint64_t)readUInt64; | 64 - (uint64_t)readUInt64; |
126 /** | 65 /// Read and return a uint32. |
127 * @return A uint32 read from the stream. | |
128 **/ | |
129 - (uint32_t)readUInt32; | 66 - (uint32_t)readUInt32; |
130 /** | 67 /// Read and return an int64. |
131 * @return An int64 read from the stream. | |
132 **/ | |
133 - (int64_t)readInt64; | 68 - (int64_t)readInt64; |
134 /** | 69 /// Read and return an int32. |
135 * @return An int32 read from the stream. | |
136 **/ | |
137 - (int32_t)readInt32; | 70 - (int32_t)readInt32; |
138 /** | 71 /// Read and return a fixed64. |
139 * @return A fixed64 read from the stream. | |
140 **/ | |
141 - (uint64_t)readFixed64; | 72 - (uint64_t)readFixed64; |
142 /** | 73 /// Read and return a fixed32. |
143 * @return A fixed32 read from the stream. | |
144 **/ | |
145 - (uint32_t)readFixed32; | 74 - (uint32_t)readFixed32; |
146 /** | 75 /// Read and return an enum (int). |
147 * @return An enum read from the stream. | |
148 **/ | |
149 - (int32_t)readEnum; | 76 - (int32_t)readEnum; |
150 /** | 77 /// Read and return a sfixed32. |
151 * @return A sfixed32 read from the stream. | |
152 **/ | |
153 - (int32_t)readSFixed32; | 78 - (int32_t)readSFixed32; |
154 /** | 79 /// Read and return a sfixed64. |
155 * @return A fixed64 read from the stream. | |
156 **/ | |
157 - (int64_t)readSFixed64; | 80 - (int64_t)readSFixed64; |
158 /** | 81 /// Read and return a sint32. |
159 * @return A sint32 read from the stream. | |
160 **/ | |
161 - (int32_t)readSInt32; | 82 - (int32_t)readSInt32; |
162 /** | 83 /// Read and return a sint64. |
163 * @return A sint64 read from the stream. | |
164 **/ | |
165 - (int64_t)readSInt64; | 84 - (int64_t)readSInt64; |
166 /** | 85 /// Read and return a boolean. |
167 * @return A boolean read from the stream. | |
168 **/ | |
169 - (BOOL)readBool; | 86 - (BOOL)readBool; |
170 /** | 87 /// Read and return a string. |
171 * @return A string read from the stream. | |
172 **/ | |
173 - (NSString *)readString; | 88 - (NSString *)readString; |
174 /** | 89 /// Read and return length delimited data. |
175 * @return Data read from the stream. | |
176 **/ | |
177 - (NSData *)readBytes; | 90 - (NSData *)readBytes; |
178 | 91 |
179 /** | 92 /// Read an embedded message field value from the stream. |
180 * Read an embedded message field value from the stream. | 93 /// |
181 * | 94 /// @param message The message to set fields on as they are read. |
182 * @param message The message to set fields on as they are read. | 95 /// @param extensionRegistry An optional extension registry to use to lookup |
183 * @param extensionRegistry An optional extension registry to use to lookup | 96 /// extensions for @message. |
184 * extensions for message. | |
185 **/ | |
186 - (void)readMessage:(GPBMessage *)message | 97 - (void)readMessage:(GPBMessage *)message |
187 extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry; | 98 extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry; |
188 | 99 |
189 /** | 100 /// Reads and discards a single field, given its tag value. |
190 * Reads and discards a single field, given its tag value. | 101 /// |
191 * | 102 /// @param tag The tag number of the field to skip. |
192 * @param tag The tag number of the field to skip. | 103 /// |
193 * | 104 /// @return NO if the tag is an endgroup tag (in which case nothing is skipped), |
194 * @return NO if the tag is an endgroup tag (in which case nothing is skipped), | 105 /// YES in all other cases. |
195 * YES in all other cases. | |
196 **/ | |
197 - (BOOL)skipField:(int32_t)tag; | 106 - (BOOL)skipField:(int32_t)tag; |
198 | 107 |
199 /** | 108 /// Reads and discards an entire message. This will read either until EOF |
200 * Reads and discards an entire message. This will read either until EOF or | 109 /// or until an endgroup tag, whichever comes first. |
201 * until an endgroup tag, whichever comes first. | |
202 **/ | |
203 - (void)skipMessage; | 110 - (void)skipMessage; |
204 | 111 |
205 /** | 112 /// Check to see if the logical end of the stream has been reached. |
206 * Check to see if the logical end of the stream has been reached. | 113 /// |
207 * | 114 /// This can return NO when there is no more data, but the current parsing |
208 * @note This can return NO when there is no more data, but the current parsing | 115 /// expected more data. |
209 * expected more data. | |
210 * | |
211 * @return YES if the logical end of the stream has been reached, NO otherwise. | |
212 **/ | |
213 - (BOOL)isAtEnd; | 116 - (BOOL)isAtEnd; |
214 | 117 |
215 /** | 118 /// The offset into the stream. |
216 * @return The offset into the stream. | |
217 **/ | |
218 - (size_t)position; | 119 - (size_t)position; |
219 | 120 |
220 /** | 121 /// Verifies that the last call to @c -readTag returned the given tag value. |
221 * Moves the limit to the given byte offset starting at the current location. | 122 /// This is used to verify that a nested group ended with the correct end tag. |
222 * | 123 /// Throws @c NSParseErrorException if value does not match the last tag. |
223 * @exception GPBCodedInputStreamException If the requested bytes exceeed the | 124 /// |
224 * current limit. | 125 /// @param expected The tag that was expected. |
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; | 126 - (void)checkLastTagWas:(int32_t)expected; |
250 | 127 |
251 @end | 128 @end |
252 | 129 |
253 NS_ASSUME_NONNULL_END | 130 NS_ASSUME_NONNULL_END |
OLD | NEW |