Publishing nanopb-0.1.7

[apps/agl-service-can-low-level.git] / docs / concepts.rst

diff --git a/docs/concepts.rst b/docs/concepts.rst
index 122d29c..b18c505 100644 (file)
--- a/docs/concepts.rst
+++ b/docs/concepts.rst
@@ -38,6 +38,20 @@ This file, in turn, requires the file *google/protobuf/descriptor.proto*. This i
 
     protoc -I/usr/include -Inanopb/generator -I. -omessage.pb message.proto
 
+The options can be defined in file, message and field scopes::
+
+    option (nanopb_fileopt).max_size = 20; // File scope
+    message Message
+    {
+        option (nanopb_msgopt).max_size = 30; // Message scope
+        required string fieldsize = 1 [(nanopb).max_size = 40]; // Field scope
+    }
+
+It is also possible to give the options on command line, but then they will affect the whole file. For example::
+
+    user@host:~$ python ../generator/nanopb_generator.py -s 'max_size: 20' message.pb
+
+
 Streams
 =======
 
@@ -50,6 +64,7 @@ There are a few generic rules for callback functions:
 #) Use state to store your own data, such as a file descriptor.
 #) *bytes_written* and *bytes_left* are updated by pb_write and pb_read.
 #) Your callback may be used with substreams. In this case *bytes_left*, *bytes_written* and *max_size* have smaller values than the original stream. Don't use these values to calculate pointers.
+#) Always read or write the full requested length of data. For example, POSIX *recv()* needs the *MSG_WAITALL* parameter to accomplish this.
 
 Output streams
 --------------
@@ -91,9 +106,8 @@ Writing to stdout::
 
 Input streams
 -------------
-For input streams, there are a few extra rules:
+For input streams, there is one extra rule:
 
-#) If buf is NULL, read from stream but don't store the data. This is used to skip unknown input.
 #) You don't need to know the length of the message in advance. After getting EOF error when reading, set bytes_left to 0 and return false. Pb_decode will detect this and if the EOF was in a proper position, it will return true.
 
 Here is the structure::