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