Ollie Matthews / Nanopb

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?

UserRevisionLine numberNew 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