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