+Decoding callbacks
+------------------
+::
+
+ bool (*decode)(pb_istream_t *stream, const pb_field_t *field, void **arg);
+
+When decoding, the callback receives a length-limited substring that reads the contents of a single field. The field tag has already been read. For *string* and *bytes*, the length value has already been parsed, and is available at *stream->bytes_left*.
+
+The callback will be called multiple times for repeated fields. For packed fields, you can either read multiple values until the stream ends, or leave it to `pb_decode`_ to call your function over and over until all values have been read.
+
+.. _`pb_decode`: reference.html#pb-decode
+
+This callback reads multiple integers and prints them::
+
+ bool read_ints(pb_istream_t *stream, const pb_field_t *field, void **arg)
+ {
+ while (stream->bytes_left)
+ {
+ uint64_t value;
+ if (!pb_decode_varint(stream, &value))
+ return false;
+ printf("%lld\n", value);
+ }
+ return true;
+ }
+
+Field description array
+=======================
+
+For using the *pb_encode* and *pb_decode* functions, you need an array of pb_field_t constants describing the structure you wish to encode. This description is usually autogenerated from .proto file.
+
+For example this submessage in the Person.proto file::
+
+ message Person {
+ message PhoneNumber {
+ required string number = 1 [(nanopb).max_size = 40];
+ optional PhoneType type = 2 [default = HOME];
+ }
+ }
+
+generates this field description array for the structure *Person_PhoneNumber*::
+
+ const pb_field_t Person_PhoneNumber_fields[3] = {
+ PB_FIELD( 1, STRING , REQUIRED, STATIC, Person_PhoneNumber, number, number, 0),
+ PB_FIELD( 2, ENUM , OPTIONAL, STATIC, Person_PhoneNumber, type, number, &Person_PhoneNumber_type_default),
+ PB_LAST_FIELD
+ };
+
+
+Extension fields
+================
+Protocol Buffers supports a concept of `extension fields`_, which are
+additional fields to a message, but defined outside the actual message.
+The definition can even be in a completely separate .proto file.
+
+The base message is declared as extensible by keyword *extensions* in
+the .proto file::
+
+ message MyMessage {
+ .. fields ..
+ extensions 100 to 199;
+ }
+
+For each extensible message, *nanopb_generator.py* declares an additional
+callback field called *extensions*. The field and associated datatype
+*pb_extension_t* forms a linked list of handlers. When an unknown field is
+encountered, the decoder calls each handler in turn until either one of them
+handles the field, or the list is exhausted.
+
+The actual extensions are declared using the *extend* keyword in the .proto,
+and are in the global namespace::
+
+ extend MyMessage {
+ optional int32 myextension = 100;
+ }
+
+For each extension, *nanopb_generator.py* creates a constant of type
+*pb_extension_type_t*. To link together the base message and the extension,
+you have to:
+
+1. Allocate storage for your field, matching the datatype in the .proto.
+ For example, for a *int32* field, you need a *int32_t* variable to store
+ the value.
+2. Create a *pb_extension_t* constant, with pointers to your variable and
+ to the generated *pb_extension_type_t*.
+3. Set the *message.extensions* pointer to point to the *pb_extension_t*.
+
+An example of this is available in *tests/test_encode_extensions.c* and
+*tests/test_decode_extensions.c*.
+
+.. _`extension fields`: https://developers.google.com/protocol-buffers/docs/proto#extensions
+
+
+Return values and error handling
+================================
+
+Most functions in nanopb return bool: *true* means success, *false* means failure. There is also some support for error messages for debugging purposes: the error messages go in *stream->errmsg*.
+
+The error messages help in guessing what is the underlying cause of the error. The most common error conditions are:
+
+1) Running out of memory, i.e. stack overflow.
+2) Invalid field descriptors (would usually mean a bug in the generator).
+3) IO errors in your own stream callbacks.
+4) Errors that happen in your callback functions.
+5) Exceeding the max_size or bytes_left of a stream.
+6) Exceeding the max_size of a string or array field
+7) Invalid protocol buffers binary message.