Nanopb files
Dependents: nanopb_V2 Message_generator LEX_Threaded_Programming_V3
pb_decode.h@3:67ee10c4ae98, 2019-08-19 (annotated)
- Committer:
- omatthews
- Date:
- Mon Aug 19 15:23:39 2019 +0000
- Revision:
- 3:67ee10c4ae98
- Parent:
- 2:d2c61a9be078
It works
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
intrinseca | 0:c7beea49fc91 | 1 | /* pb_decode.h: Functions to decode protocol buffers. Depends on pb_decode.c. |
omatthews | 2:d2c61a9be078 | 2 | * The main function is pb_decode. You also need an input stream, and the |
omatthews | 2:d2c61a9be078 | 3 | * field descriptions created by nanopb_generator.py. |
intrinseca | 0:c7beea49fc91 | 4 | */ |
intrinseca | 0:c7beea49fc91 | 5 | |
omatthews | 2:d2c61a9be078 | 6 | #ifndef PB_DECODE_H_INCLUDED |
omatthews | 2:d2c61a9be078 | 7 | #define PB_DECODE_H_INCLUDED |
omatthews | 2:d2c61a9be078 | 8 | |
intrinseca | 0:c7beea49fc91 | 9 | #include "pb.h" |
intrinseca | 0:c7beea49fc91 | 10 | |
intrinseca | 0:c7beea49fc91 | 11 | #ifdef __cplusplus |
intrinseca | 0:c7beea49fc91 | 12 | extern "C" { |
intrinseca | 0:c7beea49fc91 | 13 | #endif |
intrinseca | 0:c7beea49fc91 | 14 | |
omatthews | 2:d2c61a9be078 | 15 | /* Structure for defining custom input streams. You will need to provide |
omatthews | 2:d2c61a9be078 | 16 | * a callback function to read the bytes from your storage, which can be |
omatthews | 2:d2c61a9be078 | 17 | * for example a file or a network socket. |
intrinseca | 0:c7beea49fc91 | 18 | * |
omatthews | 2:d2c61a9be078 | 19 | * The callback must conform to these rules: |
omatthews | 2:d2c61a9be078 | 20 | * |
intrinseca | 0:c7beea49fc91 | 21 | * 1) Return false on IO errors. This will cause decoding to abort. |
intrinseca | 0:c7beea49fc91 | 22 | * 2) You can use state to store your own data (e.g. buffer pointer), |
omatthews | 2:d2c61a9be078 | 23 | * and rely on pb_read to verify that no-body reads past bytes_left. |
intrinseca | 0:c7beea49fc91 | 24 | * 3) Your callback may be used with substreams, in which case bytes_left |
omatthews | 2:d2c61a9be078 | 25 | * is different than from the main stream. Don't use bytes_left to compute |
omatthews | 2:d2c61a9be078 | 26 | * any pointers. |
intrinseca | 0:c7beea49fc91 | 27 | */ |
omatthews | 2:d2c61a9be078 | 28 | struct pb_istream_s |
intrinseca | 0:c7beea49fc91 | 29 | { |
intrinseca | 0:c7beea49fc91 | 30 | #ifdef PB_BUFFER_ONLY |
intrinseca | 0:c7beea49fc91 | 31 | /* Callback pointer is not used in buffer-only configuration. |
intrinseca | 0:c7beea49fc91 | 32 | * Having an int pointer here allows binary compatibility but |
intrinseca | 0:c7beea49fc91 | 33 | * gives an error if someone tries to assign callback function. |
intrinseca | 0:c7beea49fc91 | 34 | */ |
intrinseca | 0:c7beea49fc91 | 35 | int *callback; |
intrinseca | 0:c7beea49fc91 | 36 | #else |
omatthews | 2:d2c61a9be078 | 37 | bool (*callback)(pb_istream_t *stream, pb_byte_t *buf, size_t count); |
intrinseca | 0:c7beea49fc91 | 38 | #endif |
intrinseca | 0:c7beea49fc91 | 39 | |
intrinseca | 0:c7beea49fc91 | 40 | void *state; /* Free field for use by callback implementation */ |
intrinseca | 0:c7beea49fc91 | 41 | size_t bytes_left; |
intrinseca | 0:c7beea49fc91 | 42 | |
intrinseca | 0:c7beea49fc91 | 43 | #ifndef PB_NO_ERRMSG |
intrinseca | 0:c7beea49fc91 | 44 | const char *errmsg; |
intrinseca | 0:c7beea49fc91 | 45 | #endif |
intrinseca | 0:c7beea49fc91 | 46 | }; |
intrinseca | 0:c7beea49fc91 | 47 | |
omatthews | 2:d2c61a9be078 | 48 | /*************************** |
omatthews | 2:d2c61a9be078 | 49 | * Main decoding functions * |
omatthews | 2:d2c61a9be078 | 50 | ***************************/ |
omatthews | 2:d2c61a9be078 | 51 | |
omatthews | 2:d2c61a9be078 | 52 | /* Decode a single protocol buffers message from input stream into a C structure. |
intrinseca | 0:c7beea49fc91 | 53 | * Returns true on success, false on any failure. |
intrinseca | 0:c7beea49fc91 | 54 | * The actual struct pointed to by dest must match the description in fields. |
omatthews | 2:d2c61a9be078 | 55 | * Callback fields of the destination structure must be initialized by caller. |
omatthews | 2:d2c61a9be078 | 56 | * All other fields will be initialized by this function. |
omatthews | 2:d2c61a9be078 | 57 | * |
omatthews | 2:d2c61a9be078 | 58 | * Example usage: |
omatthews | 2:d2c61a9be078 | 59 | * MyMessage msg = {}; |
omatthews | 2:d2c61a9be078 | 60 | * uint8_t buffer[64]; |
omatthews | 2:d2c61a9be078 | 61 | * pb_istream_t stream; |
omatthews | 2:d2c61a9be078 | 62 | * |
omatthews | 2:d2c61a9be078 | 63 | * // ... read some data into buffer ... |
omatthews | 2:d2c61a9be078 | 64 | * |
omatthews | 2:d2c61a9be078 | 65 | * stream = pb_istream_from_buffer(buffer, count); |
omatthews | 2:d2c61a9be078 | 66 | * pb_decode(&stream, MyMessage_fields, &msg); |
intrinseca | 0:c7beea49fc91 | 67 | */ |
intrinseca | 0:c7beea49fc91 | 68 | bool pb_decode(pb_istream_t *stream, const pb_field_t fields[], void *dest_struct); |
intrinseca | 0:c7beea49fc91 | 69 | |
intrinseca | 0:c7beea49fc91 | 70 | /* Same as pb_decode, except does not initialize the destination structure |
intrinseca | 0:c7beea49fc91 | 71 | * to default values. This is slightly faster if you need no default values |
intrinseca | 0:c7beea49fc91 | 72 | * and just do memset(struct, 0, sizeof(struct)) yourself. |
omatthews | 2:d2c61a9be078 | 73 | * |
omatthews | 2:d2c61a9be078 | 74 | * This can also be used for 'merging' two messages, i.e. update only the |
omatthews | 2:d2c61a9be078 | 75 | * fields that exist in the new message. |
omatthews | 2:d2c61a9be078 | 76 | * |
omatthews | 2:d2c61a9be078 | 77 | * Note: If this function returns with an error, it will not release any |
omatthews | 2:d2c61a9be078 | 78 | * dynamically allocated fields. You will need to call pb_release() yourself. |
intrinseca | 0:c7beea49fc91 | 79 | */ |
intrinseca | 0:c7beea49fc91 | 80 | bool pb_decode_noinit(pb_istream_t *stream, const pb_field_t fields[], void *dest_struct); |
intrinseca | 0:c7beea49fc91 | 81 | |
omatthews | 2:d2c61a9be078 | 82 | /* Same as pb_decode, except expects the stream to start with the message size |
omatthews | 2:d2c61a9be078 | 83 | * encoded as varint. Corresponds to parseDelimitedFrom() in Google's |
omatthews | 2:d2c61a9be078 | 84 | * protobuf API. |
omatthews | 2:d2c61a9be078 | 85 | */ |
omatthews | 2:d2c61a9be078 | 86 | bool pb_decode_delimited(pb_istream_t *stream, const pb_field_t fields[], void *dest_struct); |
omatthews | 2:d2c61a9be078 | 87 | |
omatthews | 2:d2c61a9be078 | 88 | /* Same as pb_decode_delimited, except that it does not initialize the destination structure. |
omatthews | 2:d2c61a9be078 | 89 | * See pb_decode_noinit |
omatthews | 2:d2c61a9be078 | 90 | */ |
omatthews | 2:d2c61a9be078 | 91 | bool pb_decode_delimited_noinit(pb_istream_t *stream, const pb_field_t fields[], void *dest_struct); |
omatthews | 2:d2c61a9be078 | 92 | |
omatthews | 2:d2c61a9be078 | 93 | /* Same as pb_decode, except allows the message to be terminated with a null byte. |
omatthews | 2:d2c61a9be078 | 94 | * NOTE: Until nanopb-0.4.0, pb_decode() also allows null-termination. This behaviour |
omatthews | 2:d2c61a9be078 | 95 | * is not supported in most other protobuf implementations, so pb_decode_delimited() |
omatthews | 2:d2c61a9be078 | 96 | * is a better option for compatibility. |
omatthews | 2:d2c61a9be078 | 97 | */ |
omatthews | 2:d2c61a9be078 | 98 | bool pb_decode_nullterminated(pb_istream_t *stream, const pb_field_t fields[], void *dest_struct); |
omatthews | 2:d2c61a9be078 | 99 | |
omatthews | 2:d2c61a9be078 | 100 | #ifdef PB_ENABLE_MALLOC |
omatthews | 2:d2c61a9be078 | 101 | /* Release any allocated pointer fields. If you use dynamic allocation, you should |
omatthews | 2:d2c61a9be078 | 102 | * call this for any successfully decoded message when you are done with it. If |
omatthews | 2:d2c61a9be078 | 103 | * pb_decode() returns with an error, the message is already released. |
intrinseca | 0:c7beea49fc91 | 104 | */ |
omatthews | 2:d2c61a9be078 | 105 | void pb_release(const pb_field_t fields[], void *dest_struct); |
omatthews | 2:d2c61a9be078 | 106 | #endif |
omatthews | 2:d2c61a9be078 | 107 | |
omatthews | 2:d2c61a9be078 | 108 | |
omatthews | 2:d2c61a9be078 | 109 | /************************************** |
omatthews | 2:d2c61a9be078 | 110 | * Functions for manipulating streams * |
omatthews | 2:d2c61a9be078 | 111 | **************************************/ |
omatthews | 2:d2c61a9be078 | 112 | |
omatthews | 2:d2c61a9be078 | 113 | /* Create an input stream for reading from a memory buffer. |
omatthews | 2:d2c61a9be078 | 114 | * |
omatthews | 2:d2c61a9be078 | 115 | * Alternatively, you can use a custom stream that reads directly from e.g. |
omatthews | 2:d2c61a9be078 | 116 | * a file or a network socket. |
omatthews | 2:d2c61a9be078 | 117 | */ |
omatthews | 2:d2c61a9be078 | 118 | pb_istream_t pb_istream_from_buffer(const pb_byte_t *buf, size_t bufsize); |
omatthews | 2:d2c61a9be078 | 119 | |
omatthews | 2:d2c61a9be078 | 120 | /* Function to read from a pb_istream_t. You can use this if you need to |
omatthews | 2:d2c61a9be078 | 121 | * read some custom header data, or to read data in field callbacks. |
omatthews | 2:d2c61a9be078 | 122 | */ |
omatthews | 2:d2c61a9be078 | 123 | bool pb_read(pb_istream_t *stream, pb_byte_t *buf, size_t count); |
omatthews | 2:d2c61a9be078 | 124 | |
omatthews | 2:d2c61a9be078 | 125 | |
omatthews | 2:d2c61a9be078 | 126 | /************************************************ |
omatthews | 2:d2c61a9be078 | 127 | * Helper functions for writing field callbacks * |
omatthews | 2:d2c61a9be078 | 128 | ************************************************/ |
intrinseca | 0:c7beea49fc91 | 129 | |
intrinseca | 0:c7beea49fc91 | 130 | /* Decode the tag for the next field in the stream. Gives the wire type and |
intrinseca | 0:c7beea49fc91 | 131 | * field tag. At end of the message, returns false and sets eof to true. */ |
intrinseca | 0:c7beea49fc91 | 132 | bool pb_decode_tag(pb_istream_t *stream, pb_wire_type_t *wire_type, uint32_t *tag, bool *eof); |
intrinseca | 0:c7beea49fc91 | 133 | |
intrinseca | 0:c7beea49fc91 | 134 | /* Skip the field payload data, given the wire type. */ |
intrinseca | 0:c7beea49fc91 | 135 | bool pb_skip_field(pb_istream_t *stream, pb_wire_type_t wire_type); |
intrinseca | 0:c7beea49fc91 | 136 | |
intrinseca | 0:c7beea49fc91 | 137 | /* Decode an integer in the varint format. This works for bool, enum, int32, |
intrinseca | 0:c7beea49fc91 | 138 | * int64, uint32 and uint64 field types. */ |
omatthews | 2:d2c61a9be078 | 139 | #ifndef PB_WITHOUT_64BIT |
intrinseca | 0:c7beea49fc91 | 140 | bool pb_decode_varint(pb_istream_t *stream, uint64_t *dest); |
omatthews | 2:d2c61a9be078 | 141 | #else |
omatthews | 2:d2c61a9be078 | 142 | #define pb_decode_varint pb_decode_varint32 |
omatthews | 2:d2c61a9be078 | 143 | #endif |
omatthews | 2:d2c61a9be078 | 144 | |
omatthews | 2:d2c61a9be078 | 145 | /* Decode an integer in the varint format. This works for bool, enum, int32, |
omatthews | 2:d2c61a9be078 | 146 | * and uint32 field types. */ |
omatthews | 2:d2c61a9be078 | 147 | bool pb_decode_varint32(pb_istream_t *stream, uint32_t *dest); |
intrinseca | 0:c7beea49fc91 | 148 | |
intrinseca | 0:c7beea49fc91 | 149 | /* Decode an integer in the zig-zagged svarint format. This works for sint32 |
intrinseca | 0:c7beea49fc91 | 150 | * and sint64. */ |
omatthews | 2:d2c61a9be078 | 151 | #ifndef PB_WITHOUT_64BIT |
intrinseca | 0:c7beea49fc91 | 152 | bool pb_decode_svarint(pb_istream_t *stream, int64_t *dest); |
omatthews | 2:d2c61a9be078 | 153 | #else |
omatthews | 2:d2c61a9be078 | 154 | bool pb_decode_svarint(pb_istream_t *stream, int32_t *dest); |
omatthews | 2:d2c61a9be078 | 155 | #endif |
intrinseca | 0:c7beea49fc91 | 156 | |
intrinseca | 0:c7beea49fc91 | 157 | /* Decode a fixed32, sfixed32 or float value. You need to pass a pointer to |
intrinseca | 0:c7beea49fc91 | 158 | * a 4-byte wide C variable. */ |
intrinseca | 0:c7beea49fc91 | 159 | bool pb_decode_fixed32(pb_istream_t *stream, void *dest); |
intrinseca | 0:c7beea49fc91 | 160 | |
omatthews | 2:d2c61a9be078 | 161 | #ifndef PB_WITHOUT_64BIT |
intrinseca | 0:c7beea49fc91 | 162 | /* Decode a fixed64, sfixed64 or double value. You need to pass a pointer to |
intrinseca | 0:c7beea49fc91 | 163 | * a 8-byte wide C variable. */ |
intrinseca | 0:c7beea49fc91 | 164 | bool pb_decode_fixed64(pb_istream_t *stream, void *dest); |
omatthews | 2:d2c61a9be078 | 165 | #endif |
intrinseca | 0:c7beea49fc91 | 166 | |
intrinseca | 0:c7beea49fc91 | 167 | /* Make a limited-length substream for reading a PB_WT_STRING field. */ |
intrinseca | 0:c7beea49fc91 | 168 | bool pb_make_string_substream(pb_istream_t *stream, pb_istream_t *substream); |
omatthews | 2:d2c61a9be078 | 169 | bool pb_close_string_substream(pb_istream_t *stream, pb_istream_t *substream); |
intrinseca | 0:c7beea49fc91 | 170 | |
intrinseca | 0:c7beea49fc91 | 171 | #ifdef __cplusplus |
intrinseca | 0:c7beea49fc91 | 172 | } /* extern "C" */ |
intrinseca | 0:c7beea49fc91 | 173 | #endif |
intrinseca | 0:c7beea49fc91 | 174 | |
omatthews | 2:d2c61a9be078 | 175 | #endif |