X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Freference.rst;h=e16500ad97e777582db6f7eac0797748062a8bbb;hb=50c67ecec4895f65ba684e4b46b4b70980a5be6a;hp=6c38f6b40558be53b964fd6d202af1edfe0a60c5;hpb=b663909fb6e86f0ae0f450523e72fb7fbfb719ab;p=apps%2Fagl-service-can-low-level.git diff --git a/docs/reference.rst b/docs/reference.rst index 6c38f6b4..e16500ad 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -24,8 +24,11 @@ __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_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 @@ -73,10 +76,13 @@ The generator behaviour can be adjusted using these options, defined in the 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 @@ -84,6 +90,7 @@ long_names Prefix the enum name to the enum value in 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. ============================ ================================================ These options can be defined for the .proto files before they are converted @@ -304,6 +311,41 @@ Protocol Buffers wire types. These are used with `pb_encode_tag`_. :: 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 @@ -380,6 +422,17 @@ Encodes the contents of a structure as a protocol buffers message and writes it 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. @@ -542,6 +595,10 @@ 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. +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. :: @@ -552,6 +609,35 @@ 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. ::