summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/reference.rst29
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.