===================
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.
NANOPB_INTERNALS Set this to expose the field encoder functions that are hidden since nanopb-0.1.3.
-PB_MAX_REQUIRED_FIELDS Maximum number of required fields to check for presence. Default value is 64.
-PB_MANY_FIELDS Add support for tag numbers > 255 and fields larger than 255 bytes or 255 array entries.
+PB_MAX_REQUIRED_FIELDS Maximum number of required fields to check for presence. Default value is 64. Increases stack
+ usage 1 byte per every 8 fields. Compiler warning will tell if you need this.
+PB_FIELD_16BIT Add support for tag numbers > 255 and fields larger than 255 bytes or 255 array entries.
+ 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.
+PB_OLD_CALLBACK_STYLE Use the old function signature (void\* instead of void\*\*) for callback fields. This was the
+ default until nanopb-0.2.1.
+============================ ================================================================================================
+
+The PB_MAX_REQUIRED_FIELDS, PB_FIELD_16BIT and PB_FIELD_32BIT settings allow raising some datatype limits to suit larger messages.
+Their need is recognized automatically by C-preprocessor #if-directives in the generated .pb.h files. The default setting is to use
+the smallest datatypes (least resources used).
pb.h
====
---------
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.
:array_size: Maximum number of entries in an array, if it is an array type.
:ptr: Pointer to default value for optional fields, or to submessage description for PB_LTYPE_SUBMESSAGE.
-The *uint8_t* datatypes limit the maximum size of a single item to 255 bytes and arrays to 255 items. Compiler will give error if the values are too large. The types can be changed to larger ones by defining *PB_MANY_FIELDS*.
+The *uint8_t* datatypes limit the maximum size of a single item to 255 bytes and arrays to 255 items. Compiler will give error if the values are too large. The types can be changed to larger ones by defining *PB_FIELD_16BIT*.
pb_bytes_array_t
----------------
typedef struct _pb_callback_t pb_callback_t;
struct _pb_callback_t {
union {
- bool (*decode)(pb_istream_t *stream, const pb_field_t *field, void *arg);
- bool (*encode)(pb_ostream_t *stream, const pb_field_t *field, const void *arg);
+ bool (*decode)(pb_istream_t *stream, const pb_field_t *field, void **arg);
+ bool (*encode)(pb_ostream_t *stream, const pb_field_t *field, void * const *arg);
} funcs;
void *arg;
};
-The *arg* is passed to the callback when calling. It can be used to store any information that the callback might need.
+A pointer to the *arg* is passed to the callback when calling. It can be used to store any information that the callback might need.
+
+Previously the function received just the value of *arg* instead of a pointer to it. This old behaviour can be enabled by defining *PB_OLD_CALLBACK_STYLE*.
When calling `pb_encode`_, *funcs.encode* is used, and similarly when calling `pb_decode`_, *funcs.decode* is used. The function pointers are stored in the same memory location but are of incompatible types. You can set the function pointer to NULL to skip the field.
For optional fields, this function applies the default value and sets *has_<field>* to false if the field is not present.
-pb_decode_varint
+pb_decode_noinit
----------------
-Read and decode a varint_ encoded integer. ::
+Same as `pb_decode`_, except does not apply the default values to fields. ::
- bool pb_decode_varint(pb_istream_t *stream, uint64_t *dest);
+ bool pb_decode_noinit(pb_istream_t *stream, const pb_field_t fields[], void *dest_struct);
-:stream: Input stream to read from. 1-10 bytes will be read.
-:dest: Storage for the decoded integer. Value is undefined on error.
-:returns: True on success, false if value exceeds uint64_t range or an IO error happens.
+(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
--------------
:wire_type: Type of field to skip.
:returns: True on success, false on IO error.
-.. sidebar:: Field decoders
+.. sidebar:: Decoding fields manually
- The functions with names beginning with *pb_dec_* are called field decoders. Each PB_LTYPE has an own field decoder, which handles translating from Protocol Buffers data to C data.
+ The functions with names beginning with *pb_decode_* are used when dealing with callback fields. The typical reason for using callbacks is to have an array of unlimited size. In that case, `pb_decode`_ will call your callback function repeatedly, which can then store the values into e.g. filesystem in the order received in.
- Each field decoder reads and decodes a single value. For arrays, the decoder is called repeatedly.
+ 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.
- You can use the decoders from your callbacks. Just be aware that the pb_field_t passed to the callback is not directly compatible
- with the *varint* field decoders. Instead, you must create a new pb_field_t structure and set the data_size according to the data type
- you pass to *dest*, e.g. *field.data_size = sizeof(int);*. Other fields in the *pb_field_t* don't matter.
+ 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`_.
- The field decoder interface is a bit messy as a result of the interface required inside the nanopb library.
- Eventually they may be replaced by separate wrapper functions with a more friendly interface.
+ Finally, for decoding submessages in a callback, simply use `pb_decode`_ and pass it the *SubMessage_fields* descriptor array.
-pb_dec_varint
--------------
-Field decoder for PB_LTYPE_VARINT. ::
+pb_decode_varint
+----------------
+Read and decode a varint_ encoded integer. ::
- bool pb_dec_varint(pb_istream_t *stream, const pb_field_t *field, void *dest)
+ bool pb_decode_varint(pb_istream_t *stream, uint64_t *dest);
:stream: Input stream to read from. 1-10 bytes will be read.
-:field: Field description structure. Only *field->data_size* matters.
-:dest: Pointer to destination integer. Must have size of *field->data_size* bytes.
-:returns: True on success, false on IO errors or if `pb_decode_varint`_ fails.
-
-This function first calls `pb_decode_varint`_. It then copies the first bytes of the 64-bit result value to *dest*, or on big endian architectures, the last bytes.
+:dest: Storage for the decoded integer. Value is undefined on error.
+:returns: True on success, false if value exceeds uint64_t range or an IO error happens.
-pb_dec_svarint
---------------
-Field decoder for PB_LTYPE_SVARINT. Similar to `pb_dec_varint`_, except that it performs zigzag-decoding on the value. ::
+pb_decode_svarint
+-----------------
+Similar to `pb_decode_varint`_, except that it performs zigzag-decoding on the value. This corresponds to the Protocol Buffers *sint32* and *sint64* datatypes. ::
- bool pb_dec_svarint(pb_istream_t *stream, const pb_field_t *field, void *dest);
+ bool pb_decode_svarint(pb_istream_t *stream, int64_t *dest);
-(parameters are the same as `pb_dec_varint`_)
+(parameters are the same as `pb_decode_varint`_)
-pb_dec_fixed32
---------------
-Field decoder for PB_LTYPE_FIXED32. ::
+pb_decode_fixed32
+-----------------
+Decode a *fixed32*, *sfixed32* or *float* value. ::
- bool pb_dec_fixed32(pb_istream_t *stream, const pb_field_t *field, void *dest);
+ bool pb_decode_fixed32(pb_istream_t *stream, void *dest);
:stream: Input stream to read from. 4 bytes will be read.
-:field: Not used.
:dest: Pointer to destination *int32_t*, *uint32_t* or *float*.
:returns: True on success, false on IO errors.
On big endian architectures, it then reverses the order of the bytes.
Finally, it writes the bytes to *dest*.
-pb_dec_fixed64
---------------
-Field decoder for PB_LTYPE_FIXED64. ::
+pb_decode_fixed64
+-----------------
+Decode a *fixed64*, *sfixed64* or *double* value. ::
bool pb_dec_fixed(pb_istream_t *stream, const pb_field_t *field, void *dest);
:dest: Pointer to destination *int64_t*, *uint64_t* or *double*.
:returns: True on success, false on IO errors.
-Same as `pb_dec_fixed32`_, except this reads 8 bytes.
+Same as `pb_decode_fixed32`_, except this reads 8 bytes.
-pb_dec_bytes
-------------
-Field decoder for PB_LTYPE_BYTES. Reads a length-prefixed block of bytes. ::
+pb_make_string_substream
+------------------------
+Decode the length for a field with wire type *PB_WT_STRING* and create a substream for reading the data. ::
- bool pb_dec_bytes(pb_istream_t *stream, const pb_field_t *field, void *dest);
+ bool pb_make_string_substream(pb_istream_t *stream, pb_istream_t *substream);
-**Note:** This is an internal function that is not useful in decoder callbacks. To read bytes fields in callbacks, use
-*stream->bytes_left* and `pb_read`_.
+:stream: Original input stream to read the length and data from.
+:substream: New substream that has limited length. Filled in by the function.
+:returns: True on success, false if reading the length fails.
-:stream: Input stream to read from.
-:field: Field description structure. Only *field->data_size* matters.
-:dest: Pointer to a structure similar to pb_bytes_array_t.
-:returns: True on success, false on IO error or if length exceeds the array size.
+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.
-This function expects a pointer to a structure with a *size_t* field at start, and a variable sized byte array after it. It will deduce the maximum size of the array from *field->data_size*.
-
-pb_dec_string
--------------
-Field decoder for PB_LTYPE_STRING. Reads a length-prefixed string. ::
+pb_close_string_substream
+-------------------------
+Close the substream created with `pb_make_string_substream`_. ::
- bool pb_dec_string(pb_istream_t *stream, const pb_field_t *field, void *dest);
-
-**Note:** This is an internal function that is not useful in decoder callbacks. To read string fields in callbacks, use
-*stream->bytes_left* and `pb_read`_.
-
-:stream: Input stream to read from.
-:field: Field description structure. Only *field->data_size* matters.
-:dest: Pointer to a character array of size *field->data_size*.
-:returns: True on success, false on IO error or if length exceeds the array size.
-
-This function null-terminates the string when successful. On error, the contents of the destination array is undefined.
-
-pb_dec_submessage
------------------
-Field decoder for PB_LTYPE_SUBMESSAGE. Calls `pb_decode`_ to perform the actual decoding. ::
-
- bool pb_dec_submessage(pb_istream_t *stream, const pb_field_t *field, void *dest)
-
-**Note:** This is an internal function that is not useful in decoder callbacks. To read submessage fields in callbacks, use
-`pb_decode`_ directly.
-
-:stream: Input stream to read from.
-:field: Field description structure. Only *field->ptr* matters.
-:dest: Pointer to the destination structure.
-:returns: True on success, false on IO error or if `pb_decode`_ fails.
+ void pb_close_string_substream(pb_istream_t *stream, pb_istream_t *substream);
-The *field->ptr* should be a pointer to *pb_field_t* array describing the submessage.
+: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.
Code Review / apps / agl-service-can-low-level.git / blobdiff