docs/encoding.rst

   1 =========================
   2 Nanopb: Encoding messages
   3 =========================
   4
   5 The basic way to encode messages is to:
   6
   7 1) Write a callback function for whatever stream you want to write the message to.
   8 2) Fill a structure with your data.
   9 3) Call pb_encode with the stream, a pointer to *const pb_field_t* array and a pointer to your structure.
  10
  11 A few extra steps are necessary if you need to know the size of the message beforehand, or if you have dynamically sized fields.
  12
  13 Output streams
  14 ==============
  15
  16 This is the contents of *pb_ostream_t* structure::
  17
  18  typedef struct _pb_ostream_t pb_ostream_t;
  19  struct _pb_ostream_t
  20  {
  21     bool (*callback)(pb_ostream_t *stream, const uint8_t *buf, size_t count);
  22     void *state;
  23     size_t max_size;
  24     size_t bytes_written;
  25  };
  26
  27 This, combined with the pb_write function, provides a light-weight abstraction
  28 for whatever destination you want to write data to.
  29
  30 *callback* should be a pointer to your callback function. These are the rules for it:
  31
  32 1) Return false on IO errors. This will cause encoding to abort.
  33  *
  34  * 2) You can use state to store your own data (e.g. buffer pointer).
  35  *
  36  * 3) pb_write will update bytes_written after your callback runs.
  37  *
  38  * 4) Substreams will modify max_size and bytes_written. Don't use them to
  39  * calculate any pointers.