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 /// GPBCodedInputStream exception name. Exceptions raised from 41 /// GPBCodedInputStream contain an underlying error in the userInfo dictionary 42 /// under the GPBCodedInputStreamUnderlyingErrorKey key. 43 extern NSString *const GPBCodedInputStreamException; 44 45 /// The key under which the underlying NSError from the exception is stored. 46 extern NSString *const GPBCodedInputStreamUnderlyingErrorKey; 47 48 /// NSError domain used for GPBCodedInputStream errors. 49 extern NSString *const GPBCodedInputStreamErrorDomain; 50 51 /// Error code for NSError with GPBCodedInputStreamErrorDomain. 52 typedef NS_ENUM(NSInteger, GPBCodedInputStreamErrorCode) { 53 /// The size does not fit in the remaining bytes to be read. 54 GPBCodedInputStreamErrorInvalidSize = -100, 55 /// Attempted to read beyond the subsection limit. 56 GPBCodedInputStreamErrorSubsectionLimitReached = -101, 57 /// The requested subsection limit is invalid. 58 GPBCodedInputStreamErrorInvalidSubsectionLimit = -102, 59 /// Invalid tag read. 60 GPBCodedInputStreamErrorInvalidTag = -103, 61 /// Invalid UTF-8 character in a string. 62 GPBCodedInputStreamErrorInvalidUTF8 = -104, 63 /// Invalid VarInt read. 64 GPBCodedInputStreamErrorInvalidVarInt = -105, 65 /// The maximum recursion depth of messages was exceeded. 66 GPBCodedInputStreamErrorRecursionDepthExceeded = -106, 67 }; 68 69 CF_EXTERN_C_END 70 71 /// Reads and decodes protocol message fields. 72 /// 73 /// The common uses of protocol buffers shouldn't need to use this class. 74 /// @c GPBMessage's provide a @c +parseFromData:error: and @c 75 /// +parseFromData:extensionRegistry:error: method that will decode a 76 /// message for you. 77 /// 78 /// @note Subclassing of GPBCodedInputStream is NOT supported. 79 @interface GPBCodedInputStream : NSObject 80 81 /// Creates a new stream wrapping some data. 82 + (instancetype)streamWithData:(NSData *)data; 83 84 /// Initializes a stream wrapping some data. 85 - (instancetype)initWithData:(NSData *)data; 86 87 /// Attempt to read a field tag, returning zero if we have reached EOF. 88 /// Protocol message parsers use this to read tags, since a protocol message 89 /// may legally end wherever a tag occurs, and zero is not a valid tag number. 90 - (int32_t)readTag; 91 92 /// Read and return a double. 93 - (double)readDouble; 94 /// Read and return a float. 95 - (float)readFloat; 96 /// Read and return a uint64. 97 - (uint64_t)readUInt64; 98 /// Read and return a uint32. 99 - (uint32_t)readUInt32; 100 /// Read and return an int64. 101 - (int64_t)readInt64; 102 /// Read and return an int32. 103 - (int32_t)readInt32; 104 /// Read and return a fixed64. 105 - (uint64_t)readFixed64; 106 /// Read and return a fixed32. 107 - (uint32_t)readFixed32; 108 /// Read and return an enum (int). 109 - (int32_t)readEnum; 110 /// Read and return a sfixed32. 111 - (int32_t)readSFixed32; 112 /// Read and return a sfixed64. 113 - (int64_t)readSFixed64; 114 /// Read and return a sint32. 115 - (int32_t)readSInt32; 116 /// Read and return a sint64. 117 - (int64_t)readSInt64; 118 /// Read and return a boolean. 119 - (BOOL)readBool; 120 /// Read and return a string. 121 - (NSString *)readString; 122 /// Read and return length delimited data. 123 - (NSData *)readBytes; 124 125 /// Read an embedded message field value from the stream. 126 /// 127 /// @param message The message to set fields on as they are read. 128 /// @param extensionRegistry An optional extension registry to use to lookup 129 /// extensions for @c message. 130 - (void)readMessage:(GPBMessage *)message 131 extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry; 132 133 /// Reads and discards a single field, given its tag value. 134 /// 135 /// @param tag The tag number of the field to skip. 136 /// 137 /// @return NO if the tag is an endgroup tag (in which case nothing is skipped), 138 /// YES in all other cases. 139 - (BOOL)skipField:(int32_t)tag; 140 141 /// Reads and discards an entire message. This will read either until EOF 142 /// or until an endgroup tag, whichever comes first. 143 - (void)skipMessage; 144 145 /// Check to see if the logical end of the stream has been reached. 146 /// 147 /// This can return NO when there is no more data, but the current parsing 148 /// expected more data. 149 - (BOOL)isAtEnd; 150 151 /// The offset into the stream. 152 - (size_t)position; 153 154 /// Verifies that the last call to @c -readTag returned the given tag value. 155 /// This is used to verify that a nested group ended with the correct end tag. 156 /// Throws @c NSParseErrorException if value does not match the last tag. 157 /// 158 /// @param expected The tag that was expected. 159 - (void)checkLastTagWas:(int32_t)expected; 160 161 @end 162 163 NS_ASSUME_NONNULL_END 164