src/google/protobuf-c/protobuf-c.h

   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 <inttypes.h>
  22 #include <stddef.h>
  23 #include <assert.h>
  24
  25 #ifdef __cplusplus
  26 # define PROTOBUF_C_BEGIN_DECLS    extern "C" {
  27 # define PROTOBUF_C_END_DECLS      }
  28 #else
  29 # define PROTOBUF_C_BEGIN_DECLS
  30 # define PROTOBUF_C_END_DECLS
  31 #endif
  32
  33 PROTOBUF_C_BEGIN_DECLS
  34
  35 typedef enum
  36 {
  37   PROTOBUF_C_LABEL_REQUIRED,
  38   PROTOBUF_C_LABEL_OPTIONAL,
  39   PROTOBUF_C_LABEL_REPEATED
  40 } ProtobufCLabel;
  41
  42 typedef enum
  43 {
  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,
  56   PROTOBUF_C_TYPE_BOOL,
  57   PROTOBUF_C_TYPE_ENUM,
  58   PROTOBUF_C_TYPE_STRING,
  59   PROTOBUF_C_TYPE_BYTES,
  60   //PROTOBUF_C_TYPE_GROUP,          // NOT SUPPORTED
  61   PROTOBUF_C_TYPE_MESSAGE,
  62 } ProtobufCType;
  63
  64 typedef int protobuf_c_boolean;
  65 #define PROTOBUF_C_OFFSETOF(struct, member) offsetof(struct, member)
  66
  67 #define PROTOBUF_C_ASSERT(condition) assert(condition)
  68 #define PROTOBUF_C_ASSERT_NOT_REACHED() assert(0)
  69
  70 typedef struct _ProtobufCBinaryData ProtobufCBinaryData;
  71 struct _ProtobufCBinaryData
  72 {
  73   size_t len;
  74   uint8_t *data;
  75 };
  76
  77 typedef struct _ProtobufCIntRange ProtobufCIntRange; /* private */
  78
  79 /* --- memory management --- */
  80 typedef struct _ProtobufCAllocator ProtobufCAllocator;
  81 struct _ProtobufCAllocator
  82 {
  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);
  86   unsigned max_alloca;
  87   void *allocator_data;
  88 };
  89
  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.
  94  */
  95 extern ProtobufCAllocator protobuf_c_default_allocator; /* settable */
  96
  97 /* This is the system allocator, meaning it uses malloc() and free() */
  98 extern ProtobufCAllocator protobuf_c_system_allocator;  /* use malloc, free etc */
  99
 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);
 104
 105 /* --- append-only data buffer --- */
 106 typedef struct _ProtobufCBuffer ProtobufCBuffer;
 107 struct _ProtobufCBuffer
 108 {
 109   void (*append)(ProtobufCBuffer     *buffer,
 110                  size_t               len,
 111                  const uint8_t       *data);
 112 };
 113 /* --- enums --- */
 114 typedef struct _ProtobufCEnumValue ProtobufCEnumValue;
 115 typedef struct _ProtobufCEnumValueIndex ProtobufCEnumValueIndex;
 116 typedef struct _ProtobufCEnumDescriptor ProtobufCEnumDescriptor;
 117
 118 /* ProtobufCEnumValue:  this represents a single value of
 119  * an enumeration.
 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.
 123  */
 124 struct _ProtobufCEnumValue
 125 {
 126   const char *name;
 127   const char *c_name;
 128   int value;
 129 };
 130
 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).
 141  *
 142  * The rest of the values are private essentially.
 143  *
 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.
 147  */
 148 struct _ProtobufCEnumDescriptor
 149 {
 150   uint32_t magic;
 151
 152   const char *name;
 153   const char *short_name;
 154   const char *c_name;
 155   const char *package_name;
 156
 157   /* sorted by value */
 158   unsigned n_values;
 159   const ProtobufCEnumValue *values;
 160
 161   /* sorted by name */
 162   unsigned n_value_names;
 163   const ProtobufCEnumValueIndex *values_by_name;
 164
 165   /* value-ranges, for faster lookups by number */
 166   unsigned n_value_ranges;
 167   const ProtobufCIntRange *value_ranges;
 168
 169   void *reserved1;
 170   void *reserved2;
 171   void *reserved3;
 172   void *reserved4;
 173 };
 174
 175 /* --- messages --- */
 176 typedef struct _ProtobufCMessageDescriptor ProtobufCMessageDescriptor;
 177 typedef struct _ProtobufCFieldDescriptor ProtobufCFieldDescriptor;
 178 /* ProtobufCFieldDescriptor: description of a single field
 179  * in a message.
 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,
 191  *        otherwise NULL.
 192  * 'default_value' is a pointer to a default value for this field,
 193  *        where allowed.
 194  */
 195 struct _ProtobufCFieldDescriptor
 196 {
 197   const char *name;
 198   uint32_t id;
 199   ProtobufCLabel label;
 200   ProtobufCType type;
 201   unsigned quantifier_offset;
 202   unsigned offset;
 203   const void *descriptor;   /* for MESSAGE and ENUM types */
 204   const void *default_value;   /* or NULL if no default-value */
 205
 206   void *reserved1;
 207   void *reserved2;
 208 };
 209 /* ProtobufCMessageDescriptor: description of a message.
 210  *
 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)
 222  */
 223 struct _ProtobufCMessageDescriptor
 224 {
 225   uint32_t magic;
 226
 227   const char *name;
 228   const char *short_name;
 229   const char *c_name;
 230   const char *package_name;
 231
 232   size_t sizeof_message;
 233
 234   /* sorted by field-id */
 235   unsigned n_fields;
 236   const ProtobufCFieldDescriptor *fields;
 237   const unsigned *fields_sorted_by_name;
 238
 239   /* ranges, optimization for looking up fields */
 240   unsigned n_field_ranges;
 241   const ProtobufCIntRange *field_ranges;
 242
 243   void *reserved1;
 244   void *reserved2;
 245   void *reserved3;
 246   void *reserved4;
 247 };
 248
 249
 250 /* ProtobufCMessage: an instance of a message.
 251  *
 252  * ProtobufCMessage is sort-of a lightweight
 253  * base-class for all messages.
 254  *
 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).
 261  *
 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().
 265  *
 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.
 269  */
 270 typedef struct _ProtobufCMessage ProtobufCMessage;
 271 typedef struct _ProtobufCMessageUnknownField ProtobufCMessageUnknownField;
 272 struct _ProtobufCMessage
 273 {
 274   const ProtobufCMessageDescriptor *descriptor;
 275   unsigned n_unknown_fields;
 276   ProtobufCMessageUnknownField *unknown_fields;
 277 };
 278 #define PROTOBUF_C_MESSAGE_INIT(descriptor) { descriptor, 0, NULL }
 279
 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
 284        that length.
 285    (2) Provide a virtual buffer (a ProtobufCBuffer) to
 286        accept data as we scan through it.
 287  */
 288 size_t    protobuf_c_message_get_packed_size(const ProtobufCMessage *message);
 289 size_t    protobuf_c_message_pack           (const ProtobufCMessage *message,
 290                                              uint8_t                *out);
 291 size_t    protobuf_c_message_pack_to_buffer (const ProtobufCMessage *message,
 292                                              ProtobufCBuffer  *buffer);
 293
 294 ProtobufCMessage *
 295           protobuf_c_message_unpack         (const ProtobufCMessageDescriptor *,
 296                                              ProtobufCAllocator  *allocator,
 297                                              size_t               len,
 298                                              const uint8_t       *data);
 299 void      protobuf_c_message_free_unpacked  (ProtobufCMessage    *message,
 300                                              ProtobufCAllocator  *allocator);
 301
 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);
 306
 307 /* --- services --- */
 308 typedef struct _ProtobufCMethodDescriptor ProtobufCMethodDescriptor;
 309 typedef struct _ProtobufCServiceDescriptor ProtobufCServiceDescriptor;
 310
 311 struct _ProtobufCMethodDescriptor
 312 {
 313   const char *name;
 314   const ProtobufCMessageDescriptor *input;
 315   const ProtobufCMessageDescriptor *output;
 316 };
 317 struct _ProtobufCServiceDescriptor
 318 {
 319   uint32_t magic;
 320
 321   const char *name;
 322   const char *short_name;
 323   const char *c_name;
 324   const char *package;
 325   unsigned n_methods;
 326   const ProtobufCMethodDescriptor *methods;     /* in order from .proto file */
 327   const unsigned *method_indices_by_name;
 328 };
 329
 330 typedef struct _ProtobufCService ProtobufCService;
 331 typedef void (*ProtobufCClosure)(const ProtobufCMessage *message,
 332                                  void                   *closure_data);
 333 struct _ProtobufCService
 334 {
 335   const ProtobufCServiceDescriptor *descriptor;
 336   void (*invoke)(ProtobufCService *service,
 337                  unsigned          method_index,
 338                  const ProtobufCMessage *input,
 339                  ProtobufCClosure  closure,
 340                  void             *closure_data);
 341   void (*destroy) (ProtobufCService *service);
 342 };
 343
 344
 345 void protobuf_c_service_destroy (ProtobufCService *);
 346
 347
 348 /* --- querying the descriptors --- */
 349 const ProtobufCEnumValue *
 350 protobuf_c_enum_descriptor_get_value_by_name
 351                          (const ProtobufCEnumDescriptor    *desc,
 352                           const char                       *name);
 353 const ProtobufCEnumValue *
 354 protobuf_c_enum_descriptor_get_value
 355                          (const ProtobufCEnumDescriptor    *desc,
 356                           int                               value);
 357 const ProtobufCFieldDescriptor *
 358 protobuf_c_message_descriptor_get_field_by_name
 359                          (const ProtobufCMessageDescriptor *desc,
 360                           const char                       *name);
 361 const ProtobufCFieldDescriptor *
 362 protobuf_c_message_descriptor_get_field
 363                          (const ProtobufCMessageDescriptor *desc,
 364                           unsigned                          value);
 365 const ProtobufCMethodDescriptor *
 366 protobuf_c_service_descriptor_get_method_by_name
 367                          (const ProtobufCServiceDescriptor *desc,
 368                           const char                       *name);
 369
 370 /* --- wire format enums --- */
 371 typedef enum
 372 {
 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
 379 } ProtobufCWireType;
 380
 381 /* --- unknown message fields --- */
 382 struct _ProtobufCMessageUnknownField
 383 {
 384   uint32_t tag;
 385   ProtobufCWireType wire_type;
 386   size_t len;
 387   uint8_t *data;
 388 };
 389
 390 /* --- extra (superfluous) api:  trivial buffer --- */
 391 typedef struct _ProtobufCBufferSimple ProtobufCBufferSimple;
 392 struct _ProtobufCBufferSimple
 393 {
 394   ProtobufCBuffer base;
 395   size_t alloced;
 396   size_t len;
 397   uint8_t *data;
 398   protobuf_c_boolean must_free_data;
 399 };
 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)
 406
 407 /* ====== private ====== */
 408 #include "protobuf-c-private.h"
 409
 410
 411 PROTOBUF_C_END_DECLS
 412
 413 #endif /* __PROTOBUF_C_RUNTIME_H_ */