diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/reference.rst | 29 |
1 files changed, 24 insertions, 5 deletions
diff --git a/docs/reference.rst b/docs/reference.rst index d67499e1..31f4e9fd 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -376,7 +376,12 @@ Because of memory concerns, the detection of missing required fields is not perf Each field decoder reads and decodes a single value. For arrays, the decoder is called repeatedly. - 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 most of the 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*. + 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. + + 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. pb_dec_varint ------------- @@ -403,12 +408,12 @@ pb_dec_fixed32 -------------- Field decoder for PB_LTYPE_FIXED32. :: - bool pb_dec_fixed(pb_istream_t *stream, const pb_field_t *field, void *dest); + bool pb_dec_fixed32(pb_istream_t *stream, const pb_field_t *field, void *dest); -:stream: Input stream to read from. 1-10 bytes will be read. +:stream: Input stream to read from. 4 bytes will be read. :field: Not used. -: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. +:dest: Pointer to destination *int32_t*, *uint32_t* or *float*. +:returns: True on success, false on IO errors. This function reads 4 bytes from the input stream. On big endian architectures, it then reverses the order of the bytes. @@ -420,6 +425,11 @@ Field decoder for PB_LTYPE_FIXED64. :: bool pb_dec_fixed(pb_istream_t *stream, const pb_field_t *field, void *dest); +:stream: Input stream to read from. 8 bytes will be read. +:field: Not used. +: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 @@ -428,6 +438,9 @@ 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. @@ -441,6 +454,9 @@ 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); +**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*. @@ -454,6 +470,9 @@ Field decoder for PB_LTYPE_SUBMESSAGE. Calls `pb_decode`_ to perform the actual 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. |