iOS/Pods/Protobuf/objectivec/GPBCodedInputStream.h

   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