1 |
/* --- protobuf-c.h: public protobuf c runtime api --- */
|
2 |
|
3 |
/*
|
4 |
* Copyright 2008, Dave Benson.
|
5 |
*
|
6 |
* Licensed under the Apache License, Version 2.0 (the "License");
|
7 |
* you may not use this file except in compliance with
|
8 |
* the License. You may obtain a copy of the License
|
9 |
* at http://www.apache.org/licenses/LICENSE-2.0 Unless
|
10 |
* required by applicable law or agreed to in writing,
|
11 |
* software distributed under the License is distributed on
|
12 |
* an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
13 |
* KIND, either express or implied. See the License for the
|
14 |
* specific language governing permissions and limitations
|
15 |
* under the License.
|
16 |
*/
|
17 |
|
18 |
#ifndef __PROTOBUF_C_RUNTIME_H_
|
19 |
#define __PROTOBUF_C_RUNTIME_H_
|
20 |
|
21 |
#include <stddef.h>
|
22 |
#include <assert.h>
|
23 |
|
24 |
#ifdef __cplusplus
|
25 |
# define PROTOBUF_C_BEGIN_DECLS extern "C" {
|
26 |
# define PROTOBUF_C_END_DECLS }
|
27 |
#else
|
28 |
# define PROTOBUF_C_BEGIN_DECLS
|
29 |
# define PROTOBUF_C_END_DECLS
|
30 |
#endif
|
31 |
|
32 |
#if !defined(PROTOBUF_C_NO_DEPRECATED) && (__GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1))
|
33 |
#define PROTOBUF_C_DEPRECATED __attribute__((__deprecated__))
|
34 |
#else
|
35 |
#define PROTOBUF_C_DEPRECATED
|
36 |
#endif
|
37 |
|
38 |
/* Define int32_t, int64_t, uint32_t, uint64_t, uint8_t.
|
39 |
|
40 |
Usually, just include <inttypes.h> to do the work.
|
41 |
XXX: should we use stdint.h?
|
42 |
*/
|
43 |
#ifndef PROTOBUF_C_SKIP_INTTYPES_H
|
44 |
# if defined(_MSC_VER)
|
45 |
/* On windows, in ms visual studio, define the types ourselves */
|
46 |
# define int32_t signed __int32
|
47 |
# define uint32_t unsigned __int32
|
48 |
# define int64_t signed __int64
|
49 |
# define uint64_t unsigned __int64
|
50 |
# define uint8_t unsigned char
|
51 |
# else
|
52 |
/* Use the system inttypes.h */
|
53 |
# include <inttypes.h>
|
54 |
# endif
|
55 |
#endif
|
56 |
|
57 |
PROTOBUF_C_BEGIN_DECLS
|
58 |
|
59 |
typedef enum
|
60 |
{
|
61 |
PROTOBUF_C_LABEL_REQUIRED,
|
62 |
PROTOBUF_C_LABEL_OPTIONAL,
|
63 |
PROTOBUF_C_LABEL_REPEATED
|
64 |
} ProtobufCLabel;
|
65 |
|
66 |
typedef enum
|
67 |
{
|
68 |
PROTOBUF_C_TYPE_INT32,
|
69 |
PROTOBUF_C_TYPE_SINT32,
|
70 |
PROTOBUF_C_TYPE_SFIXED32,
|
71 |
PROTOBUF_C_TYPE_INT64,
|
72 |
PROTOBUF_C_TYPE_SINT64,
|
73 |
PROTOBUF_C_TYPE_SFIXED64,
|
74 |
PROTOBUF_C_TYPE_UINT32,
|
75 |
PROTOBUF_C_TYPE_FIXED32,
|
76 |
PROTOBUF_C_TYPE_UINT64,
|
77 |
PROTOBUF_C_TYPE_FIXED64,
|
78 |
PROTOBUF_C_TYPE_FLOAT,
|
79 |
PROTOBUF_C_TYPE_DOUBLE,
|
80 |
PROTOBUF_C_TYPE_BOOL,
|
81 |
PROTOBUF_C_TYPE_ENUM,
|
82 |
PROTOBUF_C_TYPE_STRING,
|
83 |
PROTOBUF_C_TYPE_BYTES,
|
84 |
//PROTOBUF_C_TYPE_GROUP, // NOT SUPPORTED
|
85 |
PROTOBUF_C_TYPE_MESSAGE,
|
86 |
} ProtobufCType;
|
87 |
|
88 |
typedef int protobuf_c_boolean;
|
89 |
#define PROTOBUF_C_OFFSETOF(struct, member) offsetof(struct, member)
|
90 |
|
91 |
#define PROTOBUF_C_ASSERT(condition) assert(condition)
|
92 |
#define PROTOBUF_C_ASSERT_NOT_REACHED() assert(0)
|
93 |
|
94 |
typedef struct _ProtobufCBinaryData ProtobufCBinaryData;
|
95 |
struct _ProtobufCBinaryData
|
96 |
{
|
97 |
size_t len;
|
98 |
uint8_t *data;
|
99 |
};
|
100 |
|
101 |
typedef struct _ProtobufCIntRange ProtobufCIntRange; /* private */
|
102 |
|
103 |
/* --- memory management --- */
|
104 |
typedef struct _ProtobufCAllocator ProtobufCAllocator;
|
105 |
struct _ProtobufCAllocator
|
106 |
{
|
107 |
void *(*alloc)(void *allocator_data, size_t size);
|
108 |
void (*free)(void *allocator_data, void *pointer);
|
109 |
void *(*tmp_alloc)(void *allocator_data, size_t size);
|
110 |
unsigned max_alloca;
|
111 |
void *allocator_data;
|
112 |
};
|
113 |
|
114 |
/* This is a configurable allocator.
|
115 |
* By default, it uses the system allocator (meaning malloc() and free()).
|
116 |
* This is typically changed to adapt to frameworks that provide
|
117 |
* some nonstandard allocation functions.
|
118 |
*
|
119 |
* NOTE: you may modify this allocator.
|
120 |
*/
|
121 |
extern ProtobufCAllocator protobuf_c_default_allocator; /* settable */
|
122 |
|
123 |
/* This is the system allocator, meaning it uses malloc() and free().
|
124 |
*
|
125 |
* NOTE: please do NOT modify this allocator.
|
126 |
*/
|
127 |
extern ProtobufCAllocator protobuf_c_system_allocator; /* use malloc, free etc */
|
128 |
|
129 |
/* This is the function that our default allocators call when they
|
130 |
run out-of-memory. The default behavior of this function is to
|
131 |
terminate your program. */
|
132 |
extern void (*protobuf_c_out_of_memory) (void);
|
133 |
|
134 |
/* --- append-only data buffer --- */
|
135 |
typedef struct _ProtobufCBuffer ProtobufCBuffer;
|
136 |
struct _ProtobufCBuffer
|
137 |
{
|
138 |
void (*append)(ProtobufCBuffer *buffer,
|
139 |
size_t len,
|
140 |
const uint8_t *data);
|
141 |
};
|
142 |
/* --- enums --- */
|
143 |
typedef struct _ProtobufCEnumValue ProtobufCEnumValue;
|
144 |
typedef struct _ProtobufCEnumValueIndex ProtobufCEnumValueIndex;
|
145 |
typedef struct _ProtobufCEnumDescriptor ProtobufCEnumDescriptor;
|
146 |
|
147 |
/* ProtobufCEnumValue: this represents a single value of
|
148 |
* an enumeration.
|
149 |
* 'name' is the string identifying this value, as given in the .proto file.
|
150 |
* 'c_name' is the full name of the C enumeration value.
|
151 |
* 'value' is the number assigned to this value, as given in the .proto file.
|
152 |
*/
|
153 |
struct _ProtobufCEnumValue
|
154 |
{
|
155 |
const char *name;
|
156 |
const char *c_name;
|
157 |
int value;
|
158 |
};
|
159 |
|
160 |
/* ProtobufCEnumDescriptor: the represents the enum as a whole,
|
161 |
* with all its values.
|
162 |
* 'magic' is a code we check to ensure that the api is used correctly.
|
163 |
* 'name' is the qualified name (e.g. "namespace.Type").
|
164 |
* 'short_name' is the unqualified name ("Type"), as given in the .proto file.
|
165 |
* 'package_name' is the '.'-separated namespace
|
166 |
* 'n_values' is the number of distinct values.
|
167 |
* 'values' is the array of distinct values.
|
168 |
* 'n_value_names' number of named values (including aliases).
|
169 |
* 'value_names' are the named values (including aliases).
|
170 |
*
|
171 |
* The rest of the values are private essentially.
|
172 |
*
|
173 |
* see also: Use protobuf_c_enum_descriptor_get_value_by_name()
|
174 |
* and protobuf_c_enum_descriptor_get_value() to efficiently
|
175 |
* lookup values in the descriptor.
|
176 |
*/
|
177 |
struct _ProtobufCEnumDescriptor
|
178 |
{
|
179 |
uint32_t magic;
|
180 |
|
181 |
const char *name;
|
182 |
const char *short_name;
|
183 |
const char *c_name;
|
184 |
const char *package_name;
|
185 |
|
186 |
/* sorted by value */
|
187 |
unsigned n_values;
|
188 |
const ProtobufCEnumValue *values;
|
189 |
|
190 |
/* sorted by name */
|
191 |
unsigned n_value_names;
|
192 |
const ProtobufCEnumValueIndex *values_by_name;
|
193 |
|
194 |
/* value-ranges, for faster lookups by number */
|
195 |
unsigned n_value_ranges;
|
196 |
const ProtobufCIntRange *value_ranges;
|
197 |
|
198 |
void *reserved1;
|
199 |
void *reserved2;
|
200 |
void *reserved3;
|
201 |
void *reserved4;
|
202 |
};
|
203 |
|
204 |
/* --- messages --- */
|
205 |
typedef struct _ProtobufCMessageDescriptor ProtobufCMessageDescriptor;
|
206 |
typedef struct _ProtobufCFieldDescriptor ProtobufCFieldDescriptor;
|
207 |
typedef struct _ProtobufCMessage ProtobufCMessage;
|
208 |
typedef void (*ProtobufCMessageInit)(ProtobufCMessage *);
|
209 |
/* ProtobufCFieldDescriptor: description of a single field
|
210 |
* in a message.
|
211 |
* 'name' is the name of the field, as given in the .proto file.
|
212 |
* 'id' is the code representing the field, as given in the .proto file.
|
213 |
* 'label' is one of PROTOBUF_C_LABEL_{REQUIRED,OPTIONAL,REPEATED}
|
214 |
* 'type' is the type of field.
|
215 |
* 'quantifier_offset' is the offset in bytes into the message's C structure
|
216 |
* for this member's "has_MEMBER" field (for optional members) or
|
217 |
* "n_MEMBER" field (for repeated members).
|
218 |
* 'offset' is the offset in bytes into the message's C structure
|
219 |
* for the member itself.
|
220 |
* 'descriptor' is a pointer to a ProtobufC{Enum,Message}Descriptor
|
221 |
* if type is PROTOBUF_C_TYPE_{ENUM,MESSAGE} respectively,
|
222 |
* otherwise NULL.
|
223 |
* 'default_value' is a pointer to a default value for this field,
|
224 |
* where allowed.
|
225 |
*/
|
226 |
struct _ProtobufCFieldDescriptor
|
227 |
{
|
228 |
const char *name;
|
229 |
uint32_t id;
|
230 |
ProtobufCLabel label;
|
231 |
ProtobufCType type;
|
232 |
unsigned quantifier_offset;
|
233 |
unsigned offset;
|
234 |
const void *descriptor; /* for MESSAGE and ENUM types */
|
235 |
const void *default_value; /* or NULL if no default-value */
|
236 |
protobuf_c_boolean packed;
|
237 |
|
238 |
unsigned reserved_flags;
|
239 |
void *reserved2;
|
240 |
void *reserved3;
|
241 |
};
|
242 |
/* ProtobufCMessageDescriptor: description of a message.
|
243 |
*
|
244 |
* 'magic' is a code we check to ensure that the api is used correctly.
|
245 |
* 'name' is the qualified name (e.g. "namespace.Type").
|
246 |
* 'short_name' is the unqualified name ("Type"), as given in the .proto file.
|
247 |
* 'c_name' is the c-formatted name of the structure
|
248 |
* 'package_name' is the '.'-separated namespace
|
249 |
* 'sizeof_message' is the size in bytes of the C structure
|
250 |
* representing an instance of this type of message.
|
251 |
* 'n_fields' is the number of known fields in this message.
|
252 |
* 'fields' is the fields sorted by id number.
|
253 |
* 'fields_sorted_by_name', 'n_field_ranges' and 'field_ranges'
|
254 |
* are used for looking up fields by name and id. (private)
|
255 |
*/
|
256 |
struct _ProtobufCMessageDescriptor
|
257 |
{
|
258 |
uint32_t magic;
|
259 |
|
260 |
const char *name;
|
261 |
const char *short_name;
|
262 |
const char *c_name;
|
263 |
const char *package_name;
|
264 |
|
265 |
size_t sizeof_message;
|
266 |
|
267 |
/* sorted by field-id */
|
268 |
unsigned n_fields;
|
269 |
const ProtobufCFieldDescriptor *fields;
|
270 |
const unsigned *fields_sorted_by_name;
|
271 |
|
272 |
/* ranges, optimization for looking up fields */
|
273 |
unsigned n_field_ranges;
|
274 |
const ProtobufCIntRange *field_ranges;
|
275 |
|
276 |
ProtobufCMessageInit message_init;
|
277 |
void *reserved1;
|
278 |
void *reserved2;
|
279 |
void *reserved3;
|
280 |
};
|
281 |
|
282 |
|
283 |
/* ProtobufCMessage: an instance of a message.
|
284 |
*
|
285 |
* ProtobufCMessage is sort-of a lightweight
|
286 |
* base-class for all messages.
|
287 |
*
|
288 |
* In particular, ProtobufCMessage doesn't have
|
289 |
* any allocation policy associated with it.
|
290 |
* That's because it is common to create ProtobufCMessage's
|
291 |
* on the stack. In fact, we that's what we recommend
|
292 |
* for sending messages (because if you just allocate from the
|
293 |
* stack, then you can't really have a memory leak).
|
294 |
*
|
295 |
* This means that functions like protobuf_c_message_unpack()
|
296 |
* which return a ProtobufCMessage must be paired
|
297 |
* with a free function, like protobuf_c_message_free_unpacked().
|
298 |
*
|
299 |
* 'descriptor' gives the locations and types of the members of message
|
300 |
* 'n_unknown_fields' is the number of fields we didn't recognize.
|
301 |
* 'unknown_fields' are fields we didn't recognize.
|
302 |
*/
|
303 |
typedef struct _ProtobufCMessageUnknownField ProtobufCMessageUnknownField;
|
304 |
struct _ProtobufCMessage
|
305 |
{
|
306 |
const ProtobufCMessageDescriptor *descriptor;
|
307 |
unsigned n_unknown_fields;
|
308 |
ProtobufCMessageUnknownField *unknown_fields;
|
309 |
};
|
310 |
#define PROTOBUF_C_MESSAGE_INIT(descriptor) { descriptor, 0, NULL }
|
311 |
|
312 |
/* To pack a message: you have two options:
|
313 |
(1) you can compute the size of the message
|
314 |
using protobuf_c_message_get_packed_size()
|
315 |
then pass protobuf_c_message_pack() a buffer of
|
316 |
that length.
|
317 |
(2) Provide a virtual buffer (a ProtobufCBuffer) to
|
318 |
accept data as we scan through it.
|
319 |
*/
|
320 |
size_t protobuf_c_message_get_packed_size(const ProtobufCMessage *message);
|
321 |
size_t protobuf_c_message_pack (const ProtobufCMessage *message,
|
322 |
uint8_t *out);
|
323 |
size_t protobuf_c_message_pack_to_buffer (const ProtobufCMessage *message,
|
324 |
ProtobufCBuffer *buffer);
|
325 |
|
326 |
ProtobufCMessage *
|
327 |
protobuf_c_message_unpack (const ProtobufCMessageDescriptor *,
|
328 |
ProtobufCAllocator *allocator,
|
329 |
size_t len,
|
330 |
const uint8_t *data);
|
331 |
void protobuf_c_message_free_unpacked (ProtobufCMessage *message,
|
332 |
ProtobufCAllocator *allocator);
|
333 |
|
334 |
/* WARNING: 'message' must be a block of memory
|
335 |
of size descriptor->sizeof_message. */
|
336 |
#define protobuf_c_message_init(descriptor, message) ((descriptor)->message_init((ProtobufCMessage*) (message)))
|
337 |
|
338 |
/* --- services --- */
|
339 |
typedef struct _ProtobufCMethodDescriptor ProtobufCMethodDescriptor;
|
340 |
typedef struct _ProtobufCServiceDescriptor ProtobufCServiceDescriptor;
|
341 |
|
342 |
struct _ProtobufCMethodDescriptor
|
343 |
{
|
344 |
const char *name;
|
345 |
const ProtobufCMessageDescriptor *input;
|
346 |
const ProtobufCMessageDescriptor *output;
|
347 |
};
|
348 |
struct _ProtobufCServiceDescriptor
|
349 |
{
|
350 |
uint32_t magic;
|
351 |
|
352 |
const char *name;
|
353 |
const char *short_name;
|
354 |
const char *c_name;
|
355 |
const char *package;
|
356 |
unsigned n_methods;
|
357 |
const ProtobufCMethodDescriptor *methods; /* in order from .proto file */
|
358 |
const unsigned *method_indices_by_name;
|
359 |
};
|
360 |
|
361 |
typedef struct _ProtobufCService ProtobufCService;
|
362 |
typedef void (*ProtobufCClosure)(const ProtobufCMessage *message,
|
363 |
void *closure_data);
|
364 |
struct _ProtobufCService
|
365 |
{
|
366 |
const ProtobufCServiceDescriptor *descriptor;
|
367 |
void (*invoke)(ProtobufCService *service,
|
368 |
unsigned method_index,
|
369 |
const ProtobufCMessage *input,
|
370 |
ProtobufCClosure closure,
|
371 |
void *closure_data);
|
372 |
void (*destroy) (ProtobufCService *service);
|
373 |
};
|
374 |
|
375 |
|
376 |
void protobuf_c_service_destroy (ProtobufCService *);
|
377 |
|
378 |
|
379 |
/* --- querying the descriptors --- */
|
380 |
const ProtobufCEnumValue *
|
381 |
protobuf_c_enum_descriptor_get_value_by_name
|
382 |
(const ProtobufCEnumDescriptor *desc,
|
383 |
const char *name);
|
384 |
const ProtobufCEnumValue *
|
385 |
protobuf_c_enum_descriptor_get_value
|
386 |
(const ProtobufCEnumDescriptor *desc,
|
387 |
int value);
|
388 |
const ProtobufCFieldDescriptor *
|
389 |
protobuf_c_message_descriptor_get_field_by_name
|
390 |
(const ProtobufCMessageDescriptor *desc,
|
391 |
const char *name);
|
392 |
const ProtobufCFieldDescriptor *
|
393 |
protobuf_c_message_descriptor_get_field
|
394 |
(const ProtobufCMessageDescriptor *desc,
|
395 |
unsigned value);
|
396 |
const ProtobufCMethodDescriptor *
|
397 |
protobuf_c_service_descriptor_get_method_by_name
|
398 |
(const ProtobufCServiceDescriptor *desc,
|
399 |
const char *name);
|
400 |
|
401 |
/* --- wire format enums --- */
|
402 |
typedef enum
|
403 |
{
|
404 |
PROTOBUF_C_WIRE_TYPE_VARINT,
|
405 |
PROTOBUF_C_WIRE_TYPE_64BIT,
|
406 |
PROTOBUF_C_WIRE_TYPE_LENGTH_PREFIXED,
|
407 |
PROTOBUF_C_WIRE_TYPE_START_GROUP, /* unsupported */
|
408 |
PROTOBUF_C_WIRE_TYPE_END_GROUP, /* unsupported */
|
409 |
PROTOBUF_C_WIRE_TYPE_32BIT
|
410 |
} ProtobufCWireType;
|
411 |
|
412 |
/* --- unknown message fields --- */
|
413 |
struct _ProtobufCMessageUnknownField
|
414 |
{
|
415 |
uint32_t tag;
|
416 |
ProtobufCWireType wire_type;
|
417 |
size_t len;
|
418 |
uint8_t *data;
|
419 |
};
|
420 |
|
421 |
/* --- extra (superfluous) api: trivial buffer --- */
|
422 |
typedef struct _ProtobufCBufferSimple ProtobufCBufferSimple;
|
423 |
struct _ProtobufCBufferSimple
|
424 |
{
|
425 |
ProtobufCBuffer base;
|
426 |
size_t alloced;
|
427 |
size_t len;
|
428 |
uint8_t *data;
|
429 |
protobuf_c_boolean must_free_data;
|
430 |
};
|
431 |
#define PROTOBUF_C_BUFFER_SIMPLE_INIT(array_of_bytes) \
|
432 |
{ { protobuf_c_buffer_simple_append }, \
|
433 |
sizeof(array_of_bytes), 0, (array_of_bytes), 0 }
|
434 |
#define PROTOBUF_C_BUFFER_SIMPLE_CLEAR(simp_buf) \
|
435 |
do { if ((simp_buf)->must_free_data) \
|
436 |
protobuf_c_default_allocator.free (&protobuf_c_default_allocator.allocator_data, (simp_buf)->data); } while (0)
|
437 |
|
438 |
/* ====== private ====== */
|
439 |
#include "protobuf-c-private.h"
|
440 |
|
441 |
|
442 |
PROTOBUF_C_END_DECLS
|
443 |
|
444 |
#endif /* __PROTOBUF_C_RUNTIME_H_ */
|