#$@%#$%!

Ngiler SH3LL 360
: / proc / thread-self / root / usr / include / google / protobuf-c /

Information Server
MySQL : OFF Perl : OFF CURL : ON WGET : OFF PKEXEC : OFF

Directive	Local Value
IP Address	162.0.209.101
System	Linux premium169.web-hosting.com 4.18.0-553.50.1.lve.el8.x86_64 #1 SMP Thu Apr 17 19:10:24 UTC 2025 x86_64
User	luxeelil
PHP Version	8.0.30
Software	LiteSpeed
Doc root	Writable

Edit File : protobuf-c.h \| Size : 32.77 KB
/* * Copyright (c) 2008-2017, 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. / /! \file * \mainpage Introduction * * This is [protobuf-c], a C implementation of [Protocol Buffers]. * * This file defines the public API for the `libprotobuf-c` support library. * This API includes interfaces that can be used directly by client code as well * as the interfaces used by the code generated by the `protoc-c` compiler. * * The `libprotobuf-c` support library performs the actual serialization and * deserialization of Protocol Buffers messages. It interacts with structures, * definitions, and metadata generated by the `protoc-c` compiler from .proto * files. * * \authors Dave Benson and the `protobuf-c` authors. * * \copyright 2008-2014. Licensed under the terms of the [BSD-2-Clause] license. * * [protobuf-c]: https://github.com/protobuf-c/protobuf-c * [Protocol Buffers]: https://developers.google.com/protocol-buffers/ * [BSD-2-Clause]: http://opensource.org/licenses/BSD-2-Clause * * \page gencode Generated Code * * For each enum, we generate a C enum. For each message, we generate a C * structure which can be cast to a `ProtobufCMessage`. * * For each enum and message, we generate a descriptor object that allows us to * implement a kind of reflection on the structures. * * First, some naming conventions: * * - The name of the type for enums and messages and services is camel case * (meaning WordsAreCrammedTogether) except that double underscores are used * to delimit scopes. For example, the following `.proto` file: * ~~~{.proto} package foo.bar; message BazBah { optional int32 val = 1; } ~~~ * * would generate a C type `Foo__Bar__BazBah`. * * - Identifiers for functions and globals are all lowercase, with camel case * words separated by single underscores. For example, one of the function * prototypes generated by `protoc-c` for the above example: * ~~~{.c} Foo__Bar__BazBah * foo__bar__baz_bah__unpack (ProtobufCAllocator allocator, size_t len, const uint8_t data); ~~~ * * - Identifiers for enum values contain an uppercase prefix which embeds the * package name and the enum type name. * * - A double underscore is used to separate further components of identifier * names. * * For example, in the name of the unpack function above, the package name * `foo.bar` has become `foo__bar`, the message name BazBah has become * `baz_bah`, and the method name is `unpack`. These are all joined with double * underscores to form the C identifier `foo__bar__baz_bah__unpack`. * * We also generate descriptor objects for messages and enums. These are * declared in the `.pb-c.h` files: * ~~~{.c} extern const ProtobufCMessageDescriptor foo__bar__baz_bah__descriptor; ~~~ * * The message structures all begin with `ProtobufCMessageDescriptor ` which is sufficient to allow them to be cast to `ProtobufCMessage`. * * For each message defined in a `.proto` file, we generate a number of * functions and macros. Each function name contains a prefix based on the * package name and message name in order to make it a unique C identifier. * * - `INIT`. Statically initializes a message object, initializing its * descriptor and setting its fields to default values. Uninitialized * messages cannot be processed by the protobuf-c library. * ~~~{.c} #define FOO__BAR__BAZ_BAH__INIT \ { PROTOBUF_C_MESSAGE_INIT (&foo__bar__baz_bah__descriptor), 0 } ~~~ * - `init()`. Initializes a message object, initializing its descriptor and * setting its fields to default values. Uninitialized messages cannot be * processed by the protobuf-c library. * ~~~{.c} void foo__bar__baz_bah__init (Foo__Bar__BazBah message); ~~~ - `unpack()`. Unpacks data for a particular message format. Note that the * `allocator` parameter is usually `NULL` to indicate that the system's * `malloc()` and `free()` functions should be used for dynamically allocating * memory. * ~~~{.c} Foo__Bar__BazBah * foo__bar__baz_bah__unpack (ProtobufCAllocator allocator, size_t len, const uint8_t data); ~~~ * * - `free_unpacked()`. Frees a message object obtained with the `unpack()` * method. Freeing `NULL` is allowed (the same as with `free()`). * ~~~{.c} void foo__bar__baz_bah__free_unpacked (Foo__Bar__BazBah message, ProtobufCAllocator allocator); ~~~ * * - `get_packed_size()`. Calculates the length in bytes of the serialized * representation of the message object. * ~~~{.c} size_t foo__bar__baz_bah__get_packed_size (const Foo__Bar__BazBah message); ~~~ * - `pack()`. Pack a message object into a preallocated buffer. Assumes that * the buffer is large enough. (Use `get_packed_size()` first.) * ~~~{.c} size_t foo__bar__baz_bah__pack (const Foo__Bar__BazBah message, uint8_t out); ~~~ * * - `pack_to_buffer()`. Packs a message into a "virtual buffer". This is an * object which defines an "append bytes" callback to consume data as it is * serialized. * ~~~{.c} size_t foo__bar__baz_bah__pack_to_buffer (const Foo__Bar__BazBah message, ProtobufCBuffer buffer); ~~~ * * \page pack Packing and unpacking messages * * To pack a message, first compute the packed size of the message with * protobuf_c_message_get_packed_size(), then allocate a buffer of at least * that size, then call protobuf_c_message_pack(). * * Alternatively, a message can be serialized without calculating the final size * first. Use the protobuf_c_message_pack_to_buffer() function and provide a * ProtobufCBuffer object which implements an "append" method that consumes * data. * * To unpack a message, call the protobuf_c_message_unpack() function. The * result can be cast to an object of the type that matches the descriptor for * the message. * * The result of unpacking a message should be freed with * protobuf_c_message_free_unpacked(). / #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 / Empty string used for initializers / extern const char protobuf_c_empty_string[]; /* * \defgroup api Public API * * This is the public API for `libprotobuf-c`. These interfaces are stable and * subject to Semantic Versioning guarantees. * * @{ / /* * Values for the `flags` word in `ProtobufCFieldDescriptor`. / typedef enum { /* Set if the field is repeated and marked with the `packed` option. / PROTOBUF_C_FIELD_FLAG_PACKED = (1 << 0), /* Set if the field is marked with the `deprecated` option. / PROTOBUF_C_FIELD_FLAG_DEPRECATED = (1 << 1), /* Set if the field is a member of a oneof (union). / PROTOBUF_C_FIELD_FLAG_ONEOF = (1 << 2), } ProtobufCFieldFlag; /* * Message field rules. * * \see [Defining A Message Type] in the Protocol Buffers documentation. * * [Defining A Message Type]: * https://developers.google.com/protocol-buffers/docs/proto#simple / typedef enum { /* A well-formed message must have exactly one of this field. / PROTOBUF_C_LABEL_REQUIRED, /* * A well-formed message can have zero or one of this field (but not * more than one). / PROTOBUF_C_LABEL_OPTIONAL, /* * This field can be repeated any number of times (including zero) in a * well-formed message. The order of the repeated values will be * preserved. / PROTOBUF_C_LABEL_REPEATED, /* * This field has no label. This is valid only in proto3 and is * equivalent to OPTIONAL but no "has" quantifier will be consulted. / PROTOBUF_C_LABEL_NONE, } ProtobufCLabel; /* * Field value types. * * \see [Scalar Value Types] in the Protocol Buffers documentation. * * [Scalar Value Types]: * https://developers.google.com/protocol-buffers/docs/proto#scalar / typedef enum { PROTOBUF_C_TYPE_INT32, /< int32 / PROTOBUF_C_TYPE_SINT32, /*< signed int32 / PROTOBUF_C_TYPE_SFIXED32, /*< signed int32 (4 bytes) / PROTOBUF_C_TYPE_INT64, /*< int64 / PROTOBUF_C_TYPE_SINT64, /*< signed int64 / PROTOBUF_C_TYPE_SFIXED64, /*< signed int64 (8 bytes) / PROTOBUF_C_TYPE_UINT32, /*< unsigned int32 / PROTOBUF_C_TYPE_FIXED32, /*< unsigned int32 (4 bytes) / PROTOBUF_C_TYPE_UINT64, /*< unsigned int64 / PROTOBUF_C_TYPE_FIXED64, /*< unsigned int64 (8 bytes) / PROTOBUF_C_TYPE_FLOAT, /*< float / PROTOBUF_C_TYPE_DOUBLE, /*< double / PROTOBUF_C_TYPE_BOOL, /*< boolean / PROTOBUF_C_TYPE_ENUM, /*< enumerated type / PROTOBUF_C_TYPE_STRING, /*< UTF-8 or ASCII string / PROTOBUF_C_TYPE_BYTES, /*< arbitrary byte sequence / PROTOBUF_C_TYPE_MESSAGE, /*< nested message / } ProtobufCType; /** * Field wire types. * * \see [Message Structure] in the Protocol Buffers documentation. * * [Message Structure]: * https://developers.google.com/protocol-buffers/docs/encoding#structure / 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; /* Boolean type. / typedef int protobuf_c_boolean; typedef void (ProtobufCClosure)(const ProtobufCMessage , void closure_data); typedef void (ProtobufCMessageInit)(ProtobufCMessage ); typedef void (ProtobufCServiceDestroy)(ProtobufCService ); /** * Structure for defining a custom memory allocator. / struct ProtobufCAllocator { /* Function to allocate memory. / void (alloc)(void allocator_data, size_t size); /** Function to free memory. / void (free)(void allocator_data, void pointer); /** Opaque pointer passed to `alloc` and `free` functions. / void allocator_data; }; /** * Structure for the protobuf `bytes` scalar type. * * The data contained in a `ProtobufCBinaryData` is an arbitrary sequence of * bytes. It may contain embedded `NUL` characters and is not required to be * `NUL`-terminated. / struct ProtobufCBinaryData { size_t len; /< Number of bytes in the `data` field. / uint8_t data; /< Data bytes. / }; /** * Structure for defining a virtual append-only buffer. Used by * protobuf_c_message_pack_to_buffer() to abstract the consumption of serialized * bytes. * * `ProtobufCBuffer` "subclasses" may be defined on the stack. For example, to * write to a `FILE` object: * ~~~{.c} typedef struct { ProtobufCBuffer base; FILE fp; } BufferAppendToFile; static void my_buffer_file_append(ProtobufCBuffer buffer, size_t len, const uint8_t data) { BufferAppendToFile file_buf = (BufferAppendToFile ) buffer; fwrite(data, len, 1, file_buf->fp); // XXX: No error handling! } ~~~ * To use this new type of ProtobufCBuffer, it could be called as follows: * ~~~{.c} ... BufferAppendToFile tmp = {0}; tmp.base.append = my_buffer_file_append; tmp.fp = fp; protobuf_c_message_pack_to_buffer(&message, &tmp); ... ~~~ / struct ProtobufCBuffer { /* Append function. Consumes the `len` bytes stored at `data`. / void (append)(ProtobufCBuffer buffer, size_t len, const uint8_t data); }; /** * Simple buffer "subclass" of `ProtobufCBuffer`. * * A `ProtobufCBufferSimple` object is declared on the stack and uses a * scratch buffer provided by the user for the initial allocation. It performs * exponential resizing, using dynamically allocated memory. A * `ProtobufCBufferSimple` object can be created and used as follows: * ~~~{.c} uint8_t pad[128]; ProtobufCBufferSimple simple = PROTOBUF_C_BUFFER_SIMPLE_INIT(pad); ProtobufCBuffer buffer = (ProtobufCBuffer ) &simple; ~~~ * * `buffer` can now be used with `protobuf_c_message_pack_to_buffer()`. Once a * message has been serialized to a `ProtobufCBufferSimple` object, the * serialized data bytes can be accessed from the `.data` field. * * To free the memory allocated by a `ProtobufCBufferSimple` object, if any, * call PROTOBUF_C_BUFFER_SIMPLE_CLEAR() on the object, for example: * ~~~{.c} PROTOBUF_C_BUFFER_SIMPLE_CLEAR(&simple); ~~~ * * \see PROTOBUF_C_BUFFER_SIMPLE_INIT * \see PROTOBUF_C_BUFFER_SIMPLE_CLEAR / struct ProtobufCBufferSimple { /* "Base class". / ProtobufCBuffer base; /* Number of bytes allocated in `data`. / size_t alloced; /* Number of bytes currently stored in `data`. / size_t len; /* Data bytes. / uint8_t data; /** Whether `data` must be freed. / protobuf_c_boolean must_free_data; /* Allocator to use. May be NULL to indicate the system allocator. / ProtobufCAllocator allocator; }; /** * Describes an enumeration as a whole, with all of its values. / struct ProtobufCEnumDescriptor { /* Magic value checked to ensure that the API is used correctly. / uint32_t magic; /* The qualified name (e.g., "namespace.Type"). / const char name; /** The unqualified name as given in the .proto file (e.g., "Type"). / const char short_name; /** Identifier used in generated C code. / const char c_name; /** The dot-separated namespace. / const char package_name; /** Number elements in `values`. / unsigned n_values; /* Array of distinct values, sorted by numeric value. / const ProtobufCEnumValue values; /** Number of elements in `values_by_name`. / unsigned n_value_names; /* Array of named values, including aliases, sorted by name. / const ProtobufCEnumValueIndex values_by_name; /** Number of elements in `value_ranges`. / unsigned n_value_ranges; /* Value ranges, for faster lookups by numeric value. / const ProtobufCIntRange value_ranges; /** Reserved for future use. / void reserved1; /** Reserved for future use. / void reserved2; /** Reserved for future use. / void reserved3; /** Reserved for future use. / void reserved4; }; /** * Represents a single value of an enumeration. / struct ProtobufCEnumValue { /* The string identifying this value in the .proto file. / const char name; /** The string identifying this value in generated C code. / const char c_name; /** The numeric value assigned in the .proto file. / int value; }; /* * Used by `ProtobufCEnumDescriptor` to look up enum values. / struct ProtobufCEnumValueIndex { /* Name of the enum value. / const char name; /** Index into values[] array. / unsigned index; }; /* * Describes a single field in a message. / struct ProtobufCFieldDescriptor { /* Name of the field as given in the .proto file. / const char name; /** Tag value of the field as given in the .proto file. / uint32_t id; /* Whether the field is `REQUIRED`, `OPTIONAL`, or `REPEATED`. / ProtobufCLabel label; /* The type of the field. / ProtobufCType type; /* * The offset in bytes of the message's C structure's quantifier field * (the `has_MEMBER` field for optional members or the `n_MEMBER` field * for repeated members or the case enum for oneofs). / unsigned quantifier_offset; /* * The offset in bytes into the message's C structure for the member * itself. / unsigned offset; /* * A type-specific descriptor. * * If `type` is `PROTOBUF_C_TYPE_ENUM`, then `descriptor` points to the * corresponding `ProtobufCEnumDescriptor`. * * If `type` is `PROTOBUF_C_TYPE_MESSAGE`, then `descriptor` points to * the corresponding `ProtobufCMessageDescriptor`. * * Otherwise this field is NULL. / const void descriptor; /* for MESSAGE and ENUM types / /* The default value for this field, if defined. May be NULL. / const void default_value; /** * A flag word. Zero or more of the bits defined in the * `ProtobufCFieldFlag` enum may be set. / uint32_t flags; /* Reserved for future use. / unsigned reserved_flags; /* Reserved for future use. / void reserved2; /** Reserved for future use. / void reserved3; }; /** * Helper structure for optimizing int => index lookups in the case * where the keys are mostly consecutive values, as they presumably are for * enums and fields. * * The data structures requires that the values in the original array are * sorted. / 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. / }; /* * An instance of a message. * * `ProtobufCMessage` is a light-weight "base class" for all messages. * * In particular, `ProtobufCMessage` doesn't have any allocation policy * associated with it. That's because it's common to create `ProtobufCMessage` * objects on the stack. In fact, that's what we recommend for sending messages. * If the object is allocated from the stack, you can't really have a memory * leak. * * This means that calls to functions like protobuf_c_message_unpack() which * return a `ProtobufCMessage` must be paired with a call to a free function, * like protobuf_c_message_free_unpacked(). / struct ProtobufCMessage { /* The descriptor for this message type. / const ProtobufCMessageDescriptor descriptor; /** The number of elements in `unknown_fields`. / unsigned n_unknown_fields; /* The fields that weren't recognized by the parser. / ProtobufCMessageUnknownField unknown_fields; }; /** * Describes a message. / struct ProtobufCMessageDescriptor { /* Magic value checked to ensure that the API is used correctly. / uint32_t magic; /* The qualified name (e.g., "namespace.Type"). / const char name; /** The unqualified name as given in the .proto file (e.g., "Type"). / const char short_name; /** Identifier used in generated C code. / const char c_name; /** The dot-separated namespace. / const char package_name; /** * Size in bytes of the C structure representing an instance of this * type of message. / size_t sizeof_message; /* Number of elements in `fields`. / unsigned n_fields; /* Field descriptors, sorted by tag number. / const ProtobufCFieldDescriptor fields; /** Used for looking up fields by name. / const unsigned fields_sorted_by_name; /** Number of elements in `field_ranges`. / unsigned n_field_ranges; /* Used for looking up fields by id. / const ProtobufCIntRange field_ranges; /** Message initialisation function. / ProtobufCMessageInit message_init; /* Reserved for future use. / void reserved1; /** Reserved for future use. / void reserved2; /** Reserved for future use. / void reserved3; }; /** * An unknown message field. / struct ProtobufCMessageUnknownField { /* The tag number. / uint32_t tag; /* The wire type of the field. / ProtobufCWireType wire_type; /* Number of bytes in `data`. / size_t len; /* Field data. / uint8_t data; }; /** * Method descriptor. / struct ProtobufCMethodDescriptor { /* Method name. / const char name; /** Input message descriptor. / const ProtobufCMessageDescriptor input; /** Output message descriptor. / const ProtobufCMessageDescriptor output; }; /** * Service. / struct ProtobufCService { /* Service descriptor. / const ProtobufCServiceDescriptor descriptor; /** Function to invoke the service. / void (invoke)(ProtobufCService service, unsigned method_index, const ProtobufCMessage input, ProtobufCClosure closure, void closure_data); /* Function to destroy the service. / void (destroy)(ProtobufCService service); }; /* * Service descriptor. / struct ProtobufCServiceDescriptor { /* Magic value checked to ensure that the API is used correctly. / uint32_t magic; /* Service name. / const char name; /** Short version of service name. / const char short_name; /** C identifier for the service name. / const char c_name; /** Package name. / const char package; /** Number of elements in `methods`. / unsigned n_methods; /* Method descriptors, in the order defined in the .proto file. / const ProtobufCMethodDescriptor methods; /** Sort index of methods. / const unsigned method_indices_by_name; }; /** * Get the version of the protobuf-c library. Note that this is the version of * the library linked against, not the version of the headers compiled against. * * \return A string containing the version number of protobuf-c. / PROTOBUF_C__API const char protobuf_c_version(void); /** * Get the version of the protobuf-c library. Note that this is the version of * the library linked against, not the version of the headers compiled against. * * \return A 32 bit unsigned integer containing the version number of * protobuf-c, represented in base-10 as (MAJOR1E6) + (MINOR1E3) + PATCH. / PROTOBUF_C__API uint32_t protobuf_c_version_number(void); /* * The version of the protobuf-c headers, represented as a string using the same * format as protobuf_c_version(). / #define PROTOBUF_C_VERSION "1.3.0" /* * The version of the protobuf-c headers, represented as an integer using the * same format as protobuf_c_version_number(). / #define PROTOBUF_C_VERSION_NUMBER 1003000 /* * The minimum protoc-c version which works with the current version of the * protobuf-c headers. / #define PROTOBUF_C_MIN_COMPILER_VERSION 1000000 /* * Look up a `ProtobufCEnumValue` from a `ProtobufCEnumDescriptor` by name. * * \param desc * The `ProtobufCEnumDescriptor` object. * \param name * The `name` field from the corresponding `ProtobufCEnumValue` object to * match. * \return * A `ProtobufCEnumValue` object. * \retval NULL * If not found or if the optimize_for = CODE_SIZE option was set. / PROTOBUF_C__API const ProtobufCEnumValue protobuf_c_enum_descriptor_get_value_by_name( const ProtobufCEnumDescriptor desc, const char name); /** * Look up a `ProtobufCEnumValue` from a `ProtobufCEnumDescriptor` by numeric * value. * * \param desc * The `ProtobufCEnumDescriptor` object. * \param value * The `value` field from the corresponding `ProtobufCEnumValue` object to * match. * * \return * A `ProtobufCEnumValue` object. * \retval NULL * If not found. / PROTOBUF_C__API const ProtobufCEnumValue protobuf_c_enum_descriptor_get_value( const ProtobufCEnumDescriptor desc, int value); /* * Look up a `ProtobufCFieldDescriptor` from a `ProtobufCMessageDescriptor` by * the name of the field. * * \param desc * The `ProtobufCMessageDescriptor` object. * \param name * The name of the field. * \return * A `ProtobufCFieldDescriptor` object. * \retval NULL * If not found or if the optimize_for = CODE_SIZE option was set. / PROTOBUF_C__API const ProtobufCFieldDescriptor protobuf_c_message_descriptor_get_field_by_name( const ProtobufCMessageDescriptor desc, const char name); /** * Look up a `ProtobufCFieldDescriptor` from a `ProtobufCMessageDescriptor` by * the tag value of the field. * * \param desc * The `ProtobufCMessageDescriptor` object. * \param value * The tag value of the field. * \return * A `ProtobufCFieldDescriptor` object. * \retval NULL * If not found. / PROTOBUF_C__API const ProtobufCFieldDescriptor protobuf_c_message_descriptor_get_field( const ProtobufCMessageDescriptor desc, unsigned value); /* * Determine the number of bytes required to store the serialised message. * * \param message * The message object to serialise. * \return * Number of bytes. / PROTOBUF_C__API size_t protobuf_c_message_get_packed_size(const ProtobufCMessage message); /** * Serialise a message from its in-memory representation. * * This function stores the serialised bytes of the message in a pre-allocated * buffer. * * \param message * The message object to serialise. * \param[out] out * Buffer to store the bytes of the serialised message. This buffer must * have enough space to store the packed message. Use * protobuf_c_message_get_packed_size() to determine the number of bytes * required. * \return * Number of bytes stored in `out`. / PROTOBUF_C__API size_t protobuf_c_message_pack(const ProtobufCMessage message, uint8_t out); /* * Serialise a message from its in-memory representation to a virtual buffer. * * This function calls the `append` method of a `ProtobufCBuffer` object to * consume the bytes generated by the serialiser. * * \param message * The message object to serialise. * \param buffer * The virtual buffer object. * \return * Number of bytes passed to the virtual buffer. / PROTOBUF_C__API size_t protobuf_c_message_pack_to_buffer( const ProtobufCMessage message, ProtobufCBuffer buffer); /* * Unpack a serialised message into an in-memory representation. * * \param descriptor * The message descriptor. * \param allocator * `ProtobufCAllocator` to use for memory allocation. May be NULL to * specify the default allocator. * \param len * Length in bytes of the serialised message. * \param data * Pointer to the serialised message. * \return * An unpacked message object. * \retval NULL * If an error occurred during unpacking. / PROTOBUF_C__API ProtobufCMessage protobuf_c_message_unpack( const ProtobufCMessageDescriptor descriptor, ProtobufCAllocator allocator, size_t len, const uint8_t data); /* * Free an unpacked message object. * * This function should be used to deallocate the memory used by a call to * protobuf_c_message_unpack(). * * \param message * The message object to free. May be NULL. * \param allocator * `ProtobufCAllocator` to use for memory deallocation. May be NULL to * specify the default allocator. / PROTOBUF_C__API void protobuf_c_message_free_unpacked( ProtobufCMessage message, ProtobufCAllocator allocator); /* * Check the validity of a message object. * * Makes sure all required fields (`PROTOBUF_C_LABEL_REQUIRED`) are present. * Recursively checks nested messages. * * \retval TRUE * Message is valid. * \retval FALSE * Message is invalid. / PROTOBUF_C__API protobuf_c_boolean protobuf_c_message_check(const ProtobufCMessage ); /** Message initialiser. / #define PROTOBUF_C_MESSAGE_INIT(descriptor) { descriptor, 0, NULL } /* * Initialise a message object from a message descriptor. * * \param descriptor * Message descriptor. * \param message * Allocated block of memory of size `descriptor->sizeof_message`. / PROTOBUF_C__API void protobuf_c_message_init( const ProtobufCMessageDescriptor descriptor, void message); /* * Free a service. * * \param service * The service object to free. / PROTOBUF_C__API void protobuf_c_service_destroy(ProtobufCService service); /** * Look up a `ProtobufCMethodDescriptor` by name. * * \param desc * Service descriptor. * \param name * Name of the method. * * \return * A `ProtobufCMethodDescriptor` object. * \retval NULL * If not found or if the optimize_for = CODE_SIZE option was set. / PROTOBUF_C__API const ProtobufCMethodDescriptor protobuf_c_service_descriptor_get_method_by_name( const ProtobufCServiceDescriptor desc, const char name); /** * Initialise a `ProtobufCBufferSimple` object. / #define PROTOBUF_C_BUFFER_SIMPLE_INIT(array_of_bytes) \ { \ { protobuf_c_buffer_simple_append }, \ sizeof(array_of_bytes), \ 0, \ (array_of_bytes), \ 0, \ NULL \ } /* * Clear a `ProtobufCBufferSimple` object, freeing any allocated memory. / #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) /* * The `append` method for `ProtobufCBufferSimple`. * * \param buffer * The buffer object to append to. Must actually be a * `ProtobufCBufferSimple` object. * \param len * Number of bytes in `data`. * \param data * Data to append. / 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 */ Back

Edit File : protobuf-c.h | Size : 32.77 KB

/*
 * Copyright (c) 2008-2017, 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.
 */

/*! \file
 * \mainpage Introduction
 *
 * This is [protobuf-c], a C implementation of [Protocol Buffers].
 *
 * This file defines the public API for the `libprotobuf-c` support library.
 * This API includes interfaces that can be used directly by client code as well
 * as the interfaces used by the code generated by the `protoc-c` compiler.
 *
 * The `libprotobuf-c` support library performs the actual serialization and
 * deserialization of Protocol Buffers messages. It interacts with structures,
 * definitions, and metadata generated by the `protoc-c` compiler from .proto
 * files.
 *
 * \authors Dave Benson and the `protobuf-c` authors.
 *
 * \copyright 2008-2014. Licensed under the terms of the [BSD-2-Clause] license.
 *
 * [protobuf-c]:       https://github.com/protobuf-c/protobuf-c
 * [Protocol Buffers]: https://developers.google.com/protocol-buffers/
 * [BSD-2-Clause]:     http://opensource.org/licenses/BSD-2-Clause
 *
 * \page gencode Generated Code
 *
 * For each enum, we generate a C enum. For each message, we generate a C
 * structure which can be cast to a `ProtobufCMessage`.
 *
 * For each enum and message, we generate a descriptor object that allows us to
 * implement a kind of reflection on the structures.
 *
 * First, some naming conventions:
 *
 * - The name of the type for enums and messages and services is camel case
 *   (meaning WordsAreCrammedTogether) except that double underscores are used
 *   to delimit scopes. For example, the following `.proto` file:
 *
~~~{.proto}
        package foo.bar;
        message BazBah {
            optional int32 val = 1;
        }
~~~
 *
 * would generate a C type `Foo__Bar__BazBah`.
 *
 * - Identifiers for functions and globals are all lowercase, with camel case
 *   words separated by single underscores. For example, one of the function
 *   prototypes generated by `protoc-c` for the above example:
 *
~~~{.c}
Foo__Bar__BazBah *
       foo__bar__baz_bah__unpack
                     (ProtobufCAllocator  *allocator,
                      size_t               len,
                      const uint8_t       *data);
~~~
 *
 * - Identifiers for enum values contain an uppercase prefix which embeds the
 *   package name and the enum type name.
 *
 * - A double underscore is used to separate further components of identifier
 *   names.
 *
 * For example, in the name of the unpack function above, the package name
 * `foo.bar` has become `foo__bar`, the message name BazBah has become
 * `baz_bah`, and the method name is `unpack`. These are all joined with double
 * underscores to form the C identifier `foo__bar__baz_bah__unpack`.
 *
 * We also generate descriptor objects for messages and enums. These are
 * declared in the `.pb-c.h` files:
 *
~~~{.c}
extern const ProtobufCMessageDescriptor foo__bar__baz_bah__descriptor;
~~~
 *
 * The message structures all begin with `ProtobufCMessageDescriptor *` which is
 * sufficient to allow them to be cast to `ProtobufCMessage`.
 *
 * For each message defined in a `.proto` file, we generate a number of
 * functions and macros. Each function name contains a prefix based on the
 * package name and message name in order to make it a unique C identifier.
 *
 * - `INIT`. Statically initializes a message object, initializing its
 *   descriptor and setting its fields to default values. Uninitialized
 *   messages cannot be processed by the protobuf-c library.
 *
~~~{.c}
#define FOO__BAR__BAZ_BAH__INIT \
 { PROTOBUF_C_MESSAGE_INIT (&foo__bar__baz_bah__descriptor), 0 }
~~~
 * - `init()`. Initializes a message object, initializing its descriptor and
 *   setting its fields to default values. Uninitialized messages cannot be
 *   processed by the protobuf-c library.
 *
~~~{.c}
void foo__bar__baz_bah__init
                     (Foo__Bar__BazBah *message);
~~~
 * - `unpack()`. Unpacks data for a particular message format. Note that the
 *   `allocator` parameter is usually `NULL` to indicate that the system's
 *   `malloc()` and `free()` functions should be used for dynamically allocating
 *   memory.
 *
~~~{.c}
Foo__Bar__BazBah *
       foo__bar__baz_bah__unpack
                     (ProtobufCAllocator  *allocator,
                      size_t               len,
                      const uint8_t       *data);
~~~
 *
 * - `free_unpacked()`. Frees a message object obtained with the `unpack()`
 *   method. Freeing `NULL` is allowed (the same as with `free()`).
 *
~~~{.c}
void   foo__bar__baz_bah__free_unpacked
                     (Foo__Bar__BazBah *message,
                      ProtobufCAllocator *allocator);
~~~
 *
 * - `get_packed_size()`. Calculates the length in bytes of the serialized
 *   representation of the message object.
 *
~~~{.c}
size_t foo__bar__baz_bah__get_packed_size
                     (const Foo__Bar__BazBah   *message);
~~~
 *
 * - `pack()`. Pack a message object into a preallocated buffer. Assumes that
 *   the buffer is large enough. (Use `get_packed_size()` first.)
 *
~~~{.c}
size_t foo__bar__baz_bah__pack
                     (const Foo__Bar__BazBah   *message,
                      uint8_t             *out);
~~~
 *
 * - `pack_to_buffer()`. Packs a message into a "virtual buffer". This is an
 *   object which defines an "append bytes" callback to consume data as it is
 *   serialized.
 *
~~~{.c}
size_t foo__bar__baz_bah__pack_to_buffer
                     (const Foo__Bar__BazBah   *message,
                      ProtobufCBuffer     *buffer);
~~~
 *
 * \page pack Packing and unpacking messages
 *
 * To pack a message, first compute the packed size of the message with
 * protobuf_c_message_get_packed_size(), then allocate a buffer of at least
 * that size, then call protobuf_c_message_pack().
 *
 * Alternatively, a message can be serialized without calculating the final size
 * first. Use the protobuf_c_message_pack_to_buffer() function and provide a
 * ProtobufCBuffer object which implements an "append" method that consumes
 * data.
 *
 * To unpack a message, call the protobuf_c_message_unpack() function. The
 * result can be cast to an object of the type that matches the descriptor for
 * the message.
 *
 * The result of unpacking a message should be freed with
 * protobuf_c_message_free_unpacked().
 */

#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

/* Empty string used for initializers */
extern const char protobuf_c_empty_string[];

/**
 * \defgroup api Public API
 *
 * This is the public API for `libprotobuf-c`. These interfaces are stable and
 * subject to Semantic Versioning guarantees.
 *
 * @{
 */

/**
 * Values for the `flags` word in `ProtobufCFieldDescriptor`.
 */
typedef enum {
	/** Set if the field is repeated and marked with the `packed` option. */
	PROTOBUF_C_FIELD_FLAG_PACKED		= (1 << 0),

/** Set if the field is marked with the `deprecated` option. */
	PROTOBUF_C_FIELD_FLAG_DEPRECATED	= (1 << 1),

/** Set if the field is a member of a oneof (union). */
	PROTOBUF_C_FIELD_FLAG_ONEOF		= (1 << 2),
} ProtobufCFieldFlag;

/**
 * Message field rules.
 *
 * \see [Defining A Message Type] in the Protocol Buffers documentation.
 *
 * [Defining A Message Type]:
 *      https://developers.google.com/protocol-buffers/docs/proto#simple
 */
typedef enum {
	/** A well-formed message must have exactly one of this field. */
	PROTOBUF_C_LABEL_REQUIRED,

/**
	 * A well-formed message can have zero or one of this field (but not
	 * more than one).
	 */
	PROTOBUF_C_LABEL_OPTIONAL,

/**
	 * This field can be repeated any number of times (including zero) in a
	 * well-formed message. The order of the repeated values will be
	 * preserved.
	 */
	PROTOBUF_C_LABEL_REPEATED,

/**
	 * This field has no label. This is valid only in proto3 and is
	 * equivalent to OPTIONAL but no "has" quantifier will be consulted.
	 */
	PROTOBUF_C_LABEL_NONE,
} ProtobufCLabel;

/**
 * Field value types.
 *
 * \see [Scalar Value Types] in the Protocol Buffers documentation.
 *
 * [Scalar Value Types]:
 *      https://developers.google.com/protocol-buffers/docs/proto#scalar
 */
typedef enum {
	PROTOBUF_C_TYPE_INT32,      /**< int32 */
	PROTOBUF_C_TYPE_SINT32,     /**< signed int32 */
	PROTOBUF_C_TYPE_SFIXED32,   /**< signed int32 (4 bytes) */
	PROTOBUF_C_TYPE_INT64,      /**< int64 */
	PROTOBUF_C_TYPE_SINT64,     /**< signed int64 */
	PROTOBUF_C_TYPE_SFIXED64,   /**< signed int64 (8 bytes) */
	PROTOBUF_C_TYPE_UINT32,     /**< unsigned int32 */
	PROTOBUF_C_TYPE_FIXED32,    /**< unsigned int32 (4 bytes) */
	PROTOBUF_C_TYPE_UINT64,     /**< unsigned int64 */
	PROTOBUF_C_TYPE_FIXED64,    /**< unsigned int64 (8 bytes) */
	PROTOBUF_C_TYPE_FLOAT,      /**< float */
	PROTOBUF_C_TYPE_DOUBLE,     /**< double */
	PROTOBUF_C_TYPE_BOOL,       /**< boolean */
	PROTOBUF_C_TYPE_ENUM,       /**< enumerated type */
	PROTOBUF_C_TYPE_STRING,     /**< UTF-8 or ASCII string */
	PROTOBUF_C_TYPE_BYTES,      /**< arbitrary byte sequence */
	PROTOBUF_C_TYPE_MESSAGE,    /**< nested message */
} ProtobufCType;

/**
 * Field wire types.
 *
 * \see [Message Structure] in the Protocol Buffers documentation.
 *
 * [Message Structure]:
 *      https://developers.google.com/protocol-buffers/docs/encoding#structure
 */
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;

/** Boolean type. */
typedef int protobuf_c_boolean;

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

/**
 * Structure for defining a custom memory allocator.
 */
struct ProtobufCAllocator {
	/** Function to allocate memory. */
	void		*(*alloc)(void *allocator_data, size_t size);

/** Function to free memory. */
	void		(*free)(void *allocator_data, void *pointer);

/** Opaque pointer passed to `alloc` and `free` functions. */
	void		*allocator_data;
};

/**
 * Structure for the protobuf `bytes` scalar type.
 *
 * The data contained in a `ProtobufCBinaryData` is an arbitrary sequence of
 * bytes. It may contain embedded `NUL` characters and is not required to be
 * `NUL`-terminated.
 */
struct ProtobufCBinaryData {
	size_t	len;        /**< Number of bytes in the `data` field. */
	uint8_t	*data;      /**< Data bytes. */
};

/**
 * Structure for defining a virtual append-only buffer. Used by
 * protobuf_c_message_pack_to_buffer() to abstract the consumption of serialized
 * bytes.
 *
 * `ProtobufCBuffer` "subclasses" may be defined on the stack. For example, to
 * write to a `FILE` object:
 *
~~~{.c}
typedef struct {
        ProtobufCBuffer base;
        FILE *fp;
} BufferAppendToFile;

static void
my_buffer_file_append(ProtobufCBuffer *buffer,
                      size_t len,
                      const uint8_t *data)
{
        BufferAppendToFile *file_buf = (BufferAppendToFile *) buffer;
        fwrite(data, len, 1, file_buf->fp); // XXX: No error handling!
}
~~~
 *
 * To use this new type of ProtobufCBuffer, it could be called as follows:
 *
~~~{.c}
...
BufferAppendToFile tmp = {0};
tmp.base.append = my_buffer_file_append;
tmp.fp = fp;
protobuf_c_message_pack_to_buffer(&message, &tmp);
...
~~~
 */
struct ProtobufCBuffer {
	/** Append function. Consumes the `len` bytes stored at `data`. */
	void		(*append)(ProtobufCBuffer *buffer,
				  size_t len,
				  const uint8_t *data);
};

/**
 * Simple buffer "subclass" of `ProtobufCBuffer`.
 *
 * A `ProtobufCBufferSimple` object is declared on the stack and uses a
 * scratch buffer provided by the user for the initial allocation. It performs
 * exponential resizing, using dynamically allocated memory. A
 * `ProtobufCBufferSimple` object can be created and used as follows:
 *
~~~{.c}
uint8_t pad[128];
ProtobufCBufferSimple simple = PROTOBUF_C_BUFFER_SIMPLE_INIT(pad);
ProtobufCBuffer *buffer = (ProtobufCBuffer *) &simple;
~~~
 *
 * `buffer` can now be used with `protobuf_c_message_pack_to_buffer()`. Once a
 * message has been serialized to a `ProtobufCBufferSimple` object, the
 * serialized data bytes can be accessed from the `.data` field.
 *
 * To free the memory allocated by a `ProtobufCBufferSimple` object, if any,
 * call PROTOBUF_C_BUFFER_SIMPLE_CLEAR() on the object, for example:
 *
~~~{.c}
PROTOBUF_C_BUFFER_SIMPLE_CLEAR(&simple);
~~~
 *
 * \see PROTOBUF_C_BUFFER_SIMPLE_INIT
 * \see PROTOBUF_C_BUFFER_SIMPLE_CLEAR
 */
struct ProtobufCBufferSimple {
	/** "Base class". */
	ProtobufCBuffer		base;
	/** Number of bytes allocated in `data`. */
	size_t			alloced;
	/** Number of bytes currently stored in `data`. */
	size_t			len;
	/** Data bytes. */
	uint8_t			*data;
	/** Whether `data` must be freed. */
	protobuf_c_boolean	must_free_data;
	/** Allocator to use. May be NULL to indicate the system allocator. */
	ProtobufCAllocator	*allocator;
};

/**
 * Describes an enumeration as a whole, with all of its values.
 */
struct ProtobufCEnumDescriptor {
	/** Magic value checked to ensure that the API is used correctly. */
	uint32_t			magic;

/** The qualified name (e.g., "namespace.Type"). */
	const char			*name;
	/** The unqualified name as given in the .proto file (e.g., "Type"). */
	const char			*short_name;
	/** Identifier used in generated C code. */
	const char			*c_name;
	/** The dot-separated namespace. */
	const char			*package_name;

/** Number elements in `values`. */
	unsigned			n_values;
	/** Array of distinct values, sorted by numeric value. */
	const ProtobufCEnumValue	*values;

/** Number of elements in `values_by_name`. */
	unsigned			n_value_names;
	/** Array of named values, including aliases, sorted by name. */
	const ProtobufCEnumValueIndex	*values_by_name;

/** Number of elements in `value_ranges`. */
	unsigned			n_value_ranges;
	/** Value ranges, for faster lookups by numeric value. */
	const ProtobufCIntRange		*value_ranges;

/** Reserved for future use. */
	void				*reserved1;
	/** Reserved for future use. */
	void				*reserved2;
	/** Reserved for future use. */
	void				*reserved3;
	/** Reserved for future use. */
	void				*reserved4;
};

/**
 * Represents a single value of an enumeration.
 */
struct ProtobufCEnumValue {
	/** The string identifying this value in the .proto file. */
	const char	*name;

/** The string identifying this value in generated C code. */
	const char	*c_name;

/** The numeric value assigned in the .proto file. */
	int		value;
};

/**
 * Used by `ProtobufCEnumDescriptor` to look up enum values.
 */
struct ProtobufCEnumValueIndex {
	/** Name of the enum value. */
	const char      *name;
	/** Index into values[] array. */
	unsigned        index;
};

/**
 * Describes a single field in a message.
 */
struct ProtobufCFieldDescriptor {
	/** Name of the field as given in the .proto file. */
	const char		*name;

/** Tag value of the field as given in the .proto file. */
	uint32_t		id;

/** Whether the field is `REQUIRED`, `OPTIONAL`, or `REPEATED`. */
	ProtobufCLabel		label;

/** The type of the field. */
	ProtobufCType		type;

/**
	 * The offset in bytes of the message's C structure's quantifier field
	 * (the `has_MEMBER` field for optional members or the `n_MEMBER` field
	 * for repeated members or the case enum for oneofs).
	 */
	unsigned		quantifier_offset;

/**
	 * The offset in bytes into the message's C structure for the member
	 * itself.
	 */
	unsigned		offset;

/**
	 * A type-specific descriptor.
	 *
	 * If `type` is `PROTOBUF_C_TYPE_ENUM`, then `descriptor` points to the
	 * corresponding `ProtobufCEnumDescriptor`.
	 *
	 * If `type` is `PROTOBUF_C_TYPE_MESSAGE`, then `descriptor` points to
	 * the corresponding `ProtobufCMessageDescriptor`.
	 *
	 * Otherwise this field is NULL.
	 */
	const void		*descriptor; /* for MESSAGE and ENUM types */

/** The default value for this field, if defined. May be NULL. */
	const void		*default_value;

/**
	 * A flag word. Zero or more of the bits defined in the
	 * `ProtobufCFieldFlag` enum may be set.
	 */
	uint32_t		flags;

/** Reserved for future use. */
	unsigned		reserved_flags;
	/** Reserved for future use. */
	void			*reserved2;
	/** Reserved for future use. */
	void			*reserved3;
};

/**
 * Helper structure for optimizing int => index lookups in the case
 * where the keys are mostly consecutive values, as they presumably are for
 * enums and fields.
 *
 * The data structures requires that the values in the original array are
 * sorted.
 */
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.
	 */
};

/**
 * An instance of a message.
 *
 * `ProtobufCMessage` is a light-weight "base class" for all messages.
 *
 * In particular, `ProtobufCMessage` doesn't have any allocation policy
 * associated with it. That's because it's common to create `ProtobufCMessage`
 * objects on the stack. In fact, that's what we recommend for sending messages.
 * If the object is allocated from the stack, you can't really have a memory
 * leak.
 *
 * This means that calls to functions like protobuf_c_message_unpack() which
 * return a `ProtobufCMessage` must be paired with a call to a free function,
 * like protobuf_c_message_free_unpacked().
 */
struct ProtobufCMessage {
	/** The descriptor for this message type. */
	const ProtobufCMessageDescriptor	*descriptor;
	/** The number of elements in `unknown_fields`. */
	unsigned				n_unknown_fields;
	/** The fields that weren't recognized by the parser. */
	ProtobufCMessageUnknownField		*unknown_fields;
};

/**
 * Describes a message.
 */
struct ProtobufCMessageDescriptor {
	/** Magic value checked to ensure that the API is used correctly. */
	uint32_t			magic;

/**
	 * Size in bytes of the C structure representing an instance of this
	 * type of message.
	 */
	size_t				sizeof_message;

/** Number of elements in `fields`. */
	unsigned			n_fields;
	/** Field descriptors, sorted by tag number. */
	const ProtobufCFieldDescriptor	*fields;
	/** Used for looking up fields by name. */
	const unsigned			*fields_sorted_by_name;

/** Number of elements in `field_ranges`. */
	unsigned			n_field_ranges;
	/** Used for looking up fields by id. */
	const ProtobufCIntRange		*field_ranges;

/** Message initialisation function. */
	ProtobufCMessageInit		message_init;

/** Reserved for future use. */
	void				*reserved1;
	/** Reserved for future use. */
	void				*reserved2;
	/** Reserved for future use. */
	void				*reserved3;
};

/**
 * An unknown message field.
 */
struct ProtobufCMessageUnknownField {
	/** The tag number. */
	uint32_t		tag;
	/** The wire type of the field. */
	ProtobufCWireType	wire_type;
	/** Number of bytes in `data`. */
	size_t			len;
	/** Field data. */
	uint8_t			*data;
};

/**
 * Method descriptor.
 */
struct ProtobufCMethodDescriptor {
	/** Method name. */
	const char				*name;
	/** Input message descriptor. */
	const ProtobufCMessageDescriptor	*input;
	/** Output message descriptor. */
	const ProtobufCMessageDescriptor	*output;
};

/**
 * Service.
 */
struct ProtobufCService {
	/** Service descriptor. */
	const ProtobufCServiceDescriptor *descriptor;
	/** Function to invoke the service. */
	void (*invoke)(ProtobufCService *service,
		       unsigned method_index,
		       const ProtobufCMessage *input,
		       ProtobufCClosure closure,
		       void *closure_data);
	/** Function to destroy the service. */
	void (*destroy)(ProtobufCService *service);
};

/**
 * Service descriptor.
 */
struct ProtobufCServiceDescriptor {
	/** Magic value checked to ensure that the API is used correctly. */
	uint32_t			magic;

/** Service name. */
	const char			*name;
	/** Short version of service name. */
	const char			*short_name;
	/** C identifier for the service name. */
	const char			*c_name;
	/** Package name. */
	const char			*package;
	/** Number of elements in `methods`. */
	unsigned			n_methods;
	/** Method descriptors, in the order defined in the .proto file. */
	const ProtobufCMethodDescriptor	*methods;
	/** Sort index of methods. */
	const unsigned			*method_indices_by_name;
};

/**
 * Get the version of the protobuf-c library. Note that this is the version of
 * the library linked against, not the version of the headers compiled against.
 *
 * \return A string containing the version number of protobuf-c.
 */
PROTOBUF_C__API
const char *
protobuf_c_version(void);

/**
 * Get the version of the protobuf-c library. Note that this is the version of
 * the library linked against, not the version of the headers compiled against.
 *
 * \return A 32 bit unsigned integer containing the version number of
 *      protobuf-c, represented in base-10 as (MAJOR*1E6) + (MINOR*1E3) + PATCH.
 */
PROTOBUF_C__API
uint32_t
protobuf_c_version_number(void);

/**
 * The version of the protobuf-c headers, represented as a string using the same
 * format as protobuf_c_version().
 */
#define PROTOBUF_C_VERSION		"1.3.0"

/**
 * The version of the protobuf-c headers, represented as an integer using the
 * same format as protobuf_c_version_number().
 */
#define PROTOBUF_C_VERSION_NUMBER	1003000

/**
 * The minimum protoc-c version which works with the current version of the
 * protobuf-c headers.
 */
#define PROTOBUF_C_MIN_COMPILER_VERSION	1000000

/**
 * Look up a `ProtobufCEnumValue` from a `ProtobufCEnumDescriptor` by name.
 *
 * \param desc
 *      The `ProtobufCEnumDescriptor` object.
 * \param name
 *      The `name` field from the corresponding `ProtobufCEnumValue` object to
 *      match.
 * \return
 *      A `ProtobufCEnumValue` object.
 * \retval NULL
 *      If not found or if the optimize_for = CODE_SIZE option was set.
 */
PROTOBUF_C__API
const ProtobufCEnumValue *
protobuf_c_enum_descriptor_get_value_by_name(
	const ProtobufCEnumDescriptor *desc,
	const char *name);

/**
 * Look up a `ProtobufCEnumValue` from a `ProtobufCEnumDescriptor` by numeric
 * value.
 *
 * \param desc
 *      The `ProtobufCEnumDescriptor` object.
 * \param value
 *      The `value` field from the corresponding `ProtobufCEnumValue` object to
 *      match.
 *
 * \return
 *      A `ProtobufCEnumValue` object.
 * \retval NULL
 *      If not found.
 */
PROTOBUF_C__API
const ProtobufCEnumValue *
protobuf_c_enum_descriptor_get_value(
	const ProtobufCEnumDescriptor *desc,
	int value);

/**
 * Look up a `ProtobufCFieldDescriptor` from a `ProtobufCMessageDescriptor` by
 * the name of the field.
 *
 * \param desc
 *      The `ProtobufCMessageDescriptor` object.
 * \param name
 *      The name of the field.
 * \return
 *      A `ProtobufCFieldDescriptor` object.
 * \retval NULL
 *      If not found or if the optimize_for = CODE_SIZE option was set.
 */
PROTOBUF_C__API
const ProtobufCFieldDescriptor *
protobuf_c_message_descriptor_get_field_by_name(
	const ProtobufCMessageDescriptor *desc,
	const char *name);

/**
 * Look up a `ProtobufCFieldDescriptor` from a `ProtobufCMessageDescriptor` by
 * the tag value of the field.
 *
 * \param desc
 *      The `ProtobufCMessageDescriptor` object.
 * \param value
 *      The tag value of the field.
 * \return
 *      A `ProtobufCFieldDescriptor` object.
 * \retval NULL
 *      If not found.
 */
PROTOBUF_C__API
const ProtobufCFieldDescriptor *
protobuf_c_message_descriptor_get_field(
	const ProtobufCMessageDescriptor *desc,
	unsigned value);

/**
 * Determine the number of bytes required to store the serialised message.
 *
 * \param message
 *      The message object to serialise.
 * \return
 *      Number of bytes.
 */
PROTOBUF_C__API
size_t
protobuf_c_message_get_packed_size(const ProtobufCMessage *message);

/**
 * Serialise a message from its in-memory representation.
 *
 * This function stores the serialised bytes of the message in a pre-allocated
 * buffer.
 *
 * \param message
 *      The message object to serialise.
 * \param[out] out
 *      Buffer to store the bytes of the serialised message. This buffer must
 *      have enough space to store the packed message. Use
 *      protobuf_c_message_get_packed_size() to determine the number of bytes
 *      required.
 * \return
 *      Number of bytes stored in `out`.
 */
PROTOBUF_C__API
size_t
protobuf_c_message_pack(const ProtobufCMessage *message, uint8_t *out);

/**
 * Serialise a message from its in-memory representation to a virtual buffer.
 *
 * This function calls the `append` method of a `ProtobufCBuffer` object to
 * consume the bytes generated by the serialiser.
 *
 * \param message
 *      The message object to serialise.
 * \param buffer
 *      The virtual buffer object.
 * \return
 *      Number of bytes passed to the virtual buffer.
 */
PROTOBUF_C__API
size_t
protobuf_c_message_pack_to_buffer(
	const ProtobufCMessage *message,
	ProtobufCBuffer *buffer);

/**
 * Unpack a serialised message into an in-memory representation.
 *
 * \param descriptor
 *      The message descriptor.
 * \param allocator
 *      `ProtobufCAllocator` to use for memory allocation. May be NULL to
 *      specify the default allocator.
 * \param len
 *      Length in bytes of the serialised message.
 * \param data
 *      Pointer to the serialised message.
 * \return
 *      An unpacked message object.
 * \retval NULL
 *      If an error occurred during unpacking.
 */
PROTOBUF_C__API
ProtobufCMessage *
protobuf_c_message_unpack(
	const ProtobufCMessageDescriptor *descriptor,
	ProtobufCAllocator *allocator,
	size_t len,
	const uint8_t *data);

/**
 * Free an unpacked message object.
 *
 * This function should be used to deallocate the memory used by a call to
 * protobuf_c_message_unpack().
 *
 * \param message
 *      The message object to free. May be NULL.
 * \param allocator
 *      `ProtobufCAllocator` to use for memory deallocation. May be NULL to
 *      specify the default allocator.
 */
PROTOBUF_C__API
void
protobuf_c_message_free_unpacked(
	ProtobufCMessage *message,
	ProtobufCAllocator *allocator);

/**
 * Check the validity of a message object.
 *
 * Makes sure all required fields (`PROTOBUF_C_LABEL_REQUIRED`) are present.
 * Recursively checks nested messages.
 *
 * \retval TRUE
 *      Message is valid.
 * \retval FALSE
 *      Message is invalid.
 */
PROTOBUF_C__API
protobuf_c_boolean
protobuf_c_message_check(const ProtobufCMessage *);

/** Message initialiser. */
#define PROTOBUF_C_MESSAGE_INIT(descriptor) { descriptor, 0, NULL }

/**
 * Initialise a message object from a message descriptor.
 *
 * \param descriptor
 *      Message descriptor.
 * \param message
 *      Allocated block of memory of size `descriptor->sizeof_message`.
 */
PROTOBUF_C__API
void
protobuf_c_message_init(
	const ProtobufCMessageDescriptor *descriptor,
	void *message);

/**
 * Free a service.
 *
 * \param service
 *      The service object to free.
 */
PROTOBUF_C__API
void
protobuf_c_service_destroy(ProtobufCService *service);

/**
 * Look up a `ProtobufCMethodDescriptor` by name.
 *
 * \param desc
 *      Service descriptor.
 * \param name
 *      Name of the method.
 *
 * \return
 *      A `ProtobufCMethodDescriptor` object.
 * \retval NULL
 *      If not found or if the optimize_for = CODE_SIZE option was set.
 */
PROTOBUF_C__API
const ProtobufCMethodDescriptor *
protobuf_c_service_descriptor_get_method_by_name(
	const ProtobufCServiceDescriptor *desc,
	const char *name);

/**
 * Initialise a `ProtobufCBufferSimple` object.
 */
#define PROTOBUF_C_BUFFER_SIMPLE_INIT(array_of_bytes)                   \
{                                                                       \
	{ protobuf_c_buffer_simple_append },                            \
	sizeof(array_of_bytes),                                         \
	0,                                                              \
	(array_of_bytes),                                               \
	0,                                                              \
	NULL                                                            \
}

/**
 * Clear a `ProtobufCBufferSimple` object, freeing any allocated memory.
 */
#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)

/**
 * The `append` method for `ProtobufCBufferSimple`.
 *
 * \param buffer
 *      The buffer object to append to. Must actually be a
 *      `ProtobufCBufferSimple` object.
 * \param len
 *      Number of bytes in `data`.
 * \param data
 *      Data to append.
 */
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 */

Back