summaryrefslogtreecommitdiffstats
path: root/docs/encoding.rst
diff options
context:
space:
mode:
authorPetteri Aimonen <jpa@npb.mail.kapsi.fi>2011-08-14 20:11:05 +0000
committerPetteri Aimonen <jpa@npb.mail.kapsi.fi>2011-08-14 20:11:05 +0000
commit842d52633d650286ce62490362f8dfa356e17800 (patch)
tree6597bc4dc16ac13d129901fd42e76fb776e86a7d /docs/encoding.rst
parent6dfba365b00175eae7e8b83aaf5d29ce190fd9eb (diff)
More documentation, small improvements
git-svn-id: https://svn.kapsi.fi/jpa/nanopb@955 e3a754e5-d11d-0410-8d38-ebb782a927b9
Diffstat (limited to 'docs/encoding.rst')
-rw-r--r--docs/encoding.rst31
1 files changed, 5 insertions, 26 deletions
diff --git a/docs/encoding.rst b/docs/encoding.rst
index e4e0cd7f..3f673f35 100644
--- a/docs/encoding.rst
+++ b/docs/encoding.rst
@@ -4,36 +4,15 @@ Nanopb: Encoding messages
The basic way to encode messages is to:
-1) Write a callback function for whatever stream you want to write the message to.
+1) Create an `output stream`_.
2) Fill a structure with your data.
-3) Call pb_encode with the stream, a pointer to *const pb_field_t* array and a pointer to your structure.
+3) Call *pb_encode* with the stream, a pointer to *const pb_field_t* array and a pointer to your structure.
A few extra steps are necessary if you need to know the size of the message beforehand, or if you have dynamically sized fields.
-Output streams
-==============
+.. _`output stream`: concepts.html#output-streams
-This is the contents of *pb_ostream_t* structure::
+Function: pb_encode
+===================
- typedef struct _pb_ostream_t pb_ostream_t;
- struct _pb_ostream_t
- {
- bool (*callback)(pb_ostream_t *stream, const uint8_t *buf, size_t count);
- void *state;
- size_t max_size;
- size_t bytes_written;
- };
-This, combined with the pb_write function, provides a light-weight abstraction
-for whatever destination you want to write data to.
-
-*callback* should be a pointer to your callback function. These are the rules for it:
-
-1) Return false on IO errors. This will cause encoding to abort.
- *
- * 2) You can use state to store your own data (e.g. buffer pointer).
- *
- * 3) pb_write will update bytes_written after your callback runs.
- *
- * 4) Substreams will modify max_size and bytes_written. Don't use them to
- * calculate any pointers. \ No newline at end of file