Merge pull request #196 from mxk/api-ref

Update API reference to match headers

1 files changed, 32 insertions, 38 deletions

diff --git a/docs/reference.rst b/docs/reference.rst
index 6968c81b..372450be 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -202,7 +202,7 @@ pb_type_t
 ---------
 Defines the encoder/decoder behaviour that should be used for a field. ::
 
-    typedef uint8_t pb_type_t;
+    typedef uint_least8_t pb_type_t;
 
 The low-order nibble of the enumeration values defines the function that can be used for encoding and decoding the field data:
 
@@ -248,14 +248,14 @@ pb_field_t
 ----------
 Describes a single structure field with memory position in relation to others. The descriptions are usually autogenerated. ::
 
-    typedef struct _pb_field_t pb_field_t;
-    struct _pb_field_t {
-        uint8_t tag;
+    typedef struct pb_field_s pb_field_t;
+    struct pb_field_s {
+        pb_size_t tag;
         pb_type_t type;
-        uint8_t data_offset;
-        int8_t size_offset;
-        uint8_t data_size;
-        uint8_t array_size;
+        pb_size_t data_offset;
+        pb_ssize_t size_offset;
+        pb_size_t data_size;
+        pb_size_t array_size;
         const void *ptr;
     } pb_packed;
 
@@ -274,8 +274,8 @@ pb_bytes_array_t
 An byte array with a field for storing the length::
 
     typedef struct {
-        size_t size;
-        uint8_t bytes[1];
+        pb_size_t size;
+        pb_byte_t bytes[1];
     } pb_bytes_array_t;
 
 In an actual array, the length of *bytes* may be different.
@@ -339,12 +339,14 @@ Ties together the extension field type and the storage for the field value::
         const pb_extension_type_t *type;
         void *dest;
         pb_extension_t *next;
+        bool found;
     } pb_extension_t;
 
 :type:      Pointer to the structure that defines the callback functions.
 :dest:      Pointer to the variable that stores the field value
             (as used by the default extension callback functions.)
 :next:      Pointer to the next extension handler, or *NULL*.
+:found:     Decoder sets this to true if the extension was found.
 
 PB_GET_ERROR
 ------------
@@ -388,7 +390,7 @@ pb_ostream_from_buffer
 ----------------------
 Constructs an output stream for writing into a memory buffer. This is just a helper function, it doesn't do anything you couldn't do yourself in a callback function. It uses an internal callback that stores the pointer in stream *state* field. ::
 
-    pb_ostream_t pb_ostream_from_buffer(uint8_t *buf, size_t bufsize);
+    pb_ostream_t pb_ostream_from_buffer(pb_byte_t *buf, size_t bufsize);
 
 :buf:           Memory buffer to write into.
 :bufsize:       Maximum number of bytes to write.
@@ -400,7 +402,7 @@ pb_write
 --------
 Writes data to an output stream. Always use this function, instead of trying to call stream callback manually. ::
 
-    bool pb_write(pb_ostream_t *stream, const uint8_t *buf, size_t count);
+    bool pb_write(pb_ostream_t *stream, const pb_byte_t *buf, size_t count);
 
 :stream:        Output stream to write to.
 :buf:           Pointer to buffer with the data to be written.
@@ -441,11 +443,22 @@ This function does this, and it is compatible with *parseDelimitedFrom* in Googl
 
     Writing packed arrays is a little bit more involved: you need to use `pb_encode_tag` and specify `PB_WT_STRING` as the wire type. Then you need to know exactly how much data you are going to write, and use `pb_encode_varint`_ to write out the number of bytes before writing the actual data. Substreams can be used to determine the number of bytes beforehand; see `pb_encode_submessage`_ source code for an example.
 
+pb_get_encoded_size
+-------------------
+Calculates the length of the encoded message. ::
+
+    bool pb_get_encoded_size(size_t *size, const pb_field_t fields[], const void *src_struct);
+
+:size:          Calculated size of the encoded message.
+:fields:        A field description array, usually autogenerated.
+:src_struct:    Pointer to the data that will be serialized.
+:returns:       True on success, false on detectable errors in field description or if a field encoder returns false.
+
 pb_encode_tag
 -------------
 Starts a field in the Protocol Buffers binary format: encodes the field number and the wire type of the data. ::
 
-    bool pb_encode_tag(pb_ostream_t *stream, pb_wire_type_t wiretype, int field_number);
+    bool pb_encode_tag(pb_ostream_t *stream, pb_wire_type_t wiretype, uint32_t field_number);
 
 :stream:        Output stream to write to. 1-5 bytes will be written.
 :wiretype:      PB_WT_VARINT, PB_WT_64BIT, PB_WT_STRING or PB_WT_32BIT
@@ -499,7 +512,7 @@ pb_encode_string
 ----------------
 Writes the length of a string as varint and then contents of the string. Works for fields of type `bytes` and `string`::
 
-    bool pb_encode_string(pb_ostream_t *stream, const uint8_t *buffer, size_t size);
+    bool pb_encode_string(pb_ostream_t *stream, const pb_byte_t *buffer, size_t size);
 
 :stream:        Output stream to write to.
 :buffer:        Pointer to string data.
@@ -559,7 +572,7 @@ pb_istream_from_buffer
 ----------------------
 Helper function for creating an input stream that reads data from a memory buffer. ::
 
-    pb_istream_t pb_istream_from_buffer(uint8_t *buf, size_t bufsize);
+    pb_istream_t pb_istream_from_buffer(const pb_byte_t *buf, size_t bufsize);
 
 :buf:           Pointer to byte array to read from.
 :bufsize:       Size of the byte array.
@@ -569,7 +582,7 @@ pb_read
 -------
 Read data from input stream. Always use this function, don't try to call the stream callback directly. ::
 
-    bool pb_read(pb_istream_t *stream, uint8_t *buf, size_t count);
+    bool pb_read(pb_istream_t *stream, pb_byte_t *buf, size_t count);
 
 :stream:        Input stream to read from.
 :buf:           Buffer to store the data to, or NULL to just read data without storing it anywhere.
@@ -630,7 +643,7 @@ pb_release
 ----------
 Releases any dynamically allocated fields.
 
-    void pb_release(const pb_field_t fields[], void \*dest_struct);
+    void pb_release(const pb_field_t fields[], void *dest_struct);
 
 :fields:        A field description array. Usually autogenerated.
 :dest_struct:   Pointer to structure where data is stored. If NULL, function does nothing.
@@ -638,29 +651,11 @@ Releases any dynamically allocated fields.
 This function is only available if *PB_ENABLE_MALLOC* is defined. It will release any
 pointer type fields in the structure and set the pointers to NULL.
 
-pb_skip_varint
---------------
-Skip a varint_ encoded integer without decoding it. ::
-
-    bool pb_skip_varint(pb_istream_t *stream);
-
-:stream:        Input stream to read from. Will read 1 byte at a time until the MSB is clear.
-:returns:       True on success, false on IO error.
-
-pb_skip_string
---------------
-Skip a varint-length-prefixed string. This means skipping a value with wire type PB_WT_STRING. ::
-
-    bool pb_skip_string(pb_istream_t *stream);
-
-:stream:        Input stream to read from.
-:returns:       True on success, false on IO error or length exceeding uint32_t.
-
 pb_decode_tag
 -------------
 Decode the tag that comes before field in the protobuf encoding::
 
-    bool pb_decode_tag(pb_istream_t *stream, pb_wire_type_t *wire_type, int *tag, bool *eof);
+    bool pb_decode_tag(pb_istream_t *stream, pb_wire_type_t *wire_type, uint32_t *tag, bool *eof);
 
 :stream:        Input stream to read from.
 :wire_type:     Pointer to variable where to store the wire type of the field.
@@ -727,10 +722,9 @@ pb_decode_fixed64
 -----------------
 Decode a *fixed64*, *sfixed64* or *double* value. ::
 
-    bool pb_dec_fixed(pb_istream_t *stream, const pb_field_t *field, void *dest);
+    bool pb_decode_fixed64(pb_istream_t *stream, 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.