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.
+PB_BUFFER_ONLY Disables the support for custom streams. Only supports encoding to memory buffers.
+ Speeds up execution and decreases code size slightly.
============================ ================================================================================================
The PB_MAX_REQUIRED_FIELDS, PB_FIELD_16BIT and PB_FIELD_32BIT settings allow raising some datatype limits to suit larger messages.
---------
Defines the encoder/decoder behaviour that should be used for a field. ::
- typedef enum { ... } pb_type_t;
+ typedef uint8_t pb_type_t;
-The low-order byte of the enumeration values defines the function that can be used for encoding and decoding the field data:
+The low-order nibble of the enumeration values defines the function that can be used for encoding and decoding the field data:
==================== ===== ================================================
LTYPE identifier Value Storage format
==================== ===== ================================================
PB_LTYPE_VARINT 0x00 Integer.
PB_LTYPE_SVARINT 0x01 Integer, zigzag encoded.
-PB_LTYPE_FIXED 0x02 Integer or floating point.
-PB_LTYPE_BYTES 0x03 Structure with *size_t* field and byte array.
-PB_LTYPE_STRING 0x04 Null-terminated string.
-PB_LTYPE_SUBMESSAGE 0x05 Submessage structure.
+PB_LTYPE_FIXED32 0x02 32-bit integer or floating point.
+PB_LTYPE_FIXED64 0x03 64-bit integer or floating point.
+PB_LTYPE_BYTES 0x04 Structure with *size_t* field and byte array.
+PB_LTYPE_STRING 0x05 Null-terminated string.
+PB_LTYPE_SUBMESSAGE 0x06 Submessage structure.
==================== ===== ================================================
-The high-order byte defines whether the field is required, optional, repeated or callback:
+The bits 4-5 define whether the field is required, optional or repeated:
==================== ===== ================================================
HTYPE identifier Value Field handling
PB_HTYPE_REQUIRED 0x00 Verify that field exists in decoded message.
PB_HTYPE_OPTIONAL 0x10 Use separate *has_<field>* boolean to specify
whether the field is present.
-PB_HTYPE_ARRAY 0x20 A repeated field with preallocated array.
+ (Unless it is a callback)
+PB_HTYPE_REPEATED 0x20 A repeated field with preallocated array.
Separate *<field>_count* for number of items.
-PB_HTYPE_CALLBACK 0x30 A field with dynamic storage size, data is
- actually a pointer to a structure containing a
- callback function.
+ (Unless it is a callback)
==================== ===== ================================================
+The bits 6-7 define the how the storage for the field is allocated:
+
+==================== ===== ================================================
+ATYPE identifier Value Allocation method
+==================== ===== ================================================
+PB_ATYPE_STATIC 0x00 Statically allocated storage in the structure.
+PB_ATYPE_CALLBACK 0x40 A field with dynamic storage size. Struct field
+ actually contains a pointer to a callback
+ function.
+==================== ===== ================================================
+
+
pb_field_t
----------
Describes a single structure field with memory position in relation to others. The descriptions are usually autogenerated. ::
} pb_packed;
:tag: Tag number of the field or 0 to terminate a list of fields.
-:type: LTYPE and HTYPE of the field.
+:type: LTYPE, HTYPE and ATYPE of the field.
:data_offset: Offset of field data, relative to the end of the previous field.
:size_offset: Offset of *bool* flag for optional fields or *size_t* count for arrays, relative to field data.
:data_size: Size of a single data entry, in bytes. For PB_LTYPE_BYTES, the size of the byte array inside the containing structure. For PB_HTYPE_CALLBACK, size of the C data type if known.
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. ::
For decoding numeric (including enumerated and boolean) values, use `pb_decode_varint`_, `pb_decode_svarint`_, `pb_decode_fixed32`_ and `pb_decode_fixed64`_. They take a pointer to a 32- or 64-bit C variable, which you may then cast to smaller datatype for storage.
- For decoding strings and bytes fields, the length has already been decoded. You can therefore check the total length in *stream->state* and read the data using `pb_read`_.
+ For decoding strings and bytes fields, the length has already been decoded. You can therefore check the total length in *stream->bytes_left* and read the data using `pb_read`_.
Finally, for decoding submessages in a callback, simply use `pb_decode`_ and pass it the *SubMessage_fields* descriptor array.
: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.