X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Freference.rst;h=7d27a5158d8056c925efa60417b7687e4427f310;hb=516a5eab2c5904b2cd39d4958b0c101bafd8e060;hp=be6567eebc17941c20ae5c04066a5d7e7ee42104;hpb=8d35488bcde1cc6d912d4c875bcf6d2745899d7d;p=apps%2Fagl-service-can-low-level.git diff --git a/docs/reference.rst b/docs/reference.rst index be6567ee..7d27a515 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -91,6 +91,7 @@ no_unions Generate 'oneof' fields as optional fields instead of C unions. msgid Specifies a unique id for this message type. Can be used by user code as an identifier. +anonymous_oneof Generate 'oneof' fields as anonymous unions. ============================ ================================================ These options can be defined for the .proto files before they are converted @@ -198,11 +199,20 @@ The options can be defined in file, message and field scopes:: pb.h ==== +pb_byte_t +--------- +Type used for storing byte-sized data, such as raw binary input and bytes-type fields. :: + + typedef uint_least8_t pb_byte_t; + +For most platforms this is equivalent to `uint8_t`. Some platforms however do not support +8-bit variables, and on those platforms 16 or 32 bits need to be used for each byte. + pb_type_t --------- -Defines the encoder/decoder behaviour that should be used for a field. :: +Type used to store the type of each field, to control the encoder/decoder behaviour. :: - 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 +258,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 +284,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 +349,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 +400,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 +412,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 +453,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 +522,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 +582,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 +592,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. @@ -628,39 +651,21 @@ This function is compatible with *writeDelimitedTo* in the Google's Protocol Buf pb_release ---------- -Releases any dynamically allocated fields. +Releases any dynamically allocated fields:: 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 will be stored. +:dest_struct: Pointer to structure where data is stored. If NULL, function does nothing. 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 +732,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.