.. 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.
+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. 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.
+============================ ================================================================================================
+
+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
====
: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 warn "Initializer too large for type" if the limits are exceeded. The types can be changed to larger ones if necessary.
+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
----------------
End of file is signalled by *stream->bytes_left* being zero after pb_read returns false.
-pb_decode_varint
+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.
+
+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
--------------
: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
+.. 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->state* 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.
-
-pb_dec_bytes
-------------
-Field decoder for PB_LTYPE_BYTES. Reads a length-prefixed block of bytes. ::
-
- bool pb_dec_bytes(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 bytes 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 structure similar to pb_bytes_array_t.
-:returns: True on success, false on IO error or if length exceeds the array size.
-
-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. ::
-
- bool pb_dec_string(pb_istream_t *stream, const pb_field_t *field, void *dest);
+Same as `pb_decode_fixed32`_, except this reads 8 bytes.
-**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`_.
+pb_make_string_substream
+------------------------
+Decode the length for a field with wire type *PB_WT_STRING* and create a substream for reading the data. ::
-: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.
+ bool pb_make_string_substream(pb_istream_t *stream, pb_istream_t *substream);
-pb_dec_submessage
------------------
-Field decoder for PB_LTYPE_SUBMESSAGE. Calls `pb_decode`_ to perform the actual decoding. ::
+: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.
- bool pb_dec_submessage(pb_istream_t *stream, const pb_field_t *field, void *dest)
+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.
-**Note:** This is an internal function that is not useful in decoder callbacks. To read submessage fields in callbacks, use
-`pb_decode`_ directly.
+pb_close_string_substream
+-------------------------
+Close the substream created with `pb_make_string_substream`_. ::
-: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