Added new functions to public interface in pb_decode.h.

pb_decode_tag and pb_skip_field allow manually iterating the fields
in a message.

1 files changed, 36 insertions, 11 deletions

diff --git a/docs/reference.rst b/docs/reference.rst
index 4021c764..8846ce1b 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -283,6 +283,25 @@ Read data from input stream. Always use this function, don't try to call the str
 
 End of file is signalled by *stream->bytes_left* being zero after pb_read returns false.
 
+pb_decode
+---------
+Read and decode all fields of a structure. Reads until EOF on input stream. ::
+
+    bool pb_decode(pb_istream_t *stream, const pb_field_t fields[], void *dest_struct);
+
+:stream:        Input stream to read from.
+:fields:        A field description array. Usually autogenerated.
+:dest_struct:   Pointer to structure where data will be stored.
+:returns:       True on success, false on IO error, on detectable errors in field description, if a field encoder returns false or if a required field is missing.
+
+In Protocol Buffers binary format, EOF is only allowed between fields. If it happens anywhere else, pb_decode will return *false*. If pb_decode returns false, you cannot trust any of the data in the structure.
+
+In addition to EOF, the pb_decode implementation supports terminating a message with a 0 byte. This is compatible with the official Protocol Buffers because 0 is never a valid field tag.
+
+For optional fields, this function applies the default value and sets *has_<field>* to false if the field is not present.
+
+Because of memory concerns, the detection of missing required fields is not perfect if the structure contains more than 32 fields.
+
 pb_decode_varint
 ----------------
 Read and decode a varint_ encoded integer. ::
@@ -311,24 +330,30 @@ Skip a varint-length-prefixed string. This means skipping a value with wire type
 :stream:        Input stream to read from.
 :returns:       True on success, false on IO error or length exceeding uint32_t.
 
-pb_decode
----------
-Read and decode all fields of a structure. Reads until EOF on input stream. ::
+pb_decode_tag
+-------------
+Decode the tag that comes before field in the protobuf encoding::
 
-    bool pb_decode(pb_istream_t *stream, const pb_field_t fields[], void *dest_struct);
+    bool pb_decode_tag(pb_istream_t *stream, pb_wire_type_t *wire_type, int *tag, bool *eof);
 
 :stream:        Input stream to read from.
-:fields:        A field description array. Usually autogenerated.
-:dest_struct:   Pointer to structure where data will be stored.
-:returns:       True on success, false on IO error, on detectable errors in field description, if a field encoder returns false or if a required field is missing.
+:wire_type:     Pointer to variable where to store the wire type of the field.
+:tag:           Pointer to variable where to store the tag of the field.
+:eof:           Pointer to variable where to store end-of-file status.
+:returns:       True on success, false on error or EOF.
 
-In Protocol Buffers binary format, EOF is only allowed between fields. If it happens anywhere else, pb_decode will return *false*. If pb_decode returns false, you cannot trust any of the data in the structure.
+When the message (stream) ends, this function will return false and set *eof* to true. On other
+errors, *eof* will be set to false.
 
-In addition to EOF, the pb_decode implementation supports terminating a message with a 0 byte. This is compatible with the official Protocol Buffers because 0 is never a valid field tag.
+pb_skip_field
+-------------
+Remove the data for a field from the stream, without actually decoding it::
 
-For optional fields, this function applies the default value and sets *has_<field>* to false if the field is not present.
+    bool pb_skip_field(pb_istream_t *stream, pb_wire_type_t wire_type);
 
-Because of memory concerns, the detection of missing required fields is not perfect if the structure contains more than 32 fields.
+:stream:        Input stream to read from.
+:wire_type:     Type of field to skip.
+:returns:       True on success, false on IO error.
 
 .. sidebar:: Field decoders