diff options
| -rw-r--r-- | docs/reference.rst | 47 | ||||
| -rw-r--r-- | pb_decode.c | 52 | ||||
| -rw-r--r-- | pb_decode.h | 3 |
3 files changed, 73 insertions, 29 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 diff --git a/pb_decode.c b/pb_decode.c index eace906f..50a11c40 100644 --- a/pb_decode.c +++ b/pb_decode.c @@ -117,12 +117,33 @@ bool checkreturn pb_skip_string(pb_istream_t *stream) return pb_read(stream, NULL, length); } -/* Currently the wire type related stuff is kept hidden from - * callbacks. They shouldn't need it. It's better for performance - * to just assume the correct type and fail safely on corrupt message. - */ +bool checkreturn pb_decode_tag(pb_istream_t *stream, pb_wire_type_t *wire_type, int *tag, bool *eof) +{ + uint32_t temp; + *eof = false; + *wire_type = 0; + *tag = 0; + + if (!pb_decode_varint32(stream, &temp)) + { + if (stream->bytes_left == 0) + *eof = true; + + return false; + } + + if (temp == 0) + { + *eof = true; /* Special feature: allow 0-terminated messages. */ + return false; + } + + *tag = temp >> 3; + *wire_type = (pb_wire_type_t)(temp & 7); + return true; +} -static bool checkreturn skip(pb_istream_t *stream, pb_wire_type_t wire_type) +bool checkreturn pb_skip_field(pb_istream_t *stream, pb_wire_type_t wire_type) { switch (wire_type) { @@ -292,7 +313,7 @@ static bool checkreturn decode_field(pb_istream_t *stream, pb_wire_type_t wire_t pb_callback_t *pCallback = (pb_callback_t*)iter->pData; if (pCallback->funcs.decode == NULL) - return skip(stream, wire_type); + return pb_skip_field(stream, wire_type); if (wire_type == PB_WT_STRING) { @@ -392,27 +413,22 @@ bool checkreturn pb_decode(pb_istream_t *stream, const pb_field_t fields[], void while (stream->bytes_left) { - uint32_t temp; int tag; pb_wire_type_t wire_type; - if (!pb_decode_varint32(stream, &temp)) + bool eof; + + if (!pb_decode_tag(stream, &wire_type, &tag, &eof)) { - if (stream->bytes_left == 0) - break; /* It was EOF */ + if (eof) + break; else - return false; /* It was error */ + return false; } - if (temp == 0) - break; /* Special feature: allow 0-terminated messages. */ - - tag = temp >> 3; - wire_type = (pb_wire_type_t)(temp & 7); - if (!pb_field_find(&iter, tag)) { /* No match found, skip data */ - if (!skip(stream, wire_type)) + if (!pb_skip_field(stream, wire_type)) return false; continue; } diff --git a/pb_decode.h b/pb_decode.h index f12b1900..0abb342c 100644 --- a/pb_decode.h +++ b/pb_decode.h @@ -48,6 +48,9 @@ bool pb_decode(pb_istream_t *stream, const pb_field_t fields[], void *dest_struc * You may want to use these from your caller or callbacks. */ +bool pb_decode_tag(pb_istream_t *stream, pb_wire_type_t *wire_type, int *tag, bool *eof); +bool pb_skip_field(pb_istream_t *stream, pb_wire_type_t wire_type); + bool pb_decode_varint(pb_istream_t *stream, uint64_t *dest); bool pb_skip_varint(pb_istream_t *stream); |