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