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_NO_PACKED_STRUCTS Disable packed structs. Increases RAM usage but
+ is necessary on some platforms that do not
+ support unaligned memory access.
+PB_ENABLE_MALLOC Set this to enable dynamic allocation support
+ in the decoder.
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
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.
+PB_SYSTEM_HEADER Replace the standard header files with a single
+ header file. It should define all the required
+ functions and typedefs listed on the
+ `overview page`_. Value must include quotes,
+ for example *#define PB_SYSTEM_HEADER "foo.h"*.
============================ ================================================
The PB_MAX_REQUIRED_FIELDS, PB_FIELD_16BIT and PB_FIELD_32BIT settings allow
automatically by C-preprocessor #if-directives in the generated .pb.h files.
The default setting is to use the smallest datatypes (least resources used).
-
+.. _`overview page`: index.html#compiler-requirements
Proto file options
max_size Allocated size for *bytes* and *string* fields.
max_count Allocated number of entries in arrays
(*repeated* fields).
+int_size Override the integer type of a field.
+ (To use e.g. uint8_t to save RAM.)
type Type of the generated field. Default value
is *FT_DEFAULT*, which selects automatically.
- You can use *FT_CALLBACK*, *FT_STATIC* or
- *FT_IGNORE* to force a callback field, a static
+ You can use *FT_CALLBACK*, *FT_POINTER*,
+ *FT_STATIC* or *FT_IGNORE* to force a callback
+ field, a dynamically allocated field, a static
field or to completely ignore the field.
long_names Prefix the enum name to the enum value in
definitions, i.e. *EnumName_EnumValue*. Enabled
packed_struct Make the generated structures packed.
NOTE: This cannot be used on CPUs that break
on unaligned accesses to variables.
+skip_message Skip the whole message from generation.
+no_unions Generate 'oneof' fields as optional fields
+ instead of C unions.
+msgid Specifies a unique id for this message type.
+ Can be used by user code as an identifier.
============================ ================================================
These options can be defined for the .proto files before they are converted
PB_WT_32BIT = 5
} pb_wire_type_t;
+pb_extension_type_t
+-------------------
+Defines the handler functions and auxiliary data for a field that extends
+another message. Usually autogenerated by *nanopb_generator.py*::
+
+ typedef struct {
+ bool (*decode)(pb_istream_t *stream, pb_extension_t *extension,
+ uint32_t tag, pb_wire_type_t wire_type);
+ bool (*encode)(pb_ostream_t *stream, const pb_extension_t *extension);
+ const void *arg;
+ } pb_extension_type_t;
+
+In the normal case, the function pointers are *NULL* and the decoder and
+encoder use their internal implementations. The internal implementations
+assume that *arg* points to a *pb_field_t* that describes the field in question.
+
+To implement custom processing of unknown fields, you can provide pointers
+to your own functions. Their functionality is mostly the same as for normal
+callback fields, except that they get called for any unknown field when decoding.
+
+pb_extension_t
+--------------
+Ties together the extension field type and the storage for the field value::
+
+ typedef struct {
+ const pb_extension_type_t *type;
+ void *dest;
+ pb_extension_t *next;
+ } pb_extension_t;
+
+:type: Pointer to the structure that defines the callback functions.
+:dest: Pointer to the variable that stores the field value
+ (as used by the default extension callback functions.)
+:next: Pointer to the next extension handler, or *NULL*.
+
PB_GET_ERROR
------------
Get the current error message from a stream, or a placeholder string if
Normally pb_encode simply walks through the fields description array and serializes each field in turn. However, submessages must be serialized twice: first to calculate their size and then to actually write them to output. This causes some constraints for callback fields, which must return the same data on every call.
+pb_encode_delimited
+-------------------
+Calculates the length of the message, encodes it as varint and then encodes the message. ::
+
+ bool pb_encode_delimited(pb_ostream_t *stream, const pb_field_t fields[], const void *src_struct);
+
+(parameters are the same as for `pb_encode`_.)
+
+A common way to indicate the message length in Protocol Buffers is to prefix it with a varint.
+This function does this, and it is compatible with *parseDelimitedFrom* in Google's protobuf library.
+
.. sidebar:: Encoding fields manually
The functions with names *pb_encode_\** 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_encode`_ will call your callback function, which in turn will call *pb_encode_\** functions repeatedly to write out values.
For optional fields, this function applies the default value and sets *has_<field>* to false if the field is not present.
+If *PB_ENABLE_MALLOC* is defined, this function may allocate storage for any pointer type fields.
+In this case, you have to call `pb_release`_ to release the memory after you are done with the message.
+On error return `pb_decode` will release the memory itself.
+
pb_decode_noinit
----------------
Same as `pb_decode`_, except does not apply the default values to fields. ::
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.
+In addition to decoding a single message, this function can be used to merge two messages, so that
+values from previous message will remain if the new message does not contain a field.
+
+This function *will not* release the message even on error return. If you use *PB_ENABLE_MALLOC*,
+you will need to call `pb_release`_ yourself.
+
+pb_decode_delimited
+-------------------
+Same as `pb_decode`_, except that it first reads a varint with the length of the message. ::
+
+ bool pb_decode_delimited(pb_istream_t *stream, const pb_field_t fields[], void *dest_struct);
+
+(parameters are the same as for `pb_decode`_.)
+
+A common method to indicate message size in Protocol Buffers is to prefix it with a varint.
+This function is compatible with *writeDelimitedTo* in the Google's Protocol Buffers library.
+
+pb_release
+----------
+Releases any dynamically allocated fields.
+
+ void pb_release(const pb_field_t fields[], void *dest_struct);
+
+:fields: A field description array. Usually autogenerated.
+:dest_struct: Pointer to structure where data will be stored.
+
+This function is only available if *PB_ENABLE_MALLOC* is defined. It will release any
+pointer type fields in the structure and set the pointers to NULL.
+
pb_skip_varint
--------------
Skip a varint_ encoded integer without decoding it. ::