protobuf-c.h

Go to the documentation of this file.

/*
 * Copyright (c) 2008-2014, Dave Benson and the protobuf-c authors.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *
 *     * Redistributions of source code must retain the above copyright
 * notice, this list of conditions and the following disclaimer.
 *
 *     * Redistributions in binary form must reproduce the above
 * copyright notice, this list of conditions and the following disclaimer
 * in the documentation and/or other materials provided with the
 * distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef PROTOBUF_C_H
#define PROTOBUF_C_H

#include <assert.h>
#include <limits.h>
#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
# define PROTOBUF_C__BEGIN_DECLS    extern "C" {
# define PROTOBUF_C__END_DECLS      }
#else
# define PROTOBUF_C__BEGIN_DECLS
# define PROTOBUF_C__END_DECLS
#endif

PROTOBUF_C__BEGIN_DECLS

#if defined(_WIN32) && defined(PROTOBUF_C_USE_SHARED_LIB)
# ifdef PROTOBUF_C_EXPORT
#  define PROTOBUF_C__API __declspec(dllexport)
# else
#  define PROTOBUF_C__API __declspec(dllimport)
# endif
#else
# define PROTOBUF_C__API
#endif

#if !defined(PROTOBUF_C__NO_DEPRECATED) && \
    ((__GNUC__ > 3) || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1))
# define PROTOBUF_C__DEPRECATED __attribute__((__deprecated__))
#else
# define PROTOBUF_C__DEPRECATED
#endif

#ifndef PROTOBUF_C__FORCE_ENUM_TO_BE_INT_SIZE
 #define PROTOBUF_C__FORCE_ENUM_TO_BE_INT_SIZE(enum_name) \
  , _##enum_name##_IS_INT_SIZE = INT_MAX
#endif

#define PROTOBUF_C__SERVICE_DESCRIPTOR_MAGIC    0x14159bc3
#define PROTOBUF_C__MESSAGE_DESCRIPTOR_MAGIC    0x28aaeef9
#define PROTOBUF_C__ENUM_DESCRIPTOR_MAGIC       0x114315af

typedef enum {
    PROTOBUF_C_FIELD_FLAG_PACKED        = (1 << 0),

    PROTOBUF_C_FIELD_FLAG_DEPRECATED    = (1 << 1),

    PROTOBUF_C_FIELD_FLAG_ONEOF     = (1 << 2),
} ProtobufCFieldFlag;

typedef enum {
    PROTOBUF_C_LABEL_REQUIRED,

    PROTOBUF_C_LABEL_OPTIONAL,

    PROTOBUF_C_LABEL_REPEATED,
} ProtobufCLabel;

typedef enum {
    PROTOBUF_C_TYPE_INT32,      
    PROTOBUF_C_TYPE_SINT32,     
    PROTOBUF_C_TYPE_SFIXED32,   
    PROTOBUF_C_TYPE_INT64,      
    PROTOBUF_C_TYPE_SINT64,     
    PROTOBUF_C_TYPE_SFIXED64,   
    PROTOBUF_C_TYPE_UINT32,     
    PROTOBUF_C_TYPE_FIXED32,    
    PROTOBUF_C_TYPE_UINT64,     
    PROTOBUF_C_TYPE_FIXED64,    
    PROTOBUF_C_TYPE_FLOAT,      
    PROTOBUF_C_TYPE_DOUBLE,     
    PROTOBUF_C_TYPE_BOOL,       
    PROTOBUF_C_TYPE_ENUM,       
    PROTOBUF_C_TYPE_STRING,     
    PROTOBUF_C_TYPE_BYTES,      
    PROTOBUF_C_TYPE_MESSAGE,    
} ProtobufCType;

typedef enum {
    PROTOBUF_C_WIRE_TYPE_VARINT = 0,
    PROTOBUF_C_WIRE_TYPE_64BIT = 1,
    PROTOBUF_C_WIRE_TYPE_LENGTH_PREFIXED = 2,
    /* "Start group" and "end group" wire types are unsupported. */
    PROTOBUF_C_WIRE_TYPE_32BIT = 5,
} ProtobufCWireType;

struct ProtobufCAllocator;
struct ProtobufCBinaryData;
struct ProtobufCBuffer;
struct ProtobufCBufferSimple;
struct ProtobufCEnumDescriptor;
struct ProtobufCEnumValue;
struct ProtobufCEnumValueIndex;
struct ProtobufCFieldDescriptor;
struct ProtobufCIntRange;
struct ProtobufCMessage;
struct ProtobufCMessageDescriptor;
struct ProtobufCMessageUnknownField;
struct ProtobufCMethodDescriptor;
struct ProtobufCService;
struct ProtobufCServiceDescriptor;

typedef struct ProtobufCAllocator ProtobufCAllocator;
typedef struct ProtobufCBinaryData ProtobufCBinaryData;
typedef struct ProtobufCBuffer ProtobufCBuffer;
typedef struct ProtobufCBufferSimple ProtobufCBufferSimple;
typedef struct ProtobufCEnumDescriptor ProtobufCEnumDescriptor;
typedef struct ProtobufCEnumValue ProtobufCEnumValue;
typedef struct ProtobufCEnumValueIndex ProtobufCEnumValueIndex;
typedef struct ProtobufCFieldDescriptor ProtobufCFieldDescriptor;
typedef struct ProtobufCIntRange ProtobufCIntRange;
typedef struct ProtobufCMessage ProtobufCMessage;
typedef struct ProtobufCMessageDescriptor ProtobufCMessageDescriptor;
typedef struct ProtobufCMessageUnknownField ProtobufCMessageUnknownField;
typedef struct ProtobufCMethodDescriptor ProtobufCMethodDescriptor;
typedef struct ProtobufCService ProtobufCService;
typedef struct ProtobufCServiceDescriptor ProtobufCServiceDescriptor;

typedef int protobuf_c_boolean;

typedef void (*ProtobufCClosure)(const ProtobufCMessage *, void *closure_data);
typedef void (*ProtobufCMessageInit)(ProtobufCMessage *);
typedef void (*ProtobufCServiceDestroy)(ProtobufCService *);

struct ProtobufCAllocator {
    void        *(*alloc)(void *allocator_data, size_t size);

    void        (*free)(void *allocator_data, void *pointer);

    void        *allocator_data;
};

struct ProtobufCBinaryData {
    size_t  len;        
    uint8_t *data;      
};

struct ProtobufCBuffer {
    void        (*append)(ProtobufCBuffer *buffer,
                  size_t len,
                  const uint8_t *data);
};

struct ProtobufCBufferSimple {
    ProtobufCBuffer     base;
    size_t          alloced;
    size_t          len;
    uint8_t         *data;
    protobuf_c_boolean  must_free_data;
    ProtobufCAllocator  *allocator;
};

struct ProtobufCEnumDescriptor {
    uint32_t            magic;

    const char          *name;
    const char          *short_name;
    const char          *c_name;
    const char          *package_name;

    unsigned            n_values;
    const ProtobufCEnumValue    *values;

    unsigned            n_value_names;
    const ProtobufCEnumValueIndex   *values_by_name;

    unsigned            n_value_ranges;
    const ProtobufCIntRange     *value_ranges;

    void                *reserved1;
    void                *reserved2;
    void                *reserved3;
    void                *reserved4;
};

struct ProtobufCEnumValue {
    const char  *name;

    const char  *c_name;

    int     value;
};

struct ProtobufCEnumValueIndex {
    const char      *name;
    unsigned        index;
};

struct ProtobufCFieldDescriptor {
    const char      *name;

    uint32_t        id;

    ProtobufCLabel      label;

    ProtobufCType       type;

    unsigned        quantifier_offset;

    unsigned        offset;

    const void      *descriptor; /* for MESSAGE and ENUM types */

    const void      *default_value;

    uint32_t        flags;

    unsigned        reserved_flags;
    void            *reserved2;
    void            *reserved3;
};

struct ProtobufCIntRange {
    int             start_value;
    unsigned        orig_index;
    /*
     * NOTE: the number of values in the range can be inferred by looking
     * at the next element's orig_index. A dummy element is added to make
     * this simple.
     */
};

struct ProtobufCMessage {
    const ProtobufCMessageDescriptor    *descriptor;
    unsigned                n_unknown_fields;
    ProtobufCMessageUnknownField        *unknown_fields;
};

struct ProtobufCMessageDescriptor {
    uint32_t            magic;

    const char          *name;
    const char          *short_name;
    const char          *c_name;
    const char          *package_name;

    size_t              sizeof_message;

    unsigned            n_fields;
    const ProtobufCFieldDescriptor  *fields;
    const unsigned          *fields_sorted_by_name;

    unsigned            n_field_ranges;
    const ProtobufCIntRange     *field_ranges;

    ProtobufCMessageInit        message_init;

    void                *reserved1;
    void                *reserved2;
    void                *reserved3;
};

struct ProtobufCMessageUnknownField {
    uint32_t        tag;
    ProtobufCWireType   wire_type;
    size_t          len;
    uint8_t         *data;
};

struct ProtobufCMethodDescriptor {
    const char              *name;
    const ProtobufCMessageDescriptor    *input;
    const ProtobufCMessageDescriptor    *output;
};

struct ProtobufCService {
    const ProtobufCServiceDescriptor *descriptor;
    void (*invoke)(ProtobufCService *service,
               unsigned method_index,
               const ProtobufCMessage *input,
               ProtobufCClosure closure,
               void *closure_data);
    void (*destroy)(ProtobufCService *service);
};

struct ProtobufCServiceDescriptor {
    uint32_t            magic;

    const char          *name;
    const char          *short_name;
    const char          *c_name;
    const char          *package;
    unsigned            n_methods;
    const ProtobufCMethodDescriptor *methods;
    const unsigned          *method_indices_by_name;
};

PROTOBUF_C__API
const char *
protobuf_c_version(void);

PROTOBUF_C__API
uint32_t
protobuf_c_version_number(void);

#define PROTOBUF_C_VERSION      "1.1.1"

#define PROTOBUF_C_VERSION_NUMBER   1001001

#define PROTOBUF_C_MIN_COMPILER_VERSION 1000000

PROTOBUF_C__API
const ProtobufCEnumValue *
protobuf_c_enum_descriptor_get_value_by_name(
    const ProtobufCEnumDescriptor *desc,
    const char *name);

PROTOBUF_C__API
const ProtobufCEnumValue *
protobuf_c_enum_descriptor_get_value(
    const ProtobufCEnumDescriptor *desc,
    int value);

PROTOBUF_C__API
const ProtobufCFieldDescriptor *
protobuf_c_message_descriptor_get_field_by_name(
    const ProtobufCMessageDescriptor *desc,
    const char *name);

PROTOBUF_C__API
const ProtobufCFieldDescriptor *
protobuf_c_message_descriptor_get_field(
    const ProtobufCMessageDescriptor *desc,
    unsigned value);

PROTOBUF_C__API
size_t
protobuf_c_message_get_packed_size(const ProtobufCMessage *message);

PROTOBUF_C__API
size_t
protobuf_c_message_pack(const ProtobufCMessage *message, uint8_t *out);

PROTOBUF_C__API
size_t
protobuf_c_message_pack_to_buffer(
    const ProtobufCMessage *message,
    ProtobufCBuffer *buffer);

PROTOBUF_C__API
ProtobufCMessage *
protobuf_c_message_unpack(
    const ProtobufCMessageDescriptor *descriptor,
    ProtobufCAllocator *allocator,
    size_t len,
    const uint8_t *data);

PROTOBUF_C__API
void
protobuf_c_message_free_unpacked(
    ProtobufCMessage *message,
    ProtobufCAllocator *allocator);

PROTOBUF_C__API
protobuf_c_boolean
protobuf_c_message_check(const ProtobufCMessage *);

#define PROTOBUF_C_MESSAGE_INIT(descriptor) { descriptor, 0, NULL }

PROTOBUF_C__API
void
protobuf_c_message_init(
    const ProtobufCMessageDescriptor *descriptor,
    void *message);

PROTOBUF_C__API
void
protobuf_c_service_destroy(ProtobufCService *service);

PROTOBUF_C__API
const ProtobufCMethodDescriptor *
protobuf_c_service_descriptor_get_method_by_name(
    const ProtobufCServiceDescriptor *desc,
    const char *name);

#define PROTOBUF_C_BUFFER_SIMPLE_INIT(array_of_bytes)                   \
{                                                                       \
    { protobuf_c_buffer_simple_append },                            \
    sizeof(array_of_bytes),                                         \
    0,                                                              \
    (array_of_bytes),                                               \
    0,                                                              \
    NULL                                                            \
}

#define PROTOBUF_C_BUFFER_SIMPLE_CLEAR(simp_buf)                        \
do {                                                                    \
    if ((simp_buf)->must_free_data) {                               \
        if ((simp_buf)->allocator != NULL)                      \
            (simp_buf)->allocator->free(                    \
                (simp_buf)->allocator,                  \
                (simp_buf)->data);          \
        else                                                    \
            free((simp_buf)->data);                         \
    }                                                               \
} while (0)

PROTOBUF_C__API
void
protobuf_c_buffer_simple_append(
    ProtobufCBuffer *buffer,
    size_t len,
    const unsigned char *data);

PROTOBUF_C__API
void
protobuf_c_service_generated_init(
    ProtobufCService *service,
    const ProtobufCServiceDescriptor *descriptor,
    ProtobufCServiceDestroy destroy);

PROTOBUF_C__API
void
protobuf_c_service_invoke_internal(
    ProtobufCService *service,
    unsigned method_index,
    const ProtobufCMessage *input,
    ProtobufCClosure closure,
    void *closure_data);

PROTOBUF_C__END_DECLS

#endif /* PROTOBUF_C_H */