Navit SVN

/work/compile/navit/src/navit/maptool/google/protobuf-c/protobuf-c.h

00001 /* --- protobuf-c.h: public protobuf c runtime api --- */
00002 
00003 /*
00004  * Copyright 2008, Dave Benson.
00005  * 
00006  * Licensed under the Apache License, Version 2.0 (the "License");
00007  * you may not use this file except in compliance with
00008  * the License. You may obtain a copy of the License
00009  * at http://www.apache.org/licenses/LICENSE-2.0 Unless
00010  * required by applicable law or agreed to in writing,
00011  * software distributed under the License is distributed on
00012  * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
00013  * KIND, either express or implied. See the License for the
00014  * specific language governing permissions and limitations
00015  * under the License.
00016  */
00017 
00018 #ifndef __PROTOBUF_C_RUNTIME_H_
00019 #define __PROTOBUF_C_RUNTIME_H_
00020 
00021 #include <stddef.h>
00022 #include <assert.h>
00023 
00024 #ifdef __cplusplus
00025 # define PROTOBUF_C_BEGIN_DECLS    extern "C" {
00026 # define PROTOBUF_C_END_DECLS      }
00027 #else
00028 # define PROTOBUF_C_BEGIN_DECLS
00029 # define PROTOBUF_C_END_DECLS
00030 #endif
00031 
00032 #if !defined(PROTOBUF_C_NO_DEPRECATED) && (__GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1))
00033 #define PROTOBUF_C_DEPRECATED __attribute__((__deprecated__))
00034 #else
00035 #define PROTOBUF_C_DEPRECATED
00036 #endif
00037 
00038 /* Define int32_t, int64_t, uint32_t, uint64_t, uint8_t.
00039 
00040    Usually, just include <inttypes.h> to do the work.
00041    XXX: should we use stdint.h?
00042  */
00043 #ifndef PROTOBUF_C_SKIP_INTTYPES_H
00044 #  if defined(_MSC_VER)
00045      /* On windows, in ms visual studio, define the types ourselves */
00046 #    define int32_t      signed __int32
00047 #    define uint32_t     unsigned __int32
00048 #    define int64_t      signed __int64
00049 #    define uint64_t     unsigned __int64
00050 #    define uint8_t      unsigned char
00051 #  else
00052      /* Use the system inttypes.h */
00053 #    include <inttypes.h>
00054 #  endif
00055 #endif
00056 
00057 PROTOBUF_C_BEGIN_DECLS
00058 
00059 typedef enum
00060 {
00061   PROTOBUF_C_LABEL_REQUIRED,
00062   PROTOBUF_C_LABEL_OPTIONAL,
00063   PROTOBUF_C_LABEL_REPEATED
00064 } ProtobufCLabel;
00065 
00066 typedef enum
00067 {
00068   PROTOBUF_C_TYPE_INT32,
00069   PROTOBUF_C_TYPE_SINT32,
00070   PROTOBUF_C_TYPE_SFIXED32,
00071   PROTOBUF_C_TYPE_INT64,
00072   PROTOBUF_C_TYPE_SINT64,
00073   PROTOBUF_C_TYPE_SFIXED64,
00074   PROTOBUF_C_TYPE_UINT32,
00075   PROTOBUF_C_TYPE_FIXED32,
00076   PROTOBUF_C_TYPE_UINT64,
00077   PROTOBUF_C_TYPE_FIXED64,
00078   PROTOBUF_C_TYPE_FLOAT,
00079   PROTOBUF_C_TYPE_DOUBLE,
00080   PROTOBUF_C_TYPE_BOOL,
00081   PROTOBUF_C_TYPE_ENUM,
00082   PROTOBUF_C_TYPE_STRING,
00083   PROTOBUF_C_TYPE_BYTES,
00084   //PROTOBUF_C_TYPE_GROUP,          // NOT SUPPORTED
00085   PROTOBUF_C_TYPE_MESSAGE,
00086 } ProtobufCType;
00087 
00088 typedef int protobuf_c_boolean;
00089 #define PROTOBUF_C_OFFSETOF(struct, member) offsetof(struct, member)
00090 
00091 #define PROTOBUF_C_ASSERT(condition) assert(condition)
00092 #define PROTOBUF_C_ASSERT_NOT_REACHED() assert(0)
00093 
00094 typedef struct _ProtobufCBinaryData ProtobufCBinaryData;
00095 struct _ProtobufCBinaryData
00096 {
00097   size_t len;
00098   uint8_t *data;
00099 };
00100 
00101 typedef struct _ProtobufCIntRange ProtobufCIntRange; /* private */
00102 
00103 /* --- memory management --- */
00104 typedef struct _ProtobufCAllocator ProtobufCAllocator;
00105 struct _ProtobufCAllocator
00106 {
00107   void *(*alloc)(void *allocator_data, size_t size);
00108   void (*free)(void *allocator_data, void *pointer);
00109   void *(*tmp_alloc)(void *allocator_data, size_t size);
00110   unsigned max_alloca;
00111   void *allocator_data;
00112 };
00113 
00114 /* This is a configurable allocator.
00115  * By default, it uses the system allocator (meaning malloc() and free()).
00116  * This is typically changed to adapt to frameworks that provide
00117  * some nonstandard allocation functions.
00118  *
00119  * NOTE: you may modify this allocator.
00120  */
00121 extern ProtobufCAllocator protobuf_c_default_allocator; /* settable */
00122 
00123 /* This is the system allocator, meaning it uses malloc() and free().
00124  *
00125  * NOTE: please do NOT modify this allocator.
00126  */
00127 extern ProtobufCAllocator protobuf_c_system_allocator;  /* use malloc, free etc */
00128 
00129 /* This is the function that our default allocators call when they 
00130    run out-of-memory.  The default behavior of this function is to
00131    terminate your program. */
00132 extern void (*protobuf_c_out_of_memory) (void);
00133 
00134 /* --- append-only data buffer --- */
00135 typedef struct _ProtobufCBuffer ProtobufCBuffer;
00136 struct _ProtobufCBuffer
00137 {
00138   void (*append)(ProtobufCBuffer     *buffer,
00139                  size_t               len,
00140                  const uint8_t       *data);
00141 };
00142 /* --- enums --- */
00143 typedef struct _ProtobufCEnumValue ProtobufCEnumValue;
00144 typedef struct _ProtobufCEnumValueIndex ProtobufCEnumValueIndex;
00145 typedef struct _ProtobufCEnumDescriptor ProtobufCEnumDescriptor;
00146 
00147 /* ProtobufCEnumValue:  this represents a single value of
00148  * an enumeration.
00149  * 'name' is the string identifying this value, as given in the .proto file.
00150  * 'c_name' is the full name of the C enumeration value.
00151  * 'value' is the number assigned to this value, as given in the .proto file.
00152  */
00153 struct _ProtobufCEnumValue
00154 {
00155   const char *name;
00156   const char *c_name;
00157   int value;
00158 };
00159 
00160 /* ProtobufCEnumDescriptor: the represents the enum as a whole,
00161  * with all its values.
00162  * 'magic' is a code we check to ensure that the api is used correctly.
00163  * 'name' is the qualified name (e.g. "namespace.Type").
00164  * 'short_name' is the unqualified name ("Type"), as given in the .proto file.
00165  * 'package_name' is the '.'-separated namespace
00166  * 'n_values' is the number of distinct values.
00167  * 'values' is the array of distinct values.
00168  * 'n_value_names' number of named values (including aliases).
00169  * 'value_names' are the named values (including aliases).
00170  *
00171  * The rest of the values are private essentially.
00172  *
00173  * see also: Use protobuf_c_enum_descriptor_get_value_by_name()
00174  * and protobuf_c_enum_descriptor_get_value() to efficiently
00175  * lookup values in the descriptor.
00176  */
00177 struct _ProtobufCEnumDescriptor
00178 {
00179   uint32_t magic;
00180 
00181   const char *name;
00182   const char *short_name;
00183   const char *c_name;
00184   const char *package_name;
00185 
00186   /* sorted by value */
00187   unsigned n_values;
00188   const ProtobufCEnumValue *values;
00189 
00190   /* sorted by name */
00191   unsigned n_value_names;
00192   const ProtobufCEnumValueIndex *values_by_name;
00193 
00194   /* value-ranges, for faster lookups by number */
00195   unsigned n_value_ranges;
00196   const ProtobufCIntRange *value_ranges;
00197 
00198   void *reserved1;
00199   void *reserved2;
00200   void *reserved3;
00201   void *reserved4;
00202 };
00203 
00204 /* --- messages --- */
00205 typedef struct _ProtobufCMessageDescriptor ProtobufCMessageDescriptor;
00206 typedef struct _ProtobufCFieldDescriptor ProtobufCFieldDescriptor;
00207 typedef struct _ProtobufCMessage ProtobufCMessage;
00208 typedef void (*ProtobufCMessageInit)(ProtobufCMessage *);
00209 /* ProtobufCFieldDescriptor: description of a single field
00210  * in a message.
00211  * 'name' is the name of the field, as given in the .proto file.
00212  * 'id' is the code representing the field, as given in the .proto file.
00213  * 'label' is one of PROTOBUF_C_LABEL_{REQUIRED,OPTIONAL,REPEATED}
00214  * 'type' is the type of field.
00215  * 'quantifier_offset' is the offset in bytes into the message's C structure
00216  *        for this member's "has_MEMBER" field (for optional members) or
00217  *        "n_MEMBER" field (for repeated members).
00218  * 'offset' is the offset in bytes into the message's C structure
00219  *        for the member itself.
00220  * 'descriptor' is a pointer to a ProtobufC{Enum,Message}Descriptor
00221  *        if type is PROTOBUF_C_TYPE_{ENUM,MESSAGE} respectively,
00222  *        otherwise NULL.
00223  * 'default_value' is a pointer to a default value for this field,
00224  *        where allowed.
00225  */
00226 struct _ProtobufCFieldDescriptor
00227 {
00228   const char *name;
00229   uint32_t id;
00230   ProtobufCLabel label;
00231   ProtobufCType type;
00232   unsigned quantifier_offset;
00233   unsigned offset;
00234   const void *descriptor;   /* for MESSAGE and ENUM types */
00235   const void *default_value;   /* or NULL if no default-value */
00236   protobuf_c_boolean packed;
00237 
00238   unsigned reserved_flags;
00239   void *reserved2;
00240   void *reserved3;
00241 };
00242 /* ProtobufCMessageDescriptor: description of a message.
00243  *
00244  * 'magic' is a code we check to ensure that the api is used correctly.
00245  * 'name' is the qualified name (e.g. "namespace.Type").
00246  * 'short_name' is the unqualified name ("Type"), as given in the .proto file.
00247  * 'c_name' is the c-formatted name of the structure
00248  * 'package_name' is the '.'-separated namespace
00249  * 'sizeof_message' is the size in bytes of the C structure
00250  *        representing an instance of this type of message.
00251  * 'n_fields' is the number of known fields in this message.
00252  * 'fields' is the fields sorted by id number.
00253  * 'fields_sorted_by_name', 'n_field_ranges' and 'field_ranges'
00254  *       are used for looking up fields by name and id. (private)
00255  */
00256 struct _ProtobufCMessageDescriptor
00257 {
00258   uint32_t magic;
00259 
00260   const char *name;
00261   const char *short_name;
00262   const char *c_name;
00263   const char *package_name;
00264 
00265   size_t sizeof_message;
00266 
00267   /* sorted by field-id */
00268   unsigned n_fields;
00269   const ProtobufCFieldDescriptor *fields;
00270   const unsigned *fields_sorted_by_name;
00271 
00272   /* ranges, optimization for looking up fields */
00273   unsigned n_field_ranges;
00274   const ProtobufCIntRange *field_ranges;
00275 
00276   ProtobufCMessageInit message_init;
00277   void *reserved1;
00278   void *reserved2;
00279   void *reserved3;
00280 };
00281 
00282 
00283 /* ProtobufCMessage: an instance of a message.
00284  *
00285  * ProtobufCMessage is sort-of a lightweight
00286  * base-class for all messages.
00287  * 
00288  * In particular, ProtobufCMessage doesn't have
00289  * any allocation policy associated with it.
00290  * That's because it is common to create ProtobufCMessage's
00291  * on the stack.  In fact, we that's what we recommend
00292  * for sending messages (because if you just allocate from the
00293  * stack, then you can't really have a memory leak).
00294  *
00295  * This means that functions like protobuf_c_message_unpack()
00296  * which return a ProtobufCMessage must be paired
00297  * with a free function, like protobuf_c_message_free_unpacked().
00298  *
00299  * 'descriptor' gives the locations and types of the members of message
00300  * 'n_unknown_fields' is the number of fields we didn't recognize.
00301  * 'unknown_fields' are fields we didn't recognize.
00302  */
00303 typedef struct _ProtobufCMessageUnknownField ProtobufCMessageUnknownField;
00304 struct _ProtobufCMessage
00305 {
00306   const ProtobufCMessageDescriptor *descriptor;
00307   unsigned n_unknown_fields;
00308   ProtobufCMessageUnknownField *unknown_fields;
00309 };
00310 #define PROTOBUF_C_MESSAGE_INIT(descriptor) { descriptor, 0, NULL }
00311 
00312 /* To pack a message: you have two options:
00313    (1) you can compute the size of the message
00314        using protobuf_c_message_get_packed_size() 
00315        then pass protobuf_c_message_pack() a buffer of
00316        that length.
00317    (2) Provide a virtual buffer (a ProtobufCBuffer) to
00318        accept data as we scan through it.
00319  */
00320 size_t    protobuf_c_message_get_packed_size(const ProtobufCMessage *message);
00321 size_t    protobuf_c_message_pack           (const ProtobufCMessage *message,
00322                                              uint8_t                *out);
00323 size_t    protobuf_c_message_pack_to_buffer (const ProtobufCMessage *message,
00324                                              ProtobufCBuffer  *buffer);
00325 
00326 ProtobufCMessage *
00327           protobuf_c_message_unpack         (const ProtobufCMessageDescriptor *,
00328                                              ProtobufCAllocator  *allocator,
00329                                              size_t               len,
00330                                              const uint8_t       *data);
00331 void      protobuf_c_message_free_unpacked  (ProtobufCMessage    *message,
00332                                              ProtobufCAllocator  *allocator);
00333 
00334 /* WARNING: 'message' must be a block of memory 
00335    of size descriptor->sizeof_message. */
00336 #define protobuf_c_message_init(descriptor, message) ((descriptor)->message_init((ProtobufCMessage*) (message)))
00337 
00338 /* --- services --- */
00339 typedef struct _ProtobufCMethodDescriptor ProtobufCMethodDescriptor;
00340 typedef struct _ProtobufCServiceDescriptor ProtobufCServiceDescriptor;
00341 
00342 struct _ProtobufCMethodDescriptor
00343 {
00344   const char *name;
00345   const ProtobufCMessageDescriptor *input;
00346   const ProtobufCMessageDescriptor *output;
00347 };
00348 struct _ProtobufCServiceDescriptor
00349 {
00350   uint32_t magic;
00351 
00352   const char *name;
00353   const char *short_name;
00354   const char *c_name;
00355   const char *package;
00356   unsigned n_methods;
00357   const ProtobufCMethodDescriptor *methods;     /* in order from .proto file */
00358   const unsigned *method_indices_by_name;
00359 };
00360 
00361 typedef struct _ProtobufCService ProtobufCService;
00362 typedef void (*ProtobufCClosure)(const ProtobufCMessage *message,
00363                                  void                   *closure_data);
00364 struct _ProtobufCService
00365 {
00366   const ProtobufCServiceDescriptor *descriptor;
00367   void (*invoke)(ProtobufCService *service,
00368                  unsigned          method_index,
00369                  const ProtobufCMessage *input,
00370                  ProtobufCClosure  closure,
00371                  void             *closure_data);
00372   void (*destroy) (ProtobufCService *service);
00373 };
00374 
00375 
00376 void protobuf_c_service_destroy (ProtobufCService *);
00377 
00378 
00379 /* --- querying the descriptors --- */
00380 const ProtobufCEnumValue *
00381 protobuf_c_enum_descriptor_get_value_by_name 
00382                          (const ProtobufCEnumDescriptor    *desc,
00383                           const char                       *name);
00384 const ProtobufCEnumValue *
00385 protobuf_c_enum_descriptor_get_value        
00386                          (const ProtobufCEnumDescriptor    *desc,
00387                           int                               value);
00388 const ProtobufCFieldDescriptor *
00389 protobuf_c_message_descriptor_get_field_by_name
00390                          (const ProtobufCMessageDescriptor *desc,
00391                           const char                       *name);
00392 const ProtobufCFieldDescriptor *
00393 protobuf_c_message_descriptor_get_field        
00394                          (const ProtobufCMessageDescriptor *desc,
00395                           unsigned                          value);
00396 const ProtobufCMethodDescriptor *
00397 protobuf_c_service_descriptor_get_method_by_name
00398                          (const ProtobufCServiceDescriptor *desc,
00399                           const char                       *name);
00400 
00401 /* --- wire format enums --- */
00402 typedef enum
00403 {
00404   PROTOBUF_C_WIRE_TYPE_VARINT,
00405   PROTOBUF_C_WIRE_TYPE_64BIT,
00406   PROTOBUF_C_WIRE_TYPE_LENGTH_PREFIXED,
00407   PROTOBUF_C_WIRE_TYPE_START_GROUP,     /* unsupported */
00408   PROTOBUF_C_WIRE_TYPE_END_GROUP,       /* unsupported */
00409   PROTOBUF_C_WIRE_TYPE_32BIT
00410 } ProtobufCWireType;
00411 
00412 /* --- unknown message fields --- */
00413 struct _ProtobufCMessageUnknownField
00414 {
00415   uint32_t tag;
00416   ProtobufCWireType wire_type;
00417   size_t len;
00418   uint8_t *data;
00419 };
00420 
00421 /* --- extra (superfluous) api:  trivial buffer --- */
00422 typedef struct _ProtobufCBufferSimple ProtobufCBufferSimple;
00423 struct _ProtobufCBufferSimple
00424 {
00425   ProtobufCBuffer base;
00426   size_t alloced;
00427   size_t len;
00428   uint8_t *data;
00429   protobuf_c_boolean must_free_data;
00430 };
00431 #define PROTOBUF_C_BUFFER_SIMPLE_INIT(array_of_bytes) \
00432 { { protobuf_c_buffer_simple_append }, \
00433   sizeof(array_of_bytes), 0, (array_of_bytes), 0 }
00434 #define PROTOBUF_C_BUFFER_SIMPLE_CLEAR(simp_buf) \
00435   do { if ((simp_buf)->must_free_data) \
00436          protobuf_c_default_allocator.free (&protobuf_c_default_allocator.allocator_data, (simp_buf)->data); } while (0)
00437 
00438 /* ====== private ====== */
00439 #include "protobuf-c-private.h"
00440 
00441 
00442 PROTOBUF_C_END_DECLS
00443 
00444 #endif /* __PROTOBUF_C_RUNTIME_H_ */