rik/nanopb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Added new functions to public interface in pb_decode.h.

Browse Source 
pb_decode_tag and pb_skip_field allow manually iterating the fields
in a message.
This commit is contained in:
Petteri Aimonen
2012-06-16 14:07:37 +03:00
parent 7e1059628c
commit e18352d506
3 changed files with 73 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
docs/reference.rst
View File

@@ -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