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 <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_ */