Index: third_party/protobuf/objectivec/GPBCodedInputStream.h |
diff --git a/third_party/protobuf/objectivec/GPBCodedInputStream.h b/third_party/protobuf/objectivec/GPBCodedInputStream.h |
index d64b64e3f3d655b70a778db6d60f08bf2a24c0e6..fbe5009c92b82380dc97d207adf3832004e83966 100644 |
--- a/third_party/protobuf/objectivec/GPBCodedInputStream.h |
+++ b/third_party/protobuf/objectivec/GPBCodedInputStream.h |
@@ -35,94 +35,217 @@ |
NS_ASSUME_NONNULL_BEGIN |
-/// Reads and decodes protocol message fields. |
-/// |
-/// The common uses of protocol buffers shouldn't need to use this class. |
-/// @c GPBMessage's provide a @c +parseFromData:error: and @c |
-/// +parseFromData:extensionRegistry:error: method that will decode a |
-/// message for you. |
-/// |
-/// @note Subclassing of GPBCodedInputStream is NOT supported. |
+CF_EXTERN_C_BEGIN |
+ |
+/** |
+ * @c GPBCodedInputStream exception name. Exceptions raised from |
+ * @c GPBCodedInputStream contain an underlying error in the userInfo dictionary |
+ * under the GPBCodedInputStreamUnderlyingErrorKey key. |
+ **/ |
+extern NSString *const GPBCodedInputStreamException; |
+ |
+/** The key under which the underlying NSError from the exception is stored. */ |
+extern NSString *const GPBCodedInputStreamUnderlyingErrorKey; |
+ |
+/** NSError domain used for @c GPBCodedInputStream errors. */ |
+extern NSString *const GPBCodedInputStreamErrorDomain; |
+ |
+/** |
+ * Error code for NSError with @c GPBCodedInputStreamErrorDomain. |
+ **/ |
+typedef NS_ENUM(NSInteger, GPBCodedInputStreamErrorCode) { |
+ /** The size does not fit in the remaining bytes to be read. */ |
+ GPBCodedInputStreamErrorInvalidSize = -100, |
+ /** Attempted to read beyond the subsection limit. */ |
+ GPBCodedInputStreamErrorSubsectionLimitReached = -101, |
+ /** The requested subsection limit is invalid. */ |
+ GPBCodedInputStreamErrorInvalidSubsectionLimit = -102, |
+ /** Invalid tag read. */ |
+ GPBCodedInputStreamErrorInvalidTag = -103, |
+ /** Invalid UTF-8 character in a string. */ |
+ GPBCodedInputStreamErrorInvalidUTF8 = -104, |
+ /** Invalid VarInt read. */ |
+ GPBCodedInputStreamErrorInvalidVarInt = -105, |
+ /** The maximum recursion depth of messages was exceeded. */ |
+ GPBCodedInputStreamErrorRecursionDepthExceeded = -106, |
+}; |
+ |
+CF_EXTERN_C_END |
+ |
+/** |
+ * Reads and decodes protocol message fields. |
+ * |
+ * The common uses of protocol buffers shouldn't need to use this class. |
+ * @c GPBMessage's provide a @c +parseFromData:error: and |
+ * @c +parseFromData:extensionRegistry:error: method that will decode a |
+ * message for you. |
+ * |
+ * @note Subclassing of @c GPBCodedInputStream is NOT supported. |
+ **/ |
@interface GPBCodedInputStream : NSObject |
-/// Creates a new stream wrapping some data. |
+/** |
+ * Creates a new stream wrapping some data. |
+ * |
+ * @param data The data to wrap inside the stream. |
+ * |
+ * @return A newly instanced GPBCodedInputStream. |
+ **/ |
+ (instancetype)streamWithData:(NSData *)data; |
-/// Initializes a stream wrapping some data. |
+/** |
+ * Initializes a stream wrapping some data. |
+ * |
+ * @param data The data to wrap inside the stream. |
+ * |
+ * @return A newly initialized GPBCodedInputStream. |
+ **/ |
- (instancetype)initWithData:(NSData *)data; |
-/// Attempt to read a field tag, returning zero if we have reached EOF. |
-/// Protocol message parsers use this to read tags, since a protocol message |
-/// may legally end wherever a tag occurs, and zero is not a valid tag number. |
+/** |
+ * Attempts to read a field tag, returning zero if we have reached EOF. |
+ * Protocol message parsers use this to read tags, since a protocol message |
+ * may legally end wherever a tag occurs, and zero is not a valid tag number. |
+ * |
+ * @return The field tag, or zero if EOF was reached. |
+ **/ |
- (int32_t)readTag; |
-/// Read and return a double. |
+/** |
+ * @return A double read from the stream. |
+ **/ |
- (double)readDouble; |
-/// Read and return a float. |
+/** |
+ * @return A float read from the stream. |
+ **/ |
- (float)readFloat; |
-/// Read and return a uint64. |
+/** |
+ * @return A uint64 read from the stream. |
+ **/ |
- (uint64_t)readUInt64; |
-/// Read and return a uint32. |
+/** |
+ * @return A uint32 read from the stream. |
+ **/ |
- (uint32_t)readUInt32; |
-/// Read and return an int64. |
+/** |
+ * @return An int64 read from the stream. |
+ **/ |
- (int64_t)readInt64; |
-/// Read and return an int32. |
+/** |
+ * @return An int32 read from the stream. |
+ **/ |
- (int32_t)readInt32; |
-/// Read and return a fixed64. |
+/** |
+ * @return A fixed64 read from the stream. |
+ **/ |
- (uint64_t)readFixed64; |
-/// Read and return a fixed32. |
+/** |
+ * @return A fixed32 read from the stream. |
+ **/ |
- (uint32_t)readFixed32; |
-/// Read and return an enum (int). |
+/** |
+ * @return An enum read from the stream. |
+ **/ |
- (int32_t)readEnum; |
-/// Read and return a sfixed32. |
+/** |
+ * @return A sfixed32 read from the stream. |
+ **/ |
- (int32_t)readSFixed32; |
-/// Read and return a sfixed64. |
+/** |
+ * @return A fixed64 read from the stream. |
+ **/ |
- (int64_t)readSFixed64; |
-/// Read and return a sint32. |
+/** |
+ * @return A sint32 read from the stream. |
+ **/ |
- (int32_t)readSInt32; |
-/// Read and return a sint64. |
+/** |
+ * @return A sint64 read from the stream. |
+ **/ |
- (int64_t)readSInt64; |
-/// Read and return a boolean. |
+/** |
+ * @return A boolean read from the stream. |
+ **/ |
- (BOOL)readBool; |
-/// Read and return a string. |
+/** |
+ * @return A string read from the stream. |
+ **/ |
- (NSString *)readString; |
-/// Read and return length delimited data. |
+/** |
+ * @return Data read from the stream. |
+ **/ |
- (NSData *)readBytes; |
-/// Read an embedded message field value from the stream. |
-/// |
-/// @param message The message to set fields on as they are read. |
-/// @param extensionRegistry An optional extension registry to use to lookup |
-/// extensions for @message. |
+/** |
+ * Read an embedded message field value from the stream. |
+ * |
+ * @param message The message to set fields on as they are read. |
+ * @param extensionRegistry An optional extension registry to use to lookup |
+ * extensions for message. |
+ **/ |
- (void)readMessage:(GPBMessage *)message |
extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry; |
-/// Reads and discards a single field, given its tag value. |
-/// |
-/// @param tag The tag number of the field to skip. |
-/// |
-/// @return NO if the tag is an endgroup tag (in which case nothing is skipped), |
-/// YES in all other cases. |
+/** |
+ * Reads and discards a single field, given its tag value. |
+ * |
+ * @param tag The tag number of the field to skip. |
+ * |
+ * @return NO if the tag is an endgroup tag (in which case nothing is skipped), |
+ * YES in all other cases. |
+ **/ |
- (BOOL)skipField:(int32_t)tag; |
-/// Reads and discards an entire message. This will read either until EOF |
-/// or until an endgroup tag, whichever comes first. |
+/** |
+ * Reads and discards an entire message. This will read either until EOF or |
+ * until an endgroup tag, whichever comes first. |
+ **/ |
- (void)skipMessage; |
-/// Check to see if the logical end of the stream has been reached. |
-/// |
-/// This can return NO when there is no more data, but the current parsing |
-/// expected more data. |
+/** |
+ * Check to see if the logical end of the stream has been reached. |
+ * |
+ * @note This can return NO when there is no more data, but the current parsing |
+ * expected more data. |
+ * |
+ * @return YES if the logical end of the stream has been reached, NO otherwise. |
+ **/ |
- (BOOL)isAtEnd; |
-/// The offset into the stream. |
+/** |
+ * @return The offset into the stream. |
+ **/ |
- (size_t)position; |
-/// Verifies that the last call to @c -readTag returned the given tag value. |
-/// This is used to verify that a nested group ended with the correct end tag. |
-/// Throws @c NSParseErrorException if value does not match the last tag. |
-/// |
-/// @param expected The tag that was expected. |
+/** |
+ * Moves the limit to the given byte offset starting at the current location. |
+ * |
+ * @exception GPBCodedInputStreamException If the requested bytes exceeed the |
+ * current limit. |
+ * |
+ * @param byteLimit The number of bytes to move the limit, offset to the current |
+ * location. |
+ * |
+ * @return The limit offset before moving the new limit. |
+ */ |
+- (size_t)pushLimit:(size_t)byteLimit; |
+ |
+/** |
+ * Moves the limit back to the offset as it was before calling pushLimit:. |
+ * |
+ * @param oldLimit The number of bytes to move the current limit. Usually this |
+ * is the value returned by the pushLimit: method. |
+ */ |
+- (void)popLimit:(size_t)oldLimit; |
+ |
+/** |
+ * Verifies that the last call to -readTag returned the given tag value. This |
+ * is used to verify that a nested group ended with the correct end tag. |
+ * |
+ * @exception NSParseErrorException If the value does not match the last tag. |
+ * |
+ * @param expected The tag that was expected. |
+ **/ |
- (void)checkLastTagWas:(int32_t)expected; |
@end |