diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/reference.rst | 47 |
1 files changed, 36 insertions, 11 deletions
diff --git a/docs/reference.rst b/docs/reference.rst index 4021c764..8846ce1b 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -283,6 +283,25 @@ Read data from input stream. Always use this function, don't try to call the str End of file is signalled by *stream->bytes_left* being zero after pb_read returns false. +pb_decode +--------- +Read and decode all fields of a structure. Reads until EOF on input stream. :: + + bool pb_decode(pb_istream_t *stream, const pb_field_t fields[], void *dest_struct); + +:stream: Input stream to read from. +:fields: A field description array. Usually autogenerated. +:dest_struct: Pointer to structure where data will be stored. +:returns: True on success, false on IO error, on detectable errors in field description, if a field encoder returns false or if a required field is missing. + +In Protocol Buffers binary format, EOF is only allowed between fields. If it happens anywhere else, pb_decode will return *false*. If pb_decode returns false, you cannot trust any of the data in the structure. + +In addition to EOF, the pb_decode implementation supports terminating a message with a 0 byte. This is compatible with the official Protocol Buffers because 0 is never a valid field tag. + +For optional fields, this function applies the default value and sets *has_<field>* to false if the field is not present. + +Because of memory concerns, the detection of missing required fields is not perfect if the structure contains more than 32 fields. + pb_decode_varint ---------------- Read and decode a varint_ encoded integer. :: @@ -311,24 +330,30 @@ Skip a varint-length-prefixed string. This means skipping a value with wire type :stream: Input stream to read from. :returns: True on success, false on IO error or length exceeding uint32_t. -pb_decode ---------- -Read and decode all fields of a structure. Reads until EOF on input stream. :: +pb_decode_tag +------------- +Decode the tag that comes before field in the protobuf encoding:: - bool pb_decode(pb_istream_t *stream, const pb_field_t fields[], void *dest_struct); + bool pb_decode_tag(pb_istream_t *stream, pb_wire_type_t *wire_type, int *tag, bool *eof); :stream: Input stream to read from. -:fields: A field description array. Usually autogenerated. -:dest_struct: Pointer to structure where data will be stored. -:returns: True on success, false on IO error, on detectable errors in field description, if a field encoder returns false or if a required field is missing. +:wire_type: Pointer to variable where to store the wire type of the field. +:tag: Pointer to variable where to store the tag of the field. +:eof: Pointer to variable where to store end-of-file status. +:returns: True on success, false on error or EOF. -In Protocol Buffers binary format, EOF is only allowed between fields. If it happens anywhere else, pb_decode will return *false*. If pb_decode returns false, you cannot trust any of the data in the structure. +When the message (stream) ends, this function will return false and set *eof* to true. On other +errors, *eof* will be set to false. -In addition to EOF, the pb_decode implementation supports terminating a message with a 0 byte. This is compatible with the official Protocol Buffers because 0 is never a valid field tag. +pb_skip_field +------------- +Remove the data for a field from the stream, without actually decoding it:: -For optional fields, this function applies the default value and sets *has_<field>* to false if the field is not present. + bool pb_skip_field(pb_istream_t *stream, pb_wire_type_t wire_type); -Because of memory concerns, the detection of missing required fields is not perfect if the structure contains more than 32 fields. +:stream: Input stream to read from. +:wire_type: Type of field to skip. +:returns: True on success, false on IO error. .. sidebar:: Field decoders |