Add pb_decode_noinit and use it from pb_dec_submessage.

[apps/agl-service-can-low-level.git] / docs / reference.rst

diff --git a/docs/reference.rst b/docs/reference.rst
index 7dd08ed..371c155 100644 (file)
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -20,6 +20,8 @@ PB_FIELD_16BIT                 Add support for tag numbers > 255 and fields larg
                                Increases code size 3 bytes per each field. Compiler error will tell if you need this.
 PB_FIELD_32BIT                 Add support for tag numbers > 65535 and fields larger than 65535 bytes or 65535 array entries.
                                Increases code size 9 bytes per each field. Compiler error will tell if you need this.
+PB_NO_ERRMSG                   Disables the support for error messages; only error information is the true/false return value.
+                               Decreases the code size by a few hundred bytes.
 ============================  ================================================================================================
 
 The PB_MAX_REQUIRED_FIELDS, PB_FIELD_16BIT and PB_FIELD_32BIT settings allow raising some datatype limits to suit larger messages.
@@ -320,6 +322,16 @@ In addition to EOF, the pb_decode implementation supports terminating a message
 
 For optional fields, this function applies the default value and sets *has_<field>* to false if the field is not present.
 
+pb_decode_noinit
+----------------
+Same as `pb_decode`_, except does not apply the default values to fields. ::
+
+    bool pb_decode_noinit(pb_istream_t *stream, const pb_field_t fields[], void *dest_struct);
+
+(parameters are the same as for `pb_decode`_.)
+
+The destination structure should be filled with zeros before calling this function. Doing a *memset* manually can be slightly faster than using `pb_decode`_ if you don't need any default values.
+
 pb_skip_varint
 --------------
 Skip a varint_ encoded integer without decoding it. ::
@@ -428,4 +440,16 @@ Decode the length for a field with wire type *PB_WT_STRING* and create a substre
 :substream:     New substream that has limited length. Filled in by the function.
 :returns:       True on success, false if reading the length fails.
 
-This function uses `pb_decode_varint`_ to read an integer from the stream. This is interpreted as a number of bytes, and the substream is set up so that its `bytes_left` is initially the same as the length. The substream has a wrapper callback that in turn reads from the parent stream.
+This function uses `pb_decode_varint`_ to read an integer from the stream. This is interpreted as a number of bytes, and the substream is set up so that its `bytes_left` is initially the same as the length, and its callback function and state the same as the parent stream.
+
+pb_close_string_substream
+-------------------------
+Close the substream created with `pb_make_string_substream`_. ::
+
+    void pb_close_string_substream(pb_istream_t *stream, pb_istream_t *substream);
+
+:stream:        Original input stream to read the length and data from.
+:substream:     Substream to close
+
+This function copies back the state from the substream to the parent stream.
+It must be called after done with the substream.