1 /* --- protobuf-c.h: public protobuf c runtime api --- */
4 * Copyright 2008, Dave Benson.
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
18 #ifndef __PROTOBUF_C_RUNTIME_H_
19 #define __PROTOBUF_C_RUNTIME_H_
26 # define PROTOBUF_C_BEGIN_DECLS extern "C" {
27 # define PROTOBUF_C_END_DECLS }
29 # define PROTOBUF_C_BEGIN_DECLS
30 # define PROTOBUF_C_END_DECLS
33 PROTOBUF_C_BEGIN_DECLS
37 PROTOBUF_C_LABEL_REQUIRED,
38 PROTOBUF_C_LABEL_OPTIONAL,
39 PROTOBUF_C_LABEL_REPEATED
44 PROTOBUF_C_TYPE_INT32,
45 PROTOBUF_C_TYPE_SINT32,
46 PROTOBUF_C_TYPE_SFIXED32,
47 PROTOBUF_C_TYPE_INT64,
48 PROTOBUF_C_TYPE_SINT64,
49 PROTOBUF_C_TYPE_SFIXED64,
50 PROTOBUF_C_TYPE_UINT32,
51 PROTOBUF_C_TYPE_FIXED32,
52 PROTOBUF_C_TYPE_UINT64,
53 PROTOBUF_C_TYPE_FIXED64,
54 PROTOBUF_C_TYPE_FLOAT,
55 PROTOBUF_C_TYPE_DOUBLE,
58 PROTOBUF_C_TYPE_STRING,
59 PROTOBUF_C_TYPE_BYTES,
60 //PROTOBUF_C_TYPE_GROUP, // NOT SUPPORTED
61 PROTOBUF_C_TYPE_MESSAGE,
64 typedef int protobuf_c_boolean;
65 #define PROTOBUF_C_OFFSETOF(struct, member) offsetof(struct, member)
67 #define PROTOBUF_C_ASSERT(condition) assert(condition)
68 #define PROTOBUF_C_ASSERT_NOT_REACHED() assert(0)
70 typedef struct _ProtobufCBinaryData ProtobufCBinaryData;
71 struct _ProtobufCBinaryData
77 typedef struct _ProtobufCIntRange ProtobufCIntRange; /* private */
79 /* --- memory management --- */
80 typedef struct _ProtobufCAllocator ProtobufCAllocator;
81 struct _ProtobufCAllocator
83 void *(*alloc)(void *allocator_data, size_t size);
84 void (*free)(void *allocator_data, void *pointer);
85 void *(*tmp_alloc)(void *allocator_data, size_t size);
90 /* This is a configurable allocator.
91 * By default, it uses the system allocator (meaning malloc() and free()).
92 * This is typically done to incorporate into frameworks that provide
93 * some nonstandard allocation functions.
95 extern ProtobufCAllocator protobuf_c_default_allocator; /* settable */
97 /* This is the system allocator, meaning it uses malloc() and free() */
98 extern ProtobufCAllocator protobuf_c_system_allocator; /* use malloc, free etc */
100 /* This is the function that our default allocators call when they
101 run out-of-memory. The default behavior of this function is to
102 terminate your program. */
103 extern void (*protobuf_c_out_of_memory) (void);
105 /* --- append-only data buffer --- */
106 typedef struct _ProtobufCBuffer ProtobufCBuffer;
107 struct _ProtobufCBuffer
109 void (*append)(ProtobufCBuffer *buffer,
111 const uint8_t *data);
114 typedef struct _ProtobufCEnumValue ProtobufCEnumValue;
115 typedef struct _ProtobufCEnumValueIndex ProtobufCEnumValueIndex;
116 typedef struct _ProtobufCEnumDescriptor ProtobufCEnumDescriptor;
118 /* ProtobufCEnumValue: this represents a single value of
120 * 'name' is the string identifying this value, as given in the .proto file.
121 * 'c_name' is the full name of the C enumeration value.
122 * 'value' is the number assigned to this value, as given in the .proto file.
124 struct _ProtobufCEnumValue
131 /* ProtobufCEnumDescriptor: the represents the enum as a whole,
132 * with all its values.
133 * 'magic' is a code we check to ensure that the api is used correctly.
134 * 'name' is the qualified name (e.g. "namespace.Type").
135 * 'short_name' is the unqualified name ("Type"), as given in the .proto file.
136 * 'package_name' is the '.'-separated namespace
137 * 'n_values' is the number of distinct values.
138 * 'values' is the array of distinct values.
139 * 'n_value_names' number of named values (including aliases).
140 * 'value_names' are the named values (including aliases).
142 * The rest of the values are private essentially.
144 * see also: Use protobuf_c_enum_descriptor_get_value_by_name()
145 * and protobuf_c_enum_descriptor_get_value() to efficiently
146 * lookup values in the descriptor.
148 struct _ProtobufCEnumDescriptor
153 const char *short_name;
155 const char *package_name;
157 /* sorted by value */
159 const ProtobufCEnumValue *values;
162 unsigned n_value_names;
163 const ProtobufCEnumValueIndex *values_by_name;
165 /* value-ranges, for faster lookups by number */
166 unsigned n_value_ranges;
167 const ProtobufCIntRange *value_ranges;
175 /* --- messages --- */
176 typedef struct _ProtobufCMessageDescriptor ProtobufCMessageDescriptor;
177 typedef struct _ProtobufCFieldDescriptor ProtobufCFieldDescriptor;
178 /* ProtobufCFieldDescriptor: description of a single field
180 * 'name' is the name of the field, as given in the .proto file.
181 * 'id' is the code representing the field, as given in the .proto file.
182 * 'label' is one of PROTOBUF_C_LABEL_{REQUIRED,OPTIONAL,REPEATED}
183 * 'type' is the type of field.
184 * 'quantifier_offset' is the offset in bytes into the message's C structure
185 * for this member's "has_MEMBER" field (for optional members) or
186 * "n_MEMBER" field (for repeated members).
187 * 'offset' is the offset in bytes into the message's C structure
188 * for the member itself.
189 * 'descriptor' is a pointer to a ProtobufC{Enum,Message}Descriptor
190 * if type is PROTOBUF_C_TYPE_{ENUM,MESSAGE} respectively,
192 * 'default_value' is a pointer to a default value for this field,
195 struct _ProtobufCFieldDescriptor
199 ProtobufCLabel label;
201 unsigned quantifier_offset;
203 const void *descriptor; /* for MESSAGE and ENUM types */
204 const void *default_value; /* or NULL if no default-value */
209 /* ProtobufCMessageDescriptor: description of a message.
211 * 'magic' is a code we check to ensure that the api is used correctly.
212 * 'name' is the qualified name (e.g. "namespace.Type").
213 * 'short_name' is the unqualified name ("Type"), as given in the .proto file.
214 * 'c_name' is the c-formatted name of the structure
215 * 'package_name' is the '.'-separated namespace
216 * 'sizeof_message' is the size in bytes of the C structure
217 * representing an instance of this type of message.
218 * 'n_fields' is the number of known fields in this message.
219 * 'fields' is the fields sorted by id number.
220 * 'fields_sorted_by_name', 'n_field_ranges' and 'field_ranges'
221 * are used for looking up fields by name and id. (private)
223 struct _ProtobufCMessageDescriptor
228 const char *short_name;
230 const char *package_name;
232 size_t sizeof_message;
234 /* sorted by field-id */
236 const ProtobufCFieldDescriptor *fields;
237 const unsigned *fields_sorted_by_name;
239 /* ranges, optimization for looking up fields */
240 unsigned n_field_ranges;
241 const ProtobufCIntRange *field_ranges;
250 /* ProtobufCMessage: an instance of a message.
252 * ProtobufCMessage is sort-of a lightweight
253 * base-class for all messages.
255 * In particular, ProtobufCMessage doesn't have
256 * any allocation policy associated with it.
257 * That's because it is common to create ProtobufCMessage's
258 * on the stack. In fact, we that's what we recommend
259 * for sending messages (because if you just allocate from the
260 * stack, then you can't really have a memory leak).
262 * This means that functions like protobuf_c_message_unpack()
263 * which return a ProtobufCMessage must be paired
264 * with a free function, like protobuf_c_message_free_unpacked().
266 * 'descriptor' gives the locations and types of the members of message
267 * 'n_unknown_fields' is the number of fields we didn't recognize.
268 * 'unknown_fields' are fields we didn't recognize.
270 typedef struct _ProtobufCMessage ProtobufCMessage;
271 typedef struct _ProtobufCMessageUnknownField ProtobufCMessageUnknownField;
272 struct _ProtobufCMessage
274 const ProtobufCMessageDescriptor *descriptor;
275 unsigned n_unknown_fields;
276 ProtobufCMessageUnknownField *unknown_fields;
278 #define PROTOBUF_C_MESSAGE_INIT(descriptor) { descriptor, 0, NULL }
280 /* To pack a message: you have two options:
281 (1) you can compute the size of the message
282 using protobuf_c_message_get_packed_size()
283 then pass protobuf_c_message_pack() a buffer of
285 (2) Provide a virtual buffer (a ProtobufCBuffer) to
286 accept data as we scan through it.
288 size_t protobuf_c_message_get_packed_size(const ProtobufCMessage *message);
289 size_t protobuf_c_message_pack (const ProtobufCMessage *message,
291 size_t protobuf_c_message_pack_to_buffer (const ProtobufCMessage *message,
292 ProtobufCBuffer *buffer);
295 protobuf_c_message_unpack (const ProtobufCMessageDescriptor *,
296 ProtobufCAllocator *allocator,
298 const uint8_t *data);
299 void protobuf_c_message_free_unpacked (ProtobufCMessage *message,
300 ProtobufCAllocator *allocator);
302 /* WARNING: 'to_init' must be a block of memory
303 of size description->sizeof_message. */
304 size_t protobuf_c_message_init (const ProtobufCMessageDescriptor *,
305 ProtobufCMessage *to_init);
307 /* --- services --- */
308 typedef struct _ProtobufCMethodDescriptor ProtobufCMethodDescriptor;
309 typedef struct _ProtobufCServiceDescriptor ProtobufCServiceDescriptor;
311 struct _ProtobufCMethodDescriptor
314 const ProtobufCMessageDescriptor *input;
315 const ProtobufCMessageDescriptor *output;
317 struct _ProtobufCServiceDescriptor
322 const char *short_name;
326 const ProtobufCMethodDescriptor *methods; /* in order from .proto file */
327 const unsigned *method_indices_by_name;
330 typedef struct _ProtobufCService ProtobufCService;
331 typedef void (*ProtobufCClosure)(const ProtobufCMessage *message,
333 struct _ProtobufCService
335 const ProtobufCServiceDescriptor *descriptor;
336 void (*invoke)(ProtobufCService *service,
337 unsigned method_index,
338 const ProtobufCMessage *input,
339 ProtobufCClosure closure,
341 void (*destroy) (ProtobufCService *service);
345 void protobuf_c_service_destroy (ProtobufCService *);
348 /* --- querying the descriptors --- */
349 const ProtobufCEnumValue *
350 protobuf_c_enum_descriptor_get_value_by_name
351 (const ProtobufCEnumDescriptor *desc,
353 const ProtobufCEnumValue *
354 protobuf_c_enum_descriptor_get_value
355 (const ProtobufCEnumDescriptor *desc,
357 const ProtobufCFieldDescriptor *
358 protobuf_c_message_descriptor_get_field_by_name
359 (const ProtobufCMessageDescriptor *desc,
361 const ProtobufCFieldDescriptor *
362 protobuf_c_message_descriptor_get_field
363 (const ProtobufCMessageDescriptor *desc,
365 const ProtobufCMethodDescriptor *
366 protobuf_c_service_descriptor_get_method_by_name
367 (const ProtobufCServiceDescriptor *desc,
370 /* --- wire format enums --- */
373 PROTOBUF_C_WIRE_TYPE_VARINT,
374 PROTOBUF_C_WIRE_TYPE_64BIT,
375 PROTOBUF_C_WIRE_TYPE_LENGTH_PREFIXED,
376 PROTOBUF_C_WIRE_TYPE_START_GROUP, /* unsupported */
377 PROTOBUF_C_WIRE_TYPE_END_GROUP, /* unsupported */
378 PROTOBUF_C_WIRE_TYPE_32BIT
381 /* --- unknown message fields --- */
382 struct _ProtobufCMessageUnknownField
385 ProtobufCWireType wire_type;
390 /* --- extra (superfluous) api: trivial buffer --- */
391 typedef struct _ProtobufCBufferSimple ProtobufCBufferSimple;
392 struct _ProtobufCBufferSimple
394 ProtobufCBuffer base;
398 protobuf_c_boolean must_free_data;
400 #define PROTOBUF_C_BUFFER_SIMPLE_INIT(array_of_bytes) \
401 { { protobuf_c_buffer_simple_append }, \
402 sizeof(array_of_bytes), 0, (array_of_bytes), 0 }
403 #define PROTOBUF_C_BUFFER_SIMPLE_CLEAR(simp_buf) \
404 do { if ((simp_buf)->must_free_data) \
405 protobuf_c_default_allocator.free (&protobuf_c_default_allocator.allocator_data, (simp_buf)->data); } while (0)
407 /* ====== private ====== */
408 #include "protobuf-c-private.h"
413 #endif /* __PROTOBUF_C_RUNTIME_H_ */