diff options
Diffstat (limited to 'objectivec/GPBCodedInputStream.h')
| -rw-r--r-- | objectivec/GPBCodedInputStream.h | 199 |
1 files changed, 134 insertions, 65 deletions
diff --git a/objectivec/GPBCodedInputStream.h b/objectivec/GPBCodedInputStream.h index df9d97ba..de27b186 100644 --- a/objectivec/GPBCodedInputStream.h +++ b/objectivec/GPBCodedInputStream.h @@ -37,125 +37,194 @@ NS_ASSUME_NONNULL_BEGIN CF_EXTERN_C_BEGIN -/// GPBCodedInputStream exception name. Exceptions raised from -/// GPBCodedInputStream contain an underlying error in the userInfo dictionary -/// under the GPBCodedInputStreamUnderlyingErrorKey key. +/** + * @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. +/** The key under which the underlying NSError from the exception is stored. */ extern NSString *const GPBCodedInputStreamUnderlyingErrorKey; -/// NSError domain used for GPBCodedInputStream errors. +/** NSError domain used for @c GPBCodedInputStream errors. */ extern NSString *const GPBCodedInputStreamErrorDomain; -/// Error code for NSError with 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. + /** The size does not fit in the remaining bytes to be read. */ GPBCodedInputStreamErrorInvalidSize = -100, - /// Attempted to read beyond the subsection limit. + /** Attempted to read beyond the subsection limit. */ GPBCodedInputStreamErrorSubsectionLimitReached = -101, - /// The requested subsection limit is invalid. + /** The requested subsection limit is invalid. */ GPBCodedInputStreamErrorInvalidSubsectionLimit = -102, - /// Invalid tag read. + /** Invalid tag read. */ GPBCodedInputStreamErrorInvalidTag = -103, - /// Invalid UTF-8 character in a string. + /** Invalid UTF-8 character in a string. */ GPBCodedInputStreamErrorInvalidUTF8 = -104, - /// Invalid VarInt read. + /** Invalid VarInt read. */ GPBCodedInputStreamErrorInvalidVarInt = -105, - /// The maximum recursion depth of messages was exceeded. + /** 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 GPBCodedInputStream is NOT supported. +/** + * 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 @c 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. +/** + * 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 |