X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Freference.rst;h=8c1af773d8e7ceaef047185c9c6b2a24ae106c16;hb=c07e576de86644d278a987550e389b000d8311d0;hp=4021c7647ff608ad00d44d58abb972a7cf993e92;hpb=9fbe9a5de30c3326bd7015e91c5ba634df49ee25;p=apps%2Fagl-service-can-low-level.git

diff --git a/docs/reference.rst b/docs/reference.rst
index 4021c764..8c1af773 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -6,6 +6,12 @@ Nanopb: API reference
 
 .. contents ::
 
+Compilation options
+===================
+The following options can be specified using -D switch given to the C compiler:
+
+:__BIG_ENDIAN__: Set this if your platform stores integers and floats in big-endian format. Mixed-endian systems (different layout for ints and floats) are currently not supported.
+
 pb.h
 ====
 
@@ -283,6 +289,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 +336,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