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.

3 files changed, 73 insertions, 29 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
     
diff --git a/pb_decode.c b/pb_decode.c
index eace906f..50a11c40 100644
--- a/pb_decode.c
+++ b/pb_decode.c
@@ -117,12 +117,33 @@ bool checkreturn pb_skip_string(pb_istream_t *stream)
     return pb_read(stream, NULL, length);
 }
 
-/* Currently the wire type related stuff is kept hidden from
- * callbacks. They shouldn't need it. It's better for performance
- * to just assume the correct type and fail safely on corrupt message.
- */
+bool checkreturn pb_decode_tag(pb_istream_t *stream, pb_wire_type_t *wire_type, int *tag, bool *eof)
+{
+    uint32_t temp;
+    *eof = false;
+    *wire_type = 0;
+    *tag = 0;
+    
+    if (!pb_decode_varint32(stream, &temp))
+    {
+        if (stream->bytes_left == 0)
+            *eof = true;
+
+        return false;
+    }
+    
+    if (temp == 0)
+    {
+        *eof = true; /* Special feature: allow 0-terminated messages. */
+        return false;
+    }
+    
+    *tag = temp >> 3;
+    *wire_type = (pb_wire_type_t)(temp & 7);
+    return true;
+}
 
-static bool checkreturn skip(pb_istream_t *stream, pb_wire_type_t wire_type)
+bool checkreturn pb_skip_field(pb_istream_t *stream, pb_wire_type_t wire_type)
 {
     switch (wire_type)
     {
@@ -292,7 +313,7 @@ static bool checkreturn decode_field(pb_istream_t *stream, pb_wire_type_t wire_t
             pb_callback_t *pCallback = (pb_callback_t*)iter->pData;
             
             if (pCallback->funcs.decode == NULL)
-                return skip(stream, wire_type);
+                return pb_skip_field(stream, wire_type);
             
             if (wire_type == PB_WT_STRING)
             {
@@ -392,27 +413,22 @@ bool checkreturn pb_decode(pb_istream_t *stream, const pb_field_t fields[], void
     
     while (stream->bytes_left)
     {
-        uint32_t temp;
         int tag;
         pb_wire_type_t wire_type;
-        if (!pb_decode_varint32(stream, &temp))
+        bool eof;
+        
+        if (!pb_decode_tag(stream, &wire_type, &tag, &eof))
         {
-            if (stream->bytes_left == 0)
-                break; /* It was EOF */
+            if (eof)
+                break;
             else
-                return false; /* It was error */
+                return false;
         }
         
-        if (temp == 0)
-            break; /* Special feature: allow 0-terminated messages. */
-        
-        tag = temp >> 3;
-        wire_type = (pb_wire_type_t)(temp & 7);
-        
         if (!pb_field_find(&iter, tag))
         {
             /* No match found, skip data */
-            if (!skip(stream, wire_type))
+            if (!pb_skip_field(stream, wire_type))
                 return false;
             continue;
         }
diff --git a/pb_decode.h b/pb_decode.h
index f12b1900..0abb342c 100644
--- a/pb_decode.h
+++ b/pb_decode.h
@@ -48,6 +48,9 @@ bool pb_decode(pb_istream_t *stream, const pb_field_t fields[], void *dest_struc
  * You may want to use these from your caller or callbacks.
  */
 
+bool pb_decode_tag(pb_istream_t *stream, pb_wire_type_t *wire_type, int *tag, bool *eof);
+bool pb_skip_field(pb_istream_t *stream, pb_wire_type_t wire_type);
+
 bool pb_decode_varint(pb_istream_t *stream, uint64_t *dest);
 
 bool pb_skip_varint(pb_istream_t *stream);