Mercurial > pidgin3 / file comparison

comparison: libpurple/protocols/gg/lib/protobuf-c.h

libpurple/protocols/gg/lib/protobuf-c.h

branch
release-2.x.y
changeset 37180
cf498d4b54bb
parent 35617
c9069e0e3c36
equal deleted inserted replaced
36350:695838796082 37180:cf498d4b54bb
1 /* --- protobuf-c.h: public protobuf c runtime api --- */
2 /* Source: http://code.google.com/p/protobuf-c/ r331 */
3
4 /* 1 /*
5 * Copyright (c) 2008-2011, Dave Benson. 2 * Copyright (c) 2008-2014, Dave Benson and the protobuf-c authors.
6 *
7 * All rights reserved. 3 * All rights reserved.
8 * 4 *
9 * Redistribution and use in source and binary forms, with 5 * Redistribution and use in source and binary forms, with or without
10 * or without modification, are permitted provided that the 6 * modification, are permitted provided that the following conditions are
11 * following conditions are met: 7 * met:
12 * 8 *
13 * Redistributions of source code must retain the above 9 * * Redistributions of source code must retain the above copyright
14 * copyright notice, this list of conditions and the following 10 * notice, this list of conditions and the following disclaimer.
15 * disclaimer. 11 *
16 12 * * Redistributions in binary form must reproduce the above
17 * Redistributions in binary form must reproduce 13 * copyright notice, this list of conditions and the following disclaimer
18 * the above copyright notice, this list of conditions and 14 * in the documentation and/or other materials provided with the
19 * the following disclaimer in the documentation and/or other 15 * distribution.
20 * materials provided with the distribution. 16 *
21 * 17 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 * Neither the name 18 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 * of "protobuf-c" nor the names of its contributors 19 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 * may be used to endorse or promote products derived from 20 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 * this software without specific prior written permission. 21 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 * 22 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND 23 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, 24 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 25 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER 27 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 28 */
33 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 29
34 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 30 /*! \file
35 * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 31 * \mainpage Introduction
36 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 32 *
37 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 33 * This is [protobuf-c], a C implementation of [Protocol Buffers].
38 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 34 *
39 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35 * This file defines the public API for the `libprotobuf-c` support library.
40 * POSSIBILITY OF SUCH DAMAGE. 36 * This API includes interfaces that can be used directly by client code as well
41 */ 37 * as the interfaces used by the code generated by the `protoc-c` compiler.
42 38 *
43 #ifndef __PROTOBUF_C_RUNTIME_H_ 39 * The `libprotobuf-c` support library performs the actual serialization and
44 #define __PROTOBUF_C_RUNTIME_H_ 40 * deserialization of Protocol Buffers messages. It interacts with structures,
45 41 * definitions, and metadata generated by the `protoc-c` compiler from .proto
46 #include <stddef.h> 42 * files.
43 *
44 * \authors Dave Benson and the `protobuf-c` authors.
45 *
46 * \copyright 2008-2014. Licensed under the terms of the [BSD-2-Clause] license.
47 *
48 * [protobuf-c]: https://github.com/protobuf-c/protobuf-c
49 * [Protocol Buffers]: https://developers.google.com/protocol-buffers/
50 * [BSD-2-Clause]: http://opensource.org/licenses/BSD-2-Clause
51 *
52 * \page gencode Generated Code
53 *
54 * For each enum, we generate a C enum. For each message, we generate a C
55 * structure which can be cast to a `ProtobufCMessage`.
56 *
57 * For each enum and message, we generate a descriptor object that allows us to
58 * implement a kind of reflection on the structures.
59 *
60 * First, some naming conventions:
61 *
62 * - The name of the type for enums and messages and services is camel case
63 * (meaning WordsAreCrammedTogether) except that double underscores are used
64 * to delimit scopes. For example, the following `.proto` file:
65 *
66 ~~~{.proto}
67 package foo.bar;
68 message BazBah {
69 optional int32 val = 1;
70 }
71 ~~~
72 *
73 * would generate a C type `Foo__Bar__BazBah`.
74 *
75 * - Identifiers for functions and globals are all lowercase, with camel case
76 * words separated by single underscores. For example, one of the function
77 * prototypes generated by `protoc-c` for the above example:
78 *
79 ~~~{.c}
80 Foo__Bar__BazBah *
81 foo__bar__baz_bah__unpack
82 (ProtobufCAllocator *allocator,
83 size_t len,
84 const uint8_t *data);
85 ~~~
86 *
87 * - Identifiers for enum values contain an uppercase prefix which embeds the
88 * package name and the enum type name.
89 *
90 * - A double underscore is used to separate further components of identifier
91 * names.
92 *
93 * For example, in the name of the unpack function above, the package name
94 * `foo.bar` has become `foo__bar`, the message name BazBah has become
95 * `baz_bah`, and the method name is `unpack`. These are all joined with double
96 * underscores to form the C identifier `foo__bar__baz_bah__unpack`.
97 *
98 * We also generate descriptor objects for messages and enums. These are
99 * declared in the `.pb-c.h` files:
100 *
101 ~~~{.c}
102 extern const ProtobufCMessageDescriptor foo__bar__baz_bah__descriptor;
103 ~~~
104 *
105 * The message structures all begin with `ProtobufCMessageDescriptor *` which is
106 * sufficient to allow them to be cast to `ProtobufCMessage`.
107 *
108 * For each message defined in a `.proto` file, we generate a number of
109 * functions. Each function name contains a prefix based on the package name and
110 * message name in order to make it a unique C identifier.
111 *
112 * - `unpack()`. Unpacks data for a particular message format. Note that the
113 * `allocator` parameter is usually `NULL` to indicate that the system's
114 * `malloc()` and `free()` functions should be used for dynamically allocating
115 * memory.
116 *
117 ~~~{.c}
118 Foo__Bar__BazBah *
119 foo__bar__baz_bah__unpack
120 (ProtobufCAllocator *allocator,
121 size_t len,
122 const uint8_t *data);
123 ~~~
124 *
125 * - `free_unpacked()`. Frees a message object obtained with the `unpack()`
126 * method.
127 *
128 ~~~{.c}
129 void foo__bar__baz_bah__free_unpacked
130 (Foo__Bar__BazBah *message,
131 ProtobufCAllocator *allocator);
132 ~~~
133 *
134 * - `get_packed_size()`. Calculates the length in bytes of the serialized
135 * representation of the message object.
136 *
137 ~~~{.c}
138 size_t foo__bar__baz_bah__get_packed_size
139 (const Foo__Bar__BazBah *message);
140 ~~~
141 *
142 * - `pack()`. Pack a message object into a preallocated buffer. Assumes that
143 * the buffer is large enough. (Use `get_packed_size()` first.)
144 *
145 ~~~{.c}
146 size_t foo__bar__baz_bah__pack
147 (const Foo__Bar__BazBah *message,
148 uint8_t *out);
149 ~~~
150 *
151 * - `pack_to_buffer()`. Packs a message into a "virtual buffer". This is an
152 * object which defines an "append bytes" callback to consume data as it is
153 * serialized.
154 *
155 ~~~{.c}
156 size_t foo__bar__baz_bah__pack_to_buffer
157 (const Foo__Bar__BazBah *message,
158 ProtobufCBuffer *buffer);
159 ~~~
160 *
161 * \page pack Packing and unpacking messages
162 *
163 * To pack a message, first compute the packed size of the message with
164 * protobuf_c_message_get_packed_size(), then allocate a buffer of at least
165 * that size, then call protobuf_c_message_pack().
166 *
167 * Alternatively, a message can be serialized without calculating the final size
168 * first. Use the protobuf_c_message_pack_to_buffer() function and provide a
169 * ProtobufCBuffer object which implements an "append" method that consumes
170 * data.
171 *
172 * To unpack a message, call the protobuf_c_message_unpack() function. The
173 * result can be cast to an object of the type that matches the descriptor for
174 * the message.
175 *
176 * The result of unpacking a message should be freed with
177 * protobuf_c_message_free_unpacked().
178 */
179
180 #ifndef PROTOBUF_C_H
181 #define PROTOBUF_C_H
182
47 #include <assert.h> 183 #include <assert.h>
48 #include <limits.h> 184 #include <limits.h>
49 #include "libgadu.h" 185 #include <stddef.h>
186 #include <stdint.h>
50 187
51 #ifdef __cplusplus 188 #ifdef __cplusplus
52 # define PROTOBUF_C_BEGIN_DECLS extern "C" { 189 # define PROTOBUF_C__BEGIN_DECLS extern "C" {
53 # define PROTOBUF_C_END_DECLS } 190 # define PROTOBUF_C__END_DECLS }
54 #else 191 #else
55 # define PROTOBUF_C_BEGIN_DECLS 192 # define PROTOBUF_C__BEGIN_DECLS
56 # define PROTOBUF_C_END_DECLS 193 # define PROTOBUF_C__END_DECLS
57 #endif 194 #endif
58 195
59 #if !defined(PROTOBUF_C_NO_DEPRECATED) && (__GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1)) 196 PROTOBUF_C__BEGIN_DECLS
60 #define PROTOBUF_C_DEPRECATED __attribute__((__deprecated__)) 197
198 #if defined(_WIN32) && defined(PROTOBUF_C_USE_SHARED_LIB)
199 # ifdef PROTOBUF_C_EXPORT
200 # define PROTOBUF_C__API __declspec(dllexport)
201 # else
202 # define PROTOBUF_C__API __declspec(dllimport)
203 # endif
61 #else 204 #else
62 #define PROTOBUF_C_DEPRECATED 205 # define PROTOBUF_C__API
63 #endif 206 #endif
64 207
65 /* The version of protobuf-c you are compiling against. */ 208 #if !defined(PROTOBUF_C__NO_DEPRECATED) && \
66 #define PROTOBUF_C_MAJOR 0 209 ((__GNUC__ > 3) || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1))
67 #define PROTOBUF_C_MINOR 14 210 # define PROTOBUF_C__DEPRECATED __attribute__((__deprecated__))
68 211 #else
69 /* The version of protobuf-c you are linking against. */ 212 # define PROTOBUF_C__DEPRECATED
70 extern unsigned protobuf_c_major; 213 #endif
71 extern unsigned protobuf_c_minor; 214
72 215 #ifndef PROTOBUF_C__FORCE_ENUM_TO_BE_INT_SIZE
73 #define PROTOBUF_C_API 216 #define PROTOBUF_C__FORCE_ENUM_TO_BE_INT_SIZE(enum_name) \
74 217 , _##enum_name##_IS_INT_SIZE = INT_MAX
75 PROTOBUF_C_BEGIN_DECLS 218 #endif
76 219
77 typedef enum 220 #define PROTOBUF_C__SERVICE_DESCRIPTOR_MAGIC 0x14159bc3
221 #define PROTOBUF_C__MESSAGE_DESCRIPTOR_MAGIC 0x28aaeef9
222 #define PROTOBUF_C__ENUM_DESCRIPTOR_MAGIC 0x114315af
223
224 /**
225 * \defgroup api Public API
226 *
227 * This is the public API for `libprotobuf-c`. These interfaces are stable and
228 * subject to Semantic Versioning guarantees.
229 *
230 * @{
231 */
232
233 /**
234 * Values for the `flags` word in `ProtobufCFieldDescriptor`.
235 */
236 typedef enum {
237 /** Set if the field is repeated and marked with the `packed` option. */
238 PROTOBUF_C_FIELD_FLAG_PACKED = (1 << 0),
239
240 /** Set if the field is marked with the `deprecated` option. */
241 PROTOBUF_C_FIELD_FLAG_DEPRECATED = (1 << 1),
242 } ProtobufCFieldFlag;
243
244 /**
245 * Message field rules.
246 *
247 * \see [Defining A Message Type] in the Protocol Buffers documentation.
248 *
249 * [Defining A Message Type]:
250 * https://developers.google.com/protocol-buffers/docs/proto#simple
251 */
252 typedef enum {
253 /** A well-formed message must have exactly one of this field. */
254 PROTOBUF_C_LABEL_REQUIRED,
255
256 /**
257 * A well-formed message can have zero or one of this field (but not
258 * more than one).
259 */
260 PROTOBUF_C_LABEL_OPTIONAL,
261
262 /**
263 * This field can be repeated any number of times (including zero) in a
264 * well-formed message. The order of the repeated values will be
265 * preserved.
266 */
267 PROTOBUF_C_LABEL_REPEATED,
268 } ProtobufCLabel;
269
270 /**
271 * Field value types.
272 *
273 * \see [Scalar Value Types] in the Protocol Buffers documentation.
274 *
275 * [Scalar Value Types]:
276 * https://developers.google.com/protocol-buffers/docs/proto#scalar
277 */
278 typedef enum {
279 PROTOBUF_C_TYPE_INT32, /**< int32 */
280 PROTOBUF_C_TYPE_SINT32, /**< signed int32 */
281 PROTOBUF_C_TYPE_SFIXED32, /**< signed int32 (4 bytes) */
282 PROTOBUF_C_TYPE_INT64, /**< int64 */
283 PROTOBUF_C_TYPE_SINT64, /**< signed int64 */
284 PROTOBUF_C_TYPE_SFIXED64, /**< signed int64 (8 bytes) */
285 PROTOBUF_C_TYPE_UINT32, /**< unsigned int32 */
286 PROTOBUF_C_TYPE_FIXED32, /**< unsigned int32 (4 bytes) */
287 PROTOBUF_C_TYPE_UINT64, /**< unsigned int64 */
288 PROTOBUF_C_TYPE_FIXED64, /**< unsigned int64 (8 bytes) */
289 PROTOBUF_C_TYPE_FLOAT, /**< float */
290 PROTOBUF_C_TYPE_DOUBLE, /**< double */
291 PROTOBUF_C_TYPE_BOOL, /**< boolean */
292 PROTOBUF_C_TYPE_ENUM, /**< enumerated type */
293 PROTOBUF_C_TYPE_STRING, /**< UTF-8 or ASCII string */
294 PROTOBUF_C_TYPE_BYTES, /**< arbitrary byte sequence */
295 PROTOBUF_C_TYPE_MESSAGE, /**< nested message */
296 } ProtobufCType;
297
298 /**
299 * Field wire types.
300 *
301 * \see [Message Structure] in the Protocol Buffers documentation.
302 *
303 * [Message Structure]:
304 * https://developers.google.com/protocol-buffers/docs/encoding#structure
305 */
306 typedef enum {
307 PROTOBUF_C_WIRE_TYPE_VARINT = 0,
308 PROTOBUF_C_WIRE_TYPE_64BIT = 1,
309 PROTOBUF_C_WIRE_TYPE_LENGTH_PREFIXED = 2,
310 /* "Start group" and "end group" wire types are unsupported. */
311 PROTOBUF_C_WIRE_TYPE_32BIT = 5,
312 } ProtobufCWireType;
313
314 struct ProtobufCAllocator;
315 struct ProtobufCBinaryData;
316 struct ProtobufCBuffer;
317 struct ProtobufCBufferSimple;
318 struct ProtobufCEnumDescriptor;
319 struct ProtobufCEnumValue;
320 struct ProtobufCEnumValueIndex;
321 struct ProtobufCFieldDescriptor;
322 struct ProtobufCIntRange;
323 struct ProtobufCMessage;
324 struct ProtobufCMessageDescriptor;
325 struct ProtobufCMessageUnknownField;
326 struct ProtobufCMethodDescriptor;
327 struct ProtobufCService;
328 struct ProtobufCServiceDescriptor;
329
330 typedef struct ProtobufCAllocator ProtobufCAllocator;
331 typedef struct ProtobufCBinaryData ProtobufCBinaryData;
332 typedef struct ProtobufCBuffer ProtobufCBuffer;
333 typedef struct ProtobufCBufferSimple ProtobufCBufferSimple;
334 typedef struct ProtobufCEnumDescriptor ProtobufCEnumDescriptor;
335 typedef struct ProtobufCEnumValue ProtobufCEnumValue;
336 typedef struct ProtobufCEnumValueIndex ProtobufCEnumValueIndex;
337 typedef struct ProtobufCFieldDescriptor ProtobufCFieldDescriptor;
338 typedef struct ProtobufCIntRange ProtobufCIntRange;
339 typedef struct ProtobufCMessage ProtobufCMessage;
340 typedef struct ProtobufCMessageDescriptor ProtobufCMessageDescriptor;
341 typedef struct ProtobufCMessageUnknownField ProtobufCMessageUnknownField;
342 typedef struct ProtobufCMethodDescriptor ProtobufCMethodDescriptor;
343 typedef struct ProtobufCService ProtobufCService;
344 typedef struct ProtobufCServiceDescriptor ProtobufCServiceDescriptor;
345
346 /** Boolean type. */
347 typedef int protobuf_c_boolean;
348
349 typedef void (*ProtobufCClosure)(const ProtobufCMessage *, void *closure_data);
350 typedef void (*ProtobufCMessageInit)(ProtobufCMessage *);
351 typedef void (*ProtobufCServiceDestroy)(ProtobufCService *);
352
353 /**
354 * Structure for defining a custom memory allocator.
355 */
356 struct ProtobufCAllocator {
357 /** Function to allocate memory. */
358 void *(*alloc)(void *allocator_data, size_t size);
359
360 /** Function to free memory. */
361 void (*free)(void *allocator_data, void *pointer);
362
363 /** Opaque pointer passed to `alloc` and `free` functions. */
364 void *allocator_data;
365 };
366
367 /**
368 * Structure for the protobuf `bytes` scalar type.
369 *
370 * The data contained in a `ProtobufCBinaryData` is an arbitrary sequence of
371 * bytes. It may contain embedded `NUL` characters and is not required to be
372 * `NUL`-terminated.
373 */
374 struct ProtobufCBinaryData {
375 size_t len; /**< Number of bytes in the `data` field. */
376 uint8_t *data; /**< Data bytes. */
377 };
378
379 /**
380 * Structure for defining a virtual append-only buffer. Used by
381 * protobuf_c_message_pack_to_buffer() to abstract the consumption of serialized
382 * bytes.
383 *
384 * `ProtobufCBuffer` "subclasses" may be defined on the stack. For example, to
385 * write to a `FILE` object:
386 *
387 ~~~{.c}
388 typedef struct {
389 ProtobufCBuffer base;
390 FILE *fp;
391 } BufferAppendToFile;
392
393 static void
394 my_buffer_file_append(ProtobufCBuffer *buffer,
395 size_t len,
396 const uint8_t *data)
78 { 397 {
79 PROTOBUF_C_LABEL_REQUIRED, 398 BufferAppendToFile *file_buf = (BufferAppendToFile *) buffer;
80 PROTOBUF_C_LABEL_OPTIONAL, 399 fwrite(data, len, 1, file_buf->fp); // XXX: No error handling!
81 PROTOBUF_C_LABEL_REPEATED 400 }
82 } ProtobufCLabel; 401 ~~~
83 402 *
84 typedef enum 403 * To use this new type of ProtobufCBuffer, it could be called as follows:
85 { 404 *
86 PROTOBUF_C_TYPE_INT32, 405 ~~~{.c}
87 PROTOBUF_C_TYPE_SINT32, 406 ...
88 PROTOBUF_C_TYPE_SFIXED32, 407 BufferAppendToFile tmp = {0};
89 PROTOBUF_C_TYPE_INT64, 408 tmp.base.append = my_buffer_file_append;
90 PROTOBUF_C_TYPE_SINT64, 409 tmp.fp = fp;
91 PROTOBUF_C_TYPE_SFIXED64, 410 protobuf_c_message_pack_to_buffer(&message, &tmp);
92 PROTOBUF_C_TYPE_UINT32, 411 ...
93 PROTOBUF_C_TYPE_FIXED32, 412 ~~~
94 PROTOBUF_C_TYPE_UINT64, 413 */
95 PROTOBUF_C_TYPE_FIXED64, 414 struct ProtobufCBuffer {
96 PROTOBUF_C_TYPE_FLOAT, 415 /** Append function. Consumes the `len` bytes stored at `data`. */
97 PROTOBUF_C_TYPE_DOUBLE, 416 void (*append)(ProtobufCBuffer *buffer,
98 PROTOBUF_C_TYPE_BOOL, 417 size_t len,
99 PROTOBUF_C_TYPE_ENUM, 418 const uint8_t *data);
100 PROTOBUF_C_TYPE_STRING, 419 };
101 PROTOBUF_C_TYPE_BYTES, 420
102 //PROTOBUF_C_TYPE_GROUP, // NOT SUPPORTED 421 /**
103 PROTOBUF_C_TYPE_MESSAGE, 422 * Simple buffer "subclass" of `ProtobufCBuffer`.
104 } ProtobufCType; 423 *
105 424 * A `ProtobufCBufferSimple` object is declared on the stack and uses a
106 425 * scratch buffer provided by the user for the initial allocation. It performs
107 typedef int protobuf_c_boolean; 426 * exponential resizing, using dynamically allocated memory. A
108 #define PROTOBUF_C_OFFSETOF(struct, member) offsetof(struct, member) 427 * `ProtobufCBufferSimple` object can be created and used as follows:
109 428 *
110 #define PROTOBUF_C_ASSERT(condition) assert(condition) 429 ~~~{.c}
111 #define PROTOBUF_C_ASSERT_NOT_REACHED() assert(0) 430 uint8_t pad[128];
112 431 ProtobufCBufferSimple simple = PROTOBUF_C_BUFFER_SIMPLE_INIT(pad);
113 typedef struct _ProtobufCBinaryData ProtobufCBinaryData; 432 ProtobufCBuffer *buffer = (ProtobufCBuffer *) &simple;
114 struct _ProtobufCBinaryData 433 ~~~
115 { 434 *
116 size_t len; 435 * `buffer` can now be used with `protobuf_c_message_pack_to_buffer()`. Once a
117 uint8_t *data; 436 * message has been serialized to a `ProtobufCBufferSimple` object, the
118 }; 437 * serialized data bytes can be accessed from the `.data` field.
119 438 *
120 typedef struct _ProtobufCIntRange ProtobufCIntRange; /* private */ 439 * To free the memory allocated by a `ProtobufCBufferSimple` object, if any,
121 440 * call PROTOBUF_C_BUFFER_SIMPLE_CLEAR() on the object, for example:
122 /* --- memory management --- */ 441 *
123 typedef struct _ProtobufCAllocator ProtobufCAllocator; 442 ~~~{.c}
124 struct _ProtobufCAllocator 443 PROTOBUF_C_BUFFER_SIMPLE_CLEAR(&simple);
125 { 444 ~~~
126 void *(*alloc)(void *allocator_data, size_t size); 445 *
127 void (*free)(void *allocator_data, void *pointer); 446 * \see PROTOBUF_C_BUFFER_SIMPLE_INIT
128 void *(*tmp_alloc)(void *allocator_data, size_t size); 447 * \see PROTOBUF_C_BUFFER_SIMPLE_CLEAR
129 unsigned max_alloca; 448 */
130 void *allocator_data; 449 struct ProtobufCBufferSimple {
131 }; 450 /** "Base class". */
132 451 ProtobufCBuffer base;
133 /* This is a configurable allocator. 452 /** Number of bytes allocated in `data`. */
134 * By default, it uses the system allocator (meaning malloc() and free()). 453 size_t alloced;
135 * This is typically changed to adapt to frameworks that provide 454 /** Number of bytes currently stored in `data`. */
136 * some nonstandard allocation functions. 455 size_t len;
137 * 456 /** Data bytes. */
138 * NOTE: you may modify this allocator. 457 uint8_t *data;
139 */ 458 /** Whether `data` must be freed. */
140 extern PROTOBUF_C_API ProtobufCAllocator protobuf_c_default_allocator; /* settable */ 459 protobuf_c_boolean must_free_data;
141 460 /** Allocator to use. May be NULL to indicate the system allocator. */
142 /* This is the system allocator, meaning it uses malloc() and free(). 461 ProtobufCAllocator *allocator;
143 * 462 };
144 * NOTE: please do NOT modify this allocator. 463
145 */ 464 /**
146 extern PROTOBUF_C_API ProtobufCAllocator protobuf_c_system_allocator; /* use malloc, free etc */ 465 * Describes an enumeration as a whole, with all of its values.
147 466 */
148 /* This is the function that our default allocators call when they 467 struct ProtobufCEnumDescriptor {
149 run out-of-memory. The default behavior of this function is to 468 /** Magic value checked to ensure that the API is used correctly. */
150 terminate your program. */ 469 uint32_t magic;
151 extern PROTOBUF_C_API void (*protobuf_c_out_of_memory) (void); 470
152 471 /** The qualified name (e.g., "namespace.Type"). */
153 /* --- append-only data buffer --- */ 472 const char *name;
154 typedef struct _ProtobufCBuffer ProtobufCBuffer; 473 /** The unqualified name as given in the .proto file (e.g., "Type"). */
155 struct _ProtobufCBuffer 474 const char *short_name;
156 { 475 /** Identifier used in generated C code. */
157 void (*append)(ProtobufCBuffer *buffer, 476 const char *c_name;
158 size_t len, 477 /** The dot-separated namespace. */
159 const uint8_t *data); 478 const char *package_name;
160 }; 479
161 /* --- enums --- */ 480 /** Number elements in `values`. */
162 typedef struct _ProtobufCEnumValue ProtobufCEnumValue; 481 unsigned n_values;
163 typedef struct _ProtobufCEnumValueIndex ProtobufCEnumValueIndex; 482 /** Array of distinct values, sorted by numeric value. */
164 typedef struct _ProtobufCEnumDescriptor ProtobufCEnumDescriptor; 483 const ProtobufCEnumValue *values;
165 484
166 /* ProtobufCEnumValue: this represents a single value of 485 /** Number of elements in `values_by_name`. */
167 * an enumeration. 486 unsigned n_value_names;
168 * 'name' is the string identifying this value, as given in the .proto file. 487 /** Array of named values, including aliases, sorted by name. */
169 * 'c_name' is the full name of the C enumeration value. 488 const ProtobufCEnumValueIndex *values_by_name;
170 * 'value' is the number assigned to this value, as given in the .proto file. 489
171 */ 490 /** Number of elements in `value_ranges`. */
172 struct _ProtobufCEnumValue 491 unsigned n_value_ranges;
173 { 492 /** Value ranges, for faster lookups by numeric value. */
174 const char *name; 493 const ProtobufCIntRange *value_ranges;
175 const char *c_name; 494
176 int value; 495 /** Reserved for future use. */
177 }; 496 void *reserved1;
178 497 /** Reserved for future use. */
179 /* ProtobufCEnumDescriptor: the represents the enum as a whole, 498 void *reserved2;
180 * with all its values. 499 /** Reserved for future use. */
181 * 'magic' is a code we check to ensure that the api is used correctly. 500 void *reserved3;
182 * 'name' is the qualified name (e.g. "namespace.Type"). 501 /** Reserved for future use. */
183 * 'short_name' is the unqualified name ("Type"), as given in the .proto file. 502 void *reserved4;
184 * 'package_name' is the '.'-separated namespace 503 };
185 * 'n_values' is the number of distinct values. 504
186 * 'values' is the array of distinct values. 505 /**
187 * 'n_value_names' number of named values (including aliases). 506 * Represents a single value of an enumeration.
188 * 'value_names' are the named values (including aliases). 507 */
189 * 508 struct ProtobufCEnumValue {
190 * The rest of the values are private essentially. 509 /** The string identifying this value in the .proto file. */
191 * 510 const char *name;
192 * see also: Use protobuf_c_enum_descriptor_get_value_by_name() 511
193 * and protobuf_c_enum_descriptor_get_value() to efficiently 512 /** The string identifying this value in generated C code. */
194 * lookup values in the descriptor. 513 const char *c_name;
195 */ 514
196 struct _ProtobufCEnumDescriptor 515 /** The numeric value assigned in the .proto file. */
197 { 516 int value;
198 uint32_t magic; 517 };
199 518
200 const char *name; 519 /**
201 const char *short_name; 520 * Used by `ProtobufCEnumDescriptor` to look up enum values.
202 const char *c_name; 521 */
203 const char *package_name; 522 struct ProtobufCEnumValueIndex {
204 523 /** Name of the enum value. */
205 /* sorted by value */ 524 const char *name;
206 unsigned n_values; 525 /** Index into values[] array. */
207 const ProtobufCEnumValue *values; 526 unsigned index;
208 527 };
209 /* sorted by name */ 528
210 unsigned n_value_names; 529 /**
211 const ProtobufCEnumValueIndex *values_by_name; 530 * Describes a single field in a message.
212 531 */
213 /* value-ranges, for faster lookups by number */ 532 struct ProtobufCFieldDescriptor {
214 unsigned n_value_ranges; 533 /** Name of the field as given in the .proto file. */
215 const ProtobufCIntRange *value_ranges; 534 const char *name;
216 535
217 void *reserved1; 536 /** Tag value of the field as given in the .proto file. */
218 void *reserved2; 537 uint32_t id;
219 void *reserved3; 538
220 void *reserved4; 539 /** Whether the field is `REQUIRED`, `OPTIONAL`, or `REPEATED`. */
221 }; 540 ProtobufCLabel label;
222 541
223 /* --- messages --- */ 542 /** The type of the field. */
224 typedef struct _ProtobufCMessageDescriptor ProtobufCMessageDescriptor; 543 ProtobufCType type;
225 typedef struct _ProtobufCFieldDescriptor ProtobufCFieldDescriptor; 544
226 typedef struct _ProtobufCMessage ProtobufCMessage; 545 /**
227 typedef void (*ProtobufCMessageInit)(ProtobufCMessage *); 546 * The offset in bytes of the message's C structure's quantifier field
228 /* ProtobufCFieldDescriptor: description of a single field 547 * (the `has_MEMBER` field for optional members or the `n_MEMBER` field
229 * in a message. 548 * for repeated members.
230 * 'name' is the name of the field, as given in the .proto file. 549 */
231 * 'id' is the code representing the field, as given in the .proto file. 550 unsigned quantifier_offset;
232 * 'label' is one of PROTOBUF_C_LABEL_{REQUIRED,OPTIONAL,REPEATED} 551
233 * 'type' is the type of field. 552 /**
234 * 'quantifier_offset' is the offset in bytes into the message's C structure 553 * The offset in bytes into the message's C structure for the member
235 * for this member's "has_MEMBER" field (for optional members) or 554 * itself.
236 * "n_MEMBER" field (for repeated members). 555 */
237 * 'offset' is the offset in bytes into the message's C structure 556 unsigned offset;
238 * for the member itself. 557
239 * 'descriptor' is a pointer to a ProtobufC{Enum,Message}Descriptor 558 /**
240 * if type is PROTOBUF_C_TYPE_{ENUM,MESSAGE} respectively, 559 * A type-specific descriptor.
241 * otherwise NULL. 560 *
242 * 'default_value' is a pointer to a default value for this field, 561 * If `type` is `PROTOBUF_C_TYPE_ENUM`, then `descriptor` points to the
243 * where allowed. 562 * corresponding `ProtobufCEnumDescriptor`.
244 * 'packed' is only for REPEATED fields (it is 0 otherwise); this is if 563 *
245 * the repeated fields is marked with the 'packed' options. 564 * If `type` is `PROTOBUF_C_TYPE_MESSAGE`, then `descriptor` points to
246 */ 565 * the corresponding `ProtobufCMessageDescriptor`.
247 struct _ProtobufCFieldDescriptor 566 *
248 { 567 * Otherwise this field is NULL.
249 const char *name; 568 */
250 uint32_t id; 569 const void *descriptor; /* for MESSAGE and ENUM types */
251 ProtobufCLabel label; 570
252 ProtobufCType type; 571 /** The default value for this field, if defined. May be NULL. */
253 unsigned quantifier_offset; 572 const void *default_value;
254 unsigned offset; 573
255 const void *descriptor; /* for MESSAGE and ENUM types */ 574 /**
256 const void *default_value; /* or NULL if no default-value */ 575 * A flag word. Zero or more of the bits defined in the
257 protobuf_c_boolean packed; 576 * `ProtobufCFieldFlag` enum may be set.
258 577 */
259 unsigned reserved_flags; 578 uint32_t flags;
260 void *reserved2; 579
261 void *reserved3; 580 /** Reserved for future use. */
262 }; 581 unsigned reserved_flags;
263 /* ProtobufCMessageDescriptor: description of a message. 582 /** Reserved for future use. */
264 * 583 void *reserved2;
265 * 'magic' is a code we check to ensure that the api is used correctly. 584 /** Reserved for future use. */
266 * 'name' is the qualified name (e.g. "namespace.Type"). 585 void *reserved3;
267 * 'short_name' is the unqualified name ("Type"), as given in the .proto file. 586 };
268 * 'c_name' is the c-formatted name of the structure 587
269 * 'package_name' is the '.'-separated namespace 588 /**
270 * 'sizeof_message' is the size in bytes of the C structure 589 * Helper structure for optimizing int => index lookups in the case
271 * representing an instance of this type of message. 590 * where the keys are mostly consecutive values, as they presumably are for
272 * 'n_fields' is the number of known fields in this message. 591 * enums and fields.
273 * 'fields' is the fields sorted by id number. 592 *
274 * 'fields_sorted_by_name', 'n_field_ranges' and 'field_ranges' 593 * The data structures requires that the values in the original array are
275 * are used for looking up fields by name and id. (private) 594 * sorted.
276 */ 595 */
277 struct _ProtobufCMessageDescriptor 596 struct ProtobufCIntRange {
278 { 597 int start_value;
279 uint32_t magic; 598 unsigned orig_index;
280 599 /*
281 const char *name; 600 * NOTE: the number of values in the range can be inferred by looking
282 const char *short_name; 601 * at the next element's orig_index. A dummy element is added to make
283 const char *c_name; 602 * this simple.
284 const char *package_name; 603 */
285 604 };
286 size_t sizeof_message; 605
287 606 /**
288 /* sorted by field-id */ 607 * An instance of a message.
289 unsigned n_fields; 608 *
290 const ProtobufCFieldDescriptor *fields; 609 * `ProtobufCMessage` is a light-weight "base class" for all messages.
291 const unsigned *fields_sorted_by_name; 610 *
292 611 * In particular, `ProtobufCMessage` doesn't have any allocation policy
293 /* ranges, optimization for looking up fields */ 612 * associated with it. That's because it's common to create `ProtobufCMessage`
294 unsigned n_field_ranges; 613 * objects on the stack. In fact, that's what we recommend for sending messages.
295 const ProtobufCIntRange *field_ranges; 614 * If the object is allocated from the stack, you can't really have a memory
296 615 * leak.
297 ProtobufCMessageInit message_init; 616 *
298 void *reserved1; 617 * This means that calls to functions like protobuf_c_message_unpack() which
299 void *reserved2; 618 * return a `ProtobufCMessage` must be paired with a call to a free function,
300 void *reserved3; 619 * like protobuf_c_message_free_unpacked().
301 }; 620 */
302 621 struct ProtobufCMessage {
303 622 /** The descriptor for this message type. */
304 /* ProtobufCMessage: an instance of a message. 623 const ProtobufCMessageDescriptor *descriptor;
305 * 624 /** The number of elements in `unknown_fields`. */
306 * ProtobufCMessage is sort-of a lightweight 625 unsigned n_unknown_fields;
307 * base-class for all messages. 626 /** The fields that weren't recognized by the parser. */
308 * 627 ProtobufCMessageUnknownField *unknown_fields;
309 * In particular, ProtobufCMessage doesn't have 628 };
310 * any allocation policy associated with it. 629
311 * That's because it is common to create ProtobufCMessage's 630 /**
312 * on the stack. In fact, we that's what we recommend 631 * Describes a message.
313 * for sending messages (because if you just allocate from the 632 */
314 * stack, then you can't really have a memory leak). 633 struct ProtobufCMessageDescriptor {
315 * 634 /** Magic value checked to ensure that the API is used correctly. */
316 * This means that functions like protobuf_c_message_unpack() 635 uint32_t magic;
317 * which return a ProtobufCMessage must be paired 636
318 * with a free function, like protobuf_c_message_free_unpacked(). 637 /** The qualified name (e.g., "namespace.Type"). */
319 * 638 const char *name;
320 * 'descriptor' gives the locations and types of the members of message 639 /** The unqualified name as given in the .proto file (e.g., "Type"). */
321 * 'n_unknown_fields' is the number of fields we didn't recognize. 640 const char *short_name;
322 * 'unknown_fields' are fields we didn't recognize. 641 /** Identifier used in generated C code. */
323 */ 642 const char *c_name;
324 typedef struct _ProtobufCMessageUnknownField ProtobufCMessageUnknownField; 643 /** The dot-separated namespace. */
325 struct _ProtobufCMessage 644 const char *package_name;
326 { 645
327 const ProtobufCMessageDescriptor *descriptor; 646 /**
328 unsigned n_unknown_fields; 647 * Size in bytes of the C structure representing an instance of this
329 ProtobufCMessageUnknownField *unknown_fields; 648 * type of message.
330 }; 649 */
650 size_t sizeof_message;
651
652 /** Number of elements in `fields`. */
653 unsigned n_fields;
654 /** Field descriptors, sorted by tag number. */
655 const ProtobufCFieldDescriptor *fields;
656 /** Used for looking up fields by name. */
657 const unsigned *fields_sorted_by_name;
658
659 /** Number of elements in `field_ranges`. */
660 unsigned n_field_ranges;
661 /** Used for looking up fields by id. */
662 const ProtobufCIntRange *field_ranges;
663
664 /** Message initialisation function. */
665 ProtobufCMessageInit message_init;
666
667 /** Reserved for future use. */
668 void *reserved1;
669 /** Reserved for future use. */
670 void *reserved2;
671 /** Reserved for future use. */
672 void *reserved3;
673 };
674
675 /**
676 * An unknown message field.
677 */
678 struct ProtobufCMessageUnknownField {
679 /** The tag number. */
680 uint32_t tag;
681 /** The wire type of the field. */
682 ProtobufCWireType wire_type;
683 /** Number of bytes in `data`. */
684 size_t len;
685 /** Field data. */
686 uint8_t *data;
687 };
688
689 /**
690 * Method descriptor.
691 */
692 struct ProtobufCMethodDescriptor {
693 /** Method name. */
694 const char *name;
695 /** Input message descriptor. */
696 const ProtobufCMessageDescriptor *input;
697 /** Output message descriptor. */
698 const ProtobufCMessageDescriptor *output;
699 };
700
701 /**
702 * Service.
703 */
704 struct ProtobufCService {
705 /** Service descriptor. */
706 const ProtobufCServiceDescriptor *descriptor;
707 /** Function to invoke the service. */
708 void (*invoke)(ProtobufCService *service,
709 unsigned method_index,
710 const ProtobufCMessage *input,
711 ProtobufCClosure closure,
712 void *closure_data);
713 /** Function to destroy the service. */
714 void (*destroy)(ProtobufCService *service);
715 };
716
717 /**
718 * Service descriptor.
719 */
720 struct ProtobufCServiceDescriptor {
721 /** Magic value checked to ensure that the API is used correctly. */
722 uint32_t magic;
723
724 /** Service name. */
725 const char *name;
726 /** Short version of service name. */
727 const char *short_name;
728 /** C identifier for the service name. */
729 const char *c_name;
730 /** Package name. */
731 const char *package;
732 /** Number of elements in `methods`. */
733 unsigned n_methods;
734 /** Method descriptors, in the order defined in the .proto file. */
735 const ProtobufCMethodDescriptor *methods;
736 /** Sort index of methods. */
737 const unsigned *method_indices_by_name;
738 };
739
740 /**
741 * Get the version of the protobuf-c library. Note that this is the version of
742 * the library linked against, not the version of the headers compiled against.
743 *
744 * \return A string containing the version number of protobuf-c.
745 */
746 PROTOBUF_C__API
747 const char *
748 protobuf_c_version(void);
749
750 /**
751 * Get the version of the protobuf-c library. Note that this is the version of
752 * the library linked against, not the version of the headers compiled against.
753 *
754 * \return A 32 bit unsigned integer containing the version number of
755 * protobuf-c, represented in base-10 as (MAJOR*1E6) + (MINOR*1E3) + PATCH.
756 */
757 PROTOBUF_C__API
758 uint32_t
759 protobuf_c_version_number(void);
760
761 /**
762 * The version of the protobuf-c headers, represented as a string using the same
763 * format as protobuf_c_version().
764 */
765 #define PROTOBUF_C_VERSION "1.0.2"
766
767 /**
768 * The version of the protobuf-c headers, represented as an integer using the
769 * same format as protobuf_c_version_number().
770 */
771 #define PROTOBUF_C_VERSION_NUMBER 1000002
772
773 /**
774 * The minimum protoc-c version which works with the current version of the
775 * protobuf-c headers.
776 */
777 #define PROTOBUF_C_MIN_COMPILER_VERSION 1000000
778
779 /**
780 * Look up a `ProtobufCEnumValue` from a `ProtobufCEnumDescriptor` by name.
781 *
782 * \param desc
783 * The `ProtobufCEnumDescriptor` object.
784 * \param name
785 * The `name` field from the corresponding `ProtobufCEnumValue` object to
786 * match.
787 * \return
788 * A `ProtobufCEnumValue` object.
789 * \retval NULL
790 * If not found.
791 */
792 PROTOBUF_C__API
793 const ProtobufCEnumValue *
794 protobuf_c_enum_descriptor_get_value_by_name(
795 const ProtobufCEnumDescriptor *desc,
796 const char *name);
797
798 /**
799 * Look up a `ProtobufCEnumValue` from a `ProtobufCEnumDescriptor` by numeric
800 * value.
801 *
802 * \param desc
803 * The `ProtobufCEnumDescriptor` object.
804 * \param value
805 * The `value` field from the corresponding `ProtobufCEnumValue` object to
806 * match.
807 *
808 * \return
809 * A `ProtobufCEnumValue` object.
810 * \retval NULL
811 * If not found.
812 */
813 PROTOBUF_C__API
814 const ProtobufCEnumValue *
815 protobuf_c_enum_descriptor_get_value(
816 const ProtobufCEnumDescriptor *desc,
817 int value);
818
819 /**
820 * Look up a `ProtobufCFieldDescriptor` from a `ProtobufCMessageDescriptor` by
821 * the name of the field.
822 *
823 * \param desc
824 * The `ProtobufCMessageDescriptor` object.
825 * \param name
826 * The name of the field.
827 * \return
828 * A `ProtobufCFieldDescriptor` object.
829 * \retval NULL
830 * If not found.
831 */
832 PROTOBUF_C__API
833 const ProtobufCFieldDescriptor *
834 protobuf_c_message_descriptor_get_field_by_name(
835 const ProtobufCMessageDescriptor *desc,
836 const char *name);
837
838 /**
839 * Look up a `ProtobufCFieldDescriptor` from a `ProtobufCMessageDescriptor` by
840 * the tag value of the field.
841 *
842 * \param desc
843 * The `ProtobufCMessageDescriptor` object.
844 * \param value
845 * The tag value of the field.
846 * \return
847 * A `ProtobufCFieldDescriptor` object.
848 * \retval NULL
849 * If not found.
850 */
851 PROTOBUF_C__API
852 const ProtobufCFieldDescriptor *
853 protobuf_c_message_descriptor_get_field(
854 const ProtobufCMessageDescriptor *desc,
855 unsigned value);
856
857 /**
858 * Determine the number of bytes required to store the serialised message.
859 *
860 * \param message
861 * The message object to serialise.
862 * \return
863 * Number of bytes.
864 */
865 PROTOBUF_C__API
866 size_t
867 protobuf_c_message_get_packed_size(const ProtobufCMessage *message);
868
869 /**
870 * Serialise a message from its in-memory representation.
871 *
872 * This function stores the serialised bytes of the message in a pre-allocated
873 * buffer.
874 *
875 * \param message
876 * The message object to serialise.
877 * \param[out] out
878 * Buffer to store the bytes of the serialised message. This buffer must
879 * have enough space to store the packed message. Use
880 * protobuf_c_message_get_packed_size() to determine the number of bytes
881 * required.
882 * \return
883 * Number of bytes stored in `out`.
884 */
885 PROTOBUF_C__API
886 size_t
887 protobuf_c_message_pack(const ProtobufCMessage *message, uint8_t *out);
888
889 /**
890 * Serialise a message from its in-memory representation to a virtual buffer.
891 *
892 * This function calls the `append` method of a `ProtobufCBuffer` object to
893 * consume the bytes generated by the serialiser.
894 *
895 * \param message
896 * The message object to serialise.
897 * \param buffer
898 * The virtual buffer object.
899 * \return
900 * Number of bytes passed to the virtual buffer.
901 */
902 PROTOBUF_C__API
903 size_t
904 protobuf_c_message_pack_to_buffer(
905 const ProtobufCMessage *message,
906 ProtobufCBuffer *buffer);
907
908 /**
909 * Unpack a serialised message into an in-memory representation.
910 *
911 * \param descriptor
912 * The message descriptor.
913 * \param allocator
914 * `ProtobufCAllocator` to use for memory allocation. May be NULL to
915 * specify the default allocator.
916 * \param len
917 * Length in bytes of the serialised message.
918 * \param data
919 * Pointer to the serialised message.
920 * \return
921 * An unpacked message object.
922 * \retval NULL
923 * If an error occurred during unpacking.
924 */
925 PROTOBUF_C__API
926 ProtobufCMessage *
927 protobuf_c_message_unpack(
928 const ProtobufCMessageDescriptor *descriptor,
929 ProtobufCAllocator *allocator,
930 size_t len,
931 const uint8_t *data);
932
933 /**
934 * Free an unpacked message object.
935 *
936 * This function should be used to deallocate the memory used by a call to
937 * protobuf_c_message_unpack().
938 *
939 * \param message
940 * The message object to free.
941 * \param allocator
942 * `ProtobufCAllocator` to use for memory deallocation. May be NULL to
943 * specify the default allocator.
944 */
945 PROTOBUF_C__API
946 void
947 protobuf_c_message_free_unpacked(
948 ProtobufCMessage *message,
949 ProtobufCAllocator *allocator);
950
951 /**
952 * Check the validity of a message object.
953 *
954 * Makes sure all required fields (`PROTOBUF_C_LABEL_REQUIRED`) are present.
955 * Recursively checks nested messages.
956 *
957 * \retval TRUE
958 * Message is valid.
959 * \retval FALSE
960 * Message is invalid.
961 */
962 PROTOBUF_C__API
963 protobuf_c_boolean
964 protobuf_c_message_check(const ProtobufCMessage *);
965
966 /** Message initialiser. */
331 #define PROTOBUF_C_MESSAGE_INIT(descriptor) { descriptor, 0, NULL } 967 #define PROTOBUF_C_MESSAGE_INIT(descriptor) { descriptor, 0, NULL }
332 968
333 /* To pack a message: you have two options: 969 /**
334 (1) you can compute the size of the message 970 * Initialise a message object from a message descriptor.
335 using protobuf_c_message_get_packed_size() 971 *
336 then pass protobuf_c_message_pack() a buffer of 972 * \param descriptor
337 that length. 973 * Message descriptor.
338 (2) Provide a virtual buffer (a ProtobufCBuffer) to 974 * \param message
339 accept data as we scan through it. 975 * Allocated block of memory of size `descriptor->sizeof_message`.
340 */ 976 */
341 PROTOBUF_C_API size_t protobuf_c_message_get_packed_size(const ProtobufCMessage *message); 977 PROTOBUF_C__API
342 PROTOBUF_C_API size_t protobuf_c_message_pack (const ProtobufCMessage *message,
343 uint8_t *out);
344 PROTOBUF_C_API size_t protobuf_c_message_pack_to_buffer (const ProtobufCMessage *message,
345 ProtobufCBuffer *buffer);
346
347 PROTOBUF_C_API ProtobufCMessage *
348 protobuf_c_message_unpack (const ProtobufCMessageDescriptor *,
349 ProtobufCAllocator *allocator,
350 size_t len,
351 const uint8_t *data);
352 PROTOBUF_C_API void protobuf_c_message_free_unpacked (ProtobufCMessage *message,
353 ProtobufCAllocator *allocator);
354
355 /* WARNING: 'message' must be a block of memory
356 of size descriptor->sizeof_message. */
357 PROTOBUF_C_API void protobuf_c_message_init (const ProtobufCMessageDescriptor *,
358 void *message);
359
360 /* --- services --- */
361 typedef struct _ProtobufCMethodDescriptor ProtobufCMethodDescriptor;
362 typedef struct _ProtobufCServiceDescriptor ProtobufCServiceDescriptor;
363
364 struct _ProtobufCMethodDescriptor
365 {
366 const char *name;
367 const ProtobufCMessageDescriptor *input;
368 const ProtobufCMessageDescriptor *output;
369 };
370 struct _ProtobufCServiceDescriptor
371 {
372 uint32_t magic;
373
374 const char *name;
375 const char *short_name;
376 const char *c_name;
377 const char *package;
378 unsigned n_methods;
379 const ProtobufCMethodDescriptor *methods; /* in order from .proto file */
380 const unsigned *method_indices_by_name;
381 };
382
383 typedef struct _ProtobufCService ProtobufCService;
384 typedef void (*ProtobufCClosure)(const ProtobufCMessage *message,
385 void *closure_data);
386 struct _ProtobufCService
387 {
388 const ProtobufCServiceDescriptor *descriptor;
389 void (*invoke)(ProtobufCService *service,
390 unsigned method_index,
391 const ProtobufCMessage *input,
392 ProtobufCClosure closure,
393 void *closure_data);
394 void (*destroy) (ProtobufCService *service);
395 };
396
397
398 void protobuf_c_service_destroy (ProtobufCService *);
399
400
401 /* --- querying the descriptors --- */
402 PROTOBUF_C_API const ProtobufCEnumValue *
403 protobuf_c_enum_descriptor_get_value_by_name
404 (const ProtobufCEnumDescriptor *desc,
405 const char *name);
406 PROTOBUF_C_API const ProtobufCEnumValue *
407 protobuf_c_enum_descriptor_get_value
408 (const ProtobufCEnumDescriptor *desc,
409 int value);
410 PROTOBUF_C_API const ProtobufCFieldDescriptor *
411 protobuf_c_message_descriptor_get_field_by_name
412 (const ProtobufCMessageDescriptor *desc,
413 const char *name);
414 PROTOBUF_C_API const ProtobufCFieldDescriptor *
415 protobuf_c_message_descriptor_get_field
416 (const ProtobufCMessageDescriptor *desc,
417 unsigned value);
418 PROTOBUF_C_API const ProtobufCMethodDescriptor *
419 protobuf_c_service_descriptor_get_method_by_name
420 (const ProtobufCServiceDescriptor *desc,
421 const char *name);
422
423 /* --- wire format enums --- */
424 typedef enum
425 {
426 PROTOBUF_C_WIRE_TYPE_VARINT,
427 PROTOBUF_C_WIRE_TYPE_64BIT,
428 PROTOBUF_C_WIRE_TYPE_LENGTH_PREFIXED,
429 PROTOBUF_C_WIRE_TYPE_START_GROUP, /* unsupported */
430 PROTOBUF_C_WIRE_TYPE_END_GROUP, /* unsupported */
431 PROTOBUF_C_WIRE_TYPE_32BIT
432 } ProtobufCWireType;
433
434 /* --- unknown message fields --- */
435 struct _ProtobufCMessageUnknownField
436 {
437 uint32_t tag;
438 ProtobufCWireType wire_type;
439 size_t len;
440 uint8_t *data;
441 };
442
443 /* --- extra (superfluous) api: trivial buffer --- */
444 typedef struct _ProtobufCBufferSimple ProtobufCBufferSimple;
445 struct _ProtobufCBufferSimple
446 {
447 ProtobufCBuffer base;
448 size_t alloced;
449 size_t len;
450 uint8_t *data;
451 protobuf_c_boolean must_free_data;
452 };
453 #define PROTOBUF_C_BUFFER_SIMPLE_INIT(array_of_bytes) \
454 { { protobuf_c_buffer_simple_append }, \
455 sizeof(array_of_bytes), 0, (array_of_bytes), 0 }
456 #define PROTOBUF_C_BUFFER_SIMPLE_CLEAR(simp_buf) \
457 do { if ((simp_buf)->must_free_data) \
458 protobuf_c_default_allocator.free (&protobuf_c_default_allocator.allocator_data, (simp_buf)->data); } while (0)
459
460
461 typedef enum
462 {
463 PROTOBUF_C_CTYPE_INT32,
464 PROTOBUF_C_CTYPE_UINT32,
465 PROTOBUF_C_CTYPE_INT64,
466 PROTOBUF_C_CTYPE_UINT64,
467 PROTOBUF_C_CTYPE_FLOAT,
468 PROTOBUF_C_CTYPE_DOUBLE,
469 PROTOBUF_C_CTYPE_BOOL,
470 PROTOBUF_C_CTYPE_ENUM,
471 PROTOBUF_C_CTYPE_STRING,
472 PROTOBUF_C_CTYPE_BYTES,
473 PROTOBUF_C_CTYPE_MESSAGE,
474 } ProtobufCCType;
475
476 extern ProtobufCCType protobuf_c_type_to_ctype (ProtobufCType type);
477 #define protobuf_c_type_to_ctype(type) \
478 ((ProtobufCCType)(protobuf_c_type_to_ctype_array[(type)]))
479
480 /* ====== private ====== */
481
482 /* A little enum helper macro: this will ensure that your
483 enum's size is sizeof(int). In protobuf, it need not
484 be larger than 32-bits.
485
486 This is written assuming it is appended to a list w/o a tail comma. */
487 #ifndef _PROTOBUF_C_FORCE_ENUM_TO_BE_INT_SIZE
488 #define _PROTOBUF_C_FORCE_ENUM_TO_BE_INT_SIZE(enum_name) \
489 , _##enum_name##_IS_INT_SIZE = INT_MAX
490 #endif
491
492 /* === needs to be declared for the PROTOBUF_C_BUFFER_SIMPLE_INIT macro === */
493
494 void protobuf_c_buffer_simple_append (ProtobufCBuffer *buffer,
495 size_t len,
496 const unsigned char *data);
497
498 /* === stuff which needs to be declared for use in the generated code === */
499
500 struct _ProtobufCEnumValueIndex
501 {
502 const char *name;
503 unsigned index; /* into values[] array */
504 };
505
506 /* IntRange: helper structure for optimizing
507 int => index lookups
508 in the case where the keys are mostly consecutive values,
509 as they presumably are for enums and fields.
510
511 The data structures assumes that the values in the original
512 array are sorted */
513 struct _ProtobufCIntRange
514 {
515 int start_value;
516 unsigned orig_index;
517 /* NOTE: the number of values in the range can
518 be inferred by looking at the next element's orig_index.
519 a dummy element is added to make this simple */
520 };
521
522
523 /* === declared for exposition on ProtobufCIntRange === */
524 /* note: ranges must have an extra sentinel IntRange at the end whose
525 orig_index is set to the number of actual values in the original array */
526 /* returns -1 if no orig_index found */
527 int protobuf_c_int_ranges_lookup (unsigned n_ranges,
528 ProtobufCIntRange *ranges);
529
530 #define PROTOBUF_C_SERVICE_DESCRIPTOR_MAGIC 0x14159bc3
531 #define PROTOBUF_C_MESSAGE_DESCRIPTOR_MAGIC 0x28aaeef9
532 #define PROTOBUF_C_ENUM_DESCRIPTOR_MAGIC 0x114315af
533
534 /* === behind the scenes on the generated service's __init functions */
535 typedef void (*ProtobufCServiceDestroy) (ProtobufCService *service);
536 void 978 void
537 protobuf_c_service_generated_init (ProtobufCService *service, 979 protobuf_c_message_init(
538 const ProtobufCServiceDescriptor *descriptor, 980 const ProtobufCMessageDescriptor *descriptor,
539 ProtobufCServiceDestroy destroy); 981 void *message);
540 982
541 void 983 /**
542 protobuf_c_service_invoke_internal(ProtobufCService *service, 984 * Free a service.
543 unsigned method_index, 985 *
544 const ProtobufCMessage *input, 986 * \param service
545 ProtobufCClosure closure, 987 * The service object to free.
546 void *closure_data); 988 */
547 989 PROTOBUF_C__API
548 990 void
549 991 protobuf_c_service_destroy(ProtobufCService *service);
550 PROTOBUF_C_END_DECLS 992
551 993 /**
552 #endif /* __PROTOBUF_C_RUNTIME_H_ */ 994 * Look up a `ProtobufCMethodDescriptor` by name.
995 *
996 * \param desc
997 * Service descriptor.
998 * \param name
999 * Name of the method.
1000 *
1001 * \return
1002 * A `ProtobufCMethodDescriptor` object.
1003 * \retval NULL
1004 * If not found.
1005 */
1006 PROTOBUF_C__API
1007 const ProtobufCMethodDescriptor *
1008 protobuf_c_service_descriptor_get_method_by_name(
1009 const ProtobufCServiceDescriptor *desc,
1010 const char *name);
1011
1012 /**
1013 * Initialise a `ProtobufCBufferSimple` object.
1014 */
1015 #define PROTOBUF_C_BUFFER_SIMPLE_INIT(array_of_bytes) \
1016 { \
1017 { protobuf_c_buffer_simple_append }, \
1018 sizeof(array_of_bytes), \
1019 0, \
1020 (array_of_bytes), \
1021 0, \
1022 NULL \
1023 }
1024
1025 /**
1026 * Clear a `ProtobufCBufferSimple` object, freeing any allocated memory.
1027 */
1028 #define PROTOBUF_C_BUFFER_SIMPLE_CLEAR(simp_buf) \
1029 do { \
1030 if ((simp_buf)->must_free_data) { \
1031 if ((simp_buf)->allocator != NULL) \
1032 (simp_buf)->allocator->free( \
1033 (simp_buf)->allocator, \
1034 (simp_buf)->data); \
1035 else \
1036 free((simp_buf)->data); \
1037 } \
1038 } while (0)
1039
1040 /**
1041 * The `append` method for `ProtobufCBufferSimple`.
1042 *
1043 * \param buffer
1044 * The buffer object to append to. Must actually be a
1045 * `ProtobufCBufferSimple` object.
1046 * \param len
1047 * Number of bytes in `data`.
1048 * \param data
1049 * Data to append.
1050 */
1051 PROTOBUF_C__API
1052 void
1053 protobuf_c_buffer_simple_append(
1054 ProtobufCBuffer *buffer,
1055 size_t len,
1056 const unsigned char *data);
1057
1058 PROTOBUF_C__API
1059 void
1060 protobuf_c_service_generated_init(
1061 ProtobufCService *service,
1062 const ProtobufCServiceDescriptor *descriptor,
1063 ProtobufCServiceDestroy destroy);
1064
1065 PROTOBUF_C__API
1066 void
1067 protobuf_c_service_invoke_internal(
1068 ProtobufCService *service,
1069 unsigned method_index,
1070 const ProtobufCMessage *input,
1071 ProtobufCClosure closure,
1072 void *closure_data);
1073
1074 /**@}*/
1075
1076 PROTOBUF_C__END_DECLS
1077
1078 #endif /* PROTOBUF_C_H */

Mercurial Repository: pidgin3

mercurial