X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Freference.rst;h=0db8e43e34bad1a63e4f18a1ca20abb258f65bae;hb=a968233777e0781cfd3dd7b9566b631dc576fed1;hp=ec9aec5d56b49bd53dd2b8bd9e3167116e2688fd;hpb=1463e687e36c8dd404d33c6ef1cba61b574adc1e;p=apps%2Fagl-service-can-low-level.git diff --git a/docs/reference.rst b/docs/reference.rst index ec9aec5d..0db8e43e 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -22,6 +22,10 @@ PB_FIELD_32BIT Add support for tag numbers > 65535 and fields la 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. @@ -35,22 +39,23 @@ pb_type_t --------- 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 @@ -58,13 +63,24 @@ HTYPE identifier Value Field handling PB_HTYPE_REQUIRED 0x00 Verify that field exists in decoded message. PB_HTYPE_OPTIONAL 0x10 Use separate *has_* 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 *_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. :: @@ -81,7 +97,7 @@ Describes a single structure field with memory position in relation to others. T } 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. @@ -108,14 +124,16 @@ Part of a message structure, for fields with type PB_HTYPE_CALLBACK:: 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. @@ -322,6 +340,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_* 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. :: @@ -371,7 +399,7 @@ Remove the data for a field from the stream, without actually 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.