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 254