Nanopb files
Dependents: nanopb_V2 Message_generator LEX_Threaded_Programming_V3
pb_encode.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_encode.h: Functions to encode protocol buffers. Depends on pb_encode.c. |
omatthews | 2:d2c61a9be078 | 2 | * The main function is pb_encode. You also need an output 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_ENCODE_H_INCLUDED |
omatthews | 2:d2c61a9be078 | 7 | #define PB_ENCODE_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 output streams. You will need to provide |
omatthews | 2:d2c61a9be078 | 16 | * a callback function to write the bytes to 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 encoding to abort. |
intrinseca | 0:c7beea49fc91 | 22 | * 2) You can use state to store your own data (e.g. buffer pointer). |
intrinseca | 0:c7beea49fc91 | 23 | * 3) pb_write will update bytes_written after your callback runs. |
omatthews | 2:d2c61a9be078 | 24 | * 4) Substreams will modify max_size and bytes_written. Don't use them |
omatthews | 2:d2c61a9be078 | 25 | * to calculate any pointers. |
intrinseca | 0:c7beea49fc91 | 26 | */ |
omatthews | 2:d2c61a9be078 | 27 | struct pb_ostream_s |
intrinseca | 0:c7beea49fc91 | 28 | { |
intrinseca | 0:c7beea49fc91 | 29 | #ifdef PB_BUFFER_ONLY |
intrinseca | 0:c7beea49fc91 | 30 | /* Callback pointer is not used in buffer-only configuration. |
intrinseca | 0:c7beea49fc91 | 31 | * Having an int pointer here allows binary compatibility but |
intrinseca | 0:c7beea49fc91 | 32 | * gives an error if someone tries to assign callback function. |
intrinseca | 0:c7beea49fc91 | 33 | * Also, NULL pointer marks a 'sizing stream' that does not |
intrinseca | 0:c7beea49fc91 | 34 | * write anything. |
intrinseca | 0:c7beea49fc91 | 35 | */ |
intrinseca | 0:c7beea49fc91 | 36 | int *callback; |
intrinseca | 0:c7beea49fc91 | 37 | #else |
omatthews | 2:d2c61a9be078 | 38 | bool (*callback)(pb_ostream_t *stream, const pb_byte_t *buf, size_t count); |
intrinseca | 0:c7beea49fc91 | 39 | #endif |
omatthews | 2:d2c61a9be078 | 40 | void *state; /* Free field for use by callback implementation. */ |
omatthews | 2:d2c61a9be078 | 41 | size_t max_size; /* Limit number of output bytes written (or use SIZE_MAX). */ |
omatthews | 2:d2c61a9be078 | 42 | size_t bytes_written; /* Number of bytes written so far. */ |
omatthews | 2:d2c61a9be078 | 43 | |
omatthews | 2:d2c61a9be078 | 44 | #ifndef PB_NO_ERRMSG |
omatthews | 2:d2c61a9be078 | 45 | const char *errmsg; |
omatthews | 2:d2c61a9be078 | 46 | #endif |
intrinseca | 0:c7beea49fc91 | 47 | }; |
intrinseca | 0:c7beea49fc91 | 48 | |
omatthews | 2:d2c61a9be078 | 49 | /*************************** |
omatthews | 2:d2c61a9be078 | 50 | * Main encoding functions * |
omatthews | 2:d2c61a9be078 | 51 | ***************************/ |
intrinseca | 0:c7beea49fc91 | 52 | |
omatthews | 2:d2c61a9be078 | 53 | /* Encode a single protocol buffers message from C structure into a stream. |
intrinseca | 0:c7beea49fc91 | 54 | * Returns true on success, false on any failure. |
intrinseca | 0:c7beea49fc91 | 55 | * The actual struct pointed to by src_struct must match the description in fields. |
intrinseca | 0:c7beea49fc91 | 56 | * All required fields in the struct are assumed to have been filled in. |
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_ostream_t stream; |
omatthews | 2:d2c61a9be078 | 62 | * |
omatthews | 2:d2c61a9be078 | 63 | * msg.field1 = 42; |
omatthews | 2:d2c61a9be078 | 64 | * stream = pb_ostream_from_buffer(buffer, sizeof(buffer)); |
omatthews | 2:d2c61a9be078 | 65 | * pb_encode(&stream, MyMessage_fields, &msg); |
intrinseca | 0:c7beea49fc91 | 66 | */ |
intrinseca | 0:c7beea49fc91 | 67 | bool pb_encode(pb_ostream_t *stream, const pb_field_t fields[], const void *src_struct); |
intrinseca | 0:c7beea49fc91 | 68 | |
omatthews | 2:d2c61a9be078 | 69 | /* Same as pb_encode, but prepends the length of the message as a varint. |
omatthews | 2:d2c61a9be078 | 70 | * Corresponds to writeDelimitedTo() in Google's protobuf API. |
omatthews | 2:d2c61a9be078 | 71 | */ |
omatthews | 2:d2c61a9be078 | 72 | bool pb_encode_delimited(pb_ostream_t *stream, const pb_field_t fields[], const void *src_struct); |
omatthews | 2:d2c61a9be078 | 73 | |
omatthews | 2:d2c61a9be078 | 74 | /* Same as pb_encode, but appends a null byte to the message for termination. |
omatthews | 2:d2c61a9be078 | 75 | * NOTE: This behaviour is not supported in most other protobuf implementations, so pb_encode_delimited() |
omatthews | 2:d2c61a9be078 | 76 | * is a better option for compatibility. |
omatthews | 2:d2c61a9be078 | 77 | */ |
omatthews | 2:d2c61a9be078 | 78 | bool pb_encode_nullterminated(pb_ostream_t *stream, const pb_field_t fields[], const void *src_struct); |
omatthews | 2:d2c61a9be078 | 79 | |
omatthews | 2:d2c61a9be078 | 80 | /* Encode the message to get the size of the encoded data, but do not store |
omatthews | 2:d2c61a9be078 | 81 | * the data. */ |
omatthews | 2:d2c61a9be078 | 82 | bool pb_get_encoded_size(size_t *size, const pb_field_t fields[], const void *src_struct); |
omatthews | 2:d2c61a9be078 | 83 | |
omatthews | 2:d2c61a9be078 | 84 | /************************************** |
omatthews | 2:d2c61a9be078 | 85 | * Functions for manipulating streams * |
omatthews | 2:d2c61a9be078 | 86 | **************************************/ |
omatthews | 2:d2c61a9be078 | 87 | |
omatthews | 2:d2c61a9be078 | 88 | /* Create an output stream for writing into a memory buffer. |
omatthews | 2:d2c61a9be078 | 89 | * The number of bytes written can be found in stream.bytes_written after |
omatthews | 2:d2c61a9be078 | 90 | * encoding the message. |
omatthews | 2:d2c61a9be078 | 91 | * |
omatthews | 2:d2c61a9be078 | 92 | * Alternatively, you can use a custom stream that writes directly to e.g. |
omatthews | 2:d2c61a9be078 | 93 | * a file or a network socket. |
intrinseca | 0:c7beea49fc91 | 94 | */ |
omatthews | 2:d2c61a9be078 | 95 | pb_ostream_t pb_ostream_from_buffer(pb_byte_t *buf, size_t bufsize); |
intrinseca | 0:c7beea49fc91 | 96 | |
omatthews | 2:d2c61a9be078 | 97 | /* Pseudo-stream for measuring the size of a message without actually storing |
omatthews | 2:d2c61a9be078 | 98 | * the encoded data. |
omatthews | 2:d2c61a9be078 | 99 | * |
omatthews | 2:d2c61a9be078 | 100 | * Example usage: |
omatthews | 2:d2c61a9be078 | 101 | * MyMessage msg = {}; |
omatthews | 2:d2c61a9be078 | 102 | * pb_ostream_t stream = PB_OSTREAM_SIZING; |
omatthews | 2:d2c61a9be078 | 103 | * pb_encode(&stream, MyMessage_fields, &msg); |
omatthews | 2:d2c61a9be078 | 104 | * printf("Message size is %d\n", stream.bytes_written); |
omatthews | 2:d2c61a9be078 | 105 | */ |
omatthews | 2:d2c61a9be078 | 106 | #ifndef PB_NO_ERRMSG |
omatthews | 2:d2c61a9be078 | 107 | #define PB_OSTREAM_SIZING {0,0,0,0,0} |
omatthews | 2:d2c61a9be078 | 108 | #else |
omatthews | 2:d2c61a9be078 | 109 | #define PB_OSTREAM_SIZING {0,0,0,0} |
omatthews | 2:d2c61a9be078 | 110 | #endif |
omatthews | 2:d2c61a9be078 | 111 | |
omatthews | 2:d2c61a9be078 | 112 | /* Function to write into a pb_ostream_t stream. You can use this if you need |
omatthews | 2:d2c61a9be078 | 113 | * to append or prepend some custom headers to the message. |
omatthews | 2:d2c61a9be078 | 114 | */ |
omatthews | 2:d2c61a9be078 | 115 | bool pb_write(pb_ostream_t *stream, const pb_byte_t *buf, size_t count); |
omatthews | 2:d2c61a9be078 | 116 | |
omatthews | 2:d2c61a9be078 | 117 | |
omatthews | 2:d2c61a9be078 | 118 | /************************************************ |
omatthews | 2:d2c61a9be078 | 119 | * Helper functions for writing field callbacks * |
omatthews | 2:d2c61a9be078 | 120 | ************************************************/ |
omatthews | 2:d2c61a9be078 | 121 | |
omatthews | 2:d2c61a9be078 | 122 | /* Encode field header based on type and field number defined in the field |
omatthews | 2:d2c61a9be078 | 123 | * structure. Call this from the callback before writing out field contents. */ |
intrinseca | 0:c7beea49fc91 | 124 | bool pb_encode_tag_for_field(pb_ostream_t *stream, const pb_field_t *field); |
intrinseca | 0:c7beea49fc91 | 125 | |
omatthews | 2:d2c61a9be078 | 126 | /* Encode field header by manually specifing wire type. You need to use this |
omatthews | 2:d2c61a9be078 | 127 | * if you want to write out packed arrays from a callback field. */ |
intrinseca | 0:c7beea49fc91 | 128 | bool pb_encode_tag(pb_ostream_t *stream, pb_wire_type_t wiretype, uint32_t field_number); |
intrinseca | 0:c7beea49fc91 | 129 | |
intrinseca | 0:c7beea49fc91 | 130 | /* Encode an integer in the varint format. |
intrinseca | 0:c7beea49fc91 | 131 | * This works for bool, enum, int32, int64, uint32 and uint64 field types. */ |
omatthews | 2:d2c61a9be078 | 132 | #ifndef PB_WITHOUT_64BIT |
intrinseca | 0:c7beea49fc91 | 133 | bool pb_encode_varint(pb_ostream_t *stream, uint64_t value); |
omatthews | 2:d2c61a9be078 | 134 | #else |
omatthews | 2:d2c61a9be078 | 135 | bool pb_encode_varint(pb_ostream_t *stream, uint32_t value); |
omatthews | 2:d2c61a9be078 | 136 | #endif |
intrinseca | 0:c7beea49fc91 | 137 | |
intrinseca | 0:c7beea49fc91 | 138 | /* Encode an integer in the zig-zagged svarint format. |
intrinseca | 0:c7beea49fc91 | 139 | * This works for sint32 and sint64. */ |
omatthews | 2:d2c61a9be078 | 140 | #ifndef PB_WITHOUT_64BIT |
intrinseca | 0:c7beea49fc91 | 141 | bool pb_encode_svarint(pb_ostream_t *stream, int64_t value); |
omatthews | 2:d2c61a9be078 | 142 | #else |
omatthews | 2:d2c61a9be078 | 143 | bool pb_encode_svarint(pb_ostream_t *stream, int32_t value); |
omatthews | 2:d2c61a9be078 | 144 | #endif |
intrinseca | 0:c7beea49fc91 | 145 | |
intrinseca | 0:c7beea49fc91 | 146 | /* Encode a string or bytes type field. For strings, pass strlen(s) as size. */ |
omatthews | 2:d2c61a9be078 | 147 | bool pb_encode_string(pb_ostream_t *stream, const pb_byte_t *buffer, size_t size); |
intrinseca | 0:c7beea49fc91 | 148 | |
intrinseca | 0:c7beea49fc91 | 149 | /* Encode a fixed32, sfixed32 or float value. |
intrinseca | 0:c7beea49fc91 | 150 | * You need to pass a pointer to a 4-byte wide C variable. */ |
intrinseca | 0:c7beea49fc91 | 151 | bool pb_encode_fixed32(pb_ostream_t *stream, const void *value); |
intrinseca | 0:c7beea49fc91 | 152 | |
omatthews | 2:d2c61a9be078 | 153 | #ifndef PB_WITHOUT_64BIT |
intrinseca | 0:c7beea49fc91 | 154 | /* Encode a fixed64, sfixed64 or double value. |
intrinseca | 0:c7beea49fc91 | 155 | * You need to pass a pointer to a 8-byte wide C variable. */ |
intrinseca | 0:c7beea49fc91 | 156 | bool pb_encode_fixed64(pb_ostream_t *stream, const void *value); |
omatthews | 2:d2c61a9be078 | 157 | #endif |
intrinseca | 0:c7beea49fc91 | 158 | |
intrinseca | 0:c7beea49fc91 | 159 | /* Encode a submessage field. |
omatthews | 2:d2c61a9be078 | 160 | * You need to pass the pb_field_t array and pointer to struct, just like |
omatthews | 2:d2c61a9be078 | 161 | * with pb_encode(). This internally encodes the submessage twice, first to |
omatthews | 2:d2c61a9be078 | 162 | * calculate message size and then to actually write it out. |
intrinseca | 0:c7beea49fc91 | 163 | */ |
intrinseca | 0:c7beea49fc91 | 164 | bool pb_encode_submessage(pb_ostream_t *stream, const pb_field_t fields[], const void *src_struct); |
intrinseca | 0:c7beea49fc91 | 165 | |
intrinseca | 0:c7beea49fc91 | 166 | #ifdef __cplusplus |
intrinseca | 0:c7beea49fc91 | 167 | } /* extern "C" */ |
intrinseca | 0:c7beea49fc91 | 168 | #endif |
intrinseca | 0:c7beea49fc91 | 169 | |
omatthews | 2:d2c61a9be078 | 170 | #endif |