1 /* 2 * Copyright (c) 2008-2014, Dave Benson and the protobuf-c authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are 7 * met: 8 * 9 * * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above 13 * copyright notice, this list of conditions and the following disclaimer 14 * in the documentation and/or other materials provided with the 15 * distribution. 16 * 17 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 19 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 20 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 21 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 22 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 23 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 27 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28 */ 29 30 /*! \file 31 * \mainpage Introduction 32 * 33 * This is [protobuf-c], a C implementation of [Protocol Buffers]. 34 * 35 * This file defines the public API for the `libprotobuf-c` support library. 36 * This API includes interfaces that can be used directly by client code as well 37 * as the interfaces used by the code generated by the `protoc-c` compiler. 38 * 39 * The `libprotobuf-c` support library performs the actual serialization and 40 * deserialization of Protocol Buffers messages. It interacts with structures, 41 * definitions, and metadata generated by the `protoc-c` compiler from .proto 42 * files. 43 * 44 * \authors Dave Benson and the `protobuf-c` authors. 45 * 46 * \copyright 2008-2014. Licensed under the terms of the [BSD-2-Clause] license. 47 * 48 * [protobuf-c]: https://github.com/protobuf-c/protobuf-c 49 * [Protocol Buffers]: https://developers.google.com/protocol-buffers/ 50 * [BSD-2-Clause]: http://opensource.org/licenses/BSD-2-Clause 51 * 52 * \page gencode Generated Code 53 * 54 * For each enum, we generate a C enum. For each message, we generate a C 55 * structure which can be cast to a `ProtobufCMessage`. 56 * 57 * For each enum and message, we generate a descriptor object that allows us to 58 * implement a kind of reflection on the structures. 59 * 60 * First, some naming conventions: 61 * 62 * - The name of the type for enums and messages and services is camel case 63 * (meaning WordsAreCrammedTogether) except that double underscores are used 64 * to delimit scopes. For example, the following `.proto` file: 65 * 66 ~~~{.proto} 67 package foo.bar; 68 message BazBah { 69 optional int32 val = 1; 70 } 71 ~~~ 72 * 73 * would generate a C type `Foo__Bar__BazBah`. 74 * 75 * - Identifiers for functions and globals are all lowercase, with camel case 76 * words separated by single underscores. For example, one of the function 77 * prototypes generated by `protoc-c` for the above example: 78 * 79 ~~~{.c} 80 Foo__Bar__BazBah * 81 foo__bar__baz_bah__unpack 82 (ProtobufCAllocator *allocator, 83 size_t len, 84 const uint8_t *data); 85 ~~~ 86 * 87 * - Identifiers for enum values contain an uppercase prefix which embeds the 88 * package name and the enum type name. 89 * 90 * - A double underscore is used to separate further components of identifier 91 * names. 92 * 93 * For example, in the name of the unpack function above, the package name 94 * `foo.bar` has become `foo__bar`, the message name BazBah has become 95 * `baz_bah`, and the method name is `unpack`. These are all joined with double 96 * underscores to form the C identifier `foo__bar__baz_bah__unpack`. 97 * 98 * We also generate descriptor objects for messages and enums. These are 99 * declared in the `.pb-c.h` files: 100 * 101 ~~~{.c} 102 extern const ProtobufCMessageDescriptor foo__bar__baz_bah__descriptor; 103 ~~~ 104 * 105 * The message structures all begin with `ProtobufCMessageDescriptor *` which is 106 * sufficient to allow them to be cast to `ProtobufCMessage`. 107 * 108 * For each message defined in a `.proto` file, we generate a number of 109 * functions. Each function name contains a prefix based on the package name and 110 * message name in order to make it a unique C identifier. 111 * 112 * - `unpack()`. Unpacks data for a particular message format. Note that the 113 * `allocator` parameter is usually `NULL` to indicate that the system's 114 * `malloc()` and `free()` functions should be used for dynamically allocating 115 * memory. 116 * 117 ~~~{.c} 118 Foo__Bar__BazBah * 119 foo__bar__baz_bah__unpack 120 (ProtobufCAllocator *allocator, 121 size_t len, 122 const uint8_t *data); 123 ~~~ 124 * 125 * - `free_unpacked()`. Frees a message object obtained with the `unpack()` 126 * method. 127 * 128 ~~~{.c} 129 void foo__bar__baz_bah__free_unpacked 130 (Foo__Bar__BazBah *message, 131 ProtobufCAllocator *allocator); 132 ~~~ 133 * 134 * - `get_packed_size()`. Calculates the length in bytes of the serialized 135 * representation of the message object. 136 * 137 ~~~{.c} 138 size_t foo__bar__baz_bah__get_packed_size 139 (const Foo__Bar__BazBah *message); 140 ~~~ 141 * 142 * - `pack()`. Pack a message object into a preallocated buffer. Assumes that 143 * the buffer is large enough. (Use `get_packed_size()` first.) 144 * 145 ~~~{.c} 146 size_t foo__bar__baz_bah__pack 147 (const Foo__Bar__BazBah *message, 148 uint8_t *out); 149 ~~~ 150 * 151 * - `pack_to_buffer()`. Packs a message into a "virtual buffer". This is an 152 * object which defines an "append bytes" callback to consume data as it is 153 * serialized. 154 * 155 ~~~{.c} 156 size_t foo__bar__baz_bah__pack_to_buffer 157 (const Foo__Bar__BazBah *message, 158 ProtobufCBuffer *buffer); 159 ~~~ 160 * 161 * \page pack Packing and unpacking messages 162 * 163 * To pack a message, first compute the packed size of the message with 164 * protobuf_c_message_get_packed_size(), then allocate a buffer of at least 165 * that size, then call protobuf_c_message_pack(). 166 * 167 * Alternatively, a message can be serialized without calculating the final size 168 * first. Use the protobuf_c_message_pack_to_buffer() function and provide a 169 * ProtobufCBuffer object which implements an "append" method that consumes 170 * data. 171 * 172 * To unpack a message, call the protobuf_c_message_unpack() function. The 173 * result can be cast to an object of the type that matches the descriptor for 174 * the message. 175 * 176 * The result of unpacking a message should be freed with 177 * protobuf_c_message_free_unpacked(). 178 */ 179 180 #ifndef PROTOBUF_C_H 181 #define PROTOBUF_C_H 182 183 #include <assert.h> 184 #include <limits.h> 185 #include <stddef.h> 186 #include <stdint.h> 187 188 #ifdef __cplusplus 189 # define PROTOBUF_C__BEGIN_DECLS extern "C" { 190 # define PROTOBUF_C__END_DECLS } 191 #else 192 # define PROTOBUF_C__BEGIN_DECLS 193 # define PROTOBUF_C__END_DECLS 194 #endif 195 196 PROTOBUF_C__BEGIN_DECLS 197 198 #if defined(_WIN32) && defined(PROTOBUF_C_USE_SHARED_LIB) 199 # ifdef PROTOBUF_C_EXPORT 200 # define PROTOBUF_C__API __declspec(dllexport) 201 # else 202 # define PROTOBUF_C__API __declspec(dllimport) 203 # endif 204 #else 205 # define PROTOBUF_C__API 206 #endif 207 208 #if !defined(PROTOBUF_C__NO_DEPRECATED) 209 # if (__GNUC__ > 3) || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1) 210 # define PROTOBUF_C__DEPRECATED __attribute__((__deprecated__)) 211 # endif 212 #else 213 # define PROTOBUF_C__DEPRECATED 214 #endif 215 216 #ifndef PROTOBUF_C__FORCE_ENUM_TO_BE_INT_SIZE 217 #define PROTOBUF_C__FORCE_ENUM_TO_BE_INT_SIZE(enum_name) \ 218 , _##enum_name##_IS_INT_SIZE = INT_MAX 219 #endif 220 221 #define PROTOBUF_C__SERVICE_DESCRIPTOR_MAGIC 0x14159bc3 222 #define PROTOBUF_C__MESSAGE_DESCRIPTOR_MAGIC 0x28aaeef9 223 #define PROTOBUF_C__ENUM_DESCRIPTOR_MAGIC 0x114315af 224 225 /** 226 * \defgroup api Public API 227 * 228 * This is the public API for `libprotobuf-c`. These interfaces are stable and 229 * subject to Semantic Versioning guarantees. 230 * 231 * @{ 232 */ 233 234 /** 235 * Values for the `flags` word in `ProtobufCFieldDescriptor`. 236 */ 237 typedef enum { 238 /** Set if the field is repeated and marked with the `packed` option. */ 239 PROTOBUF_C_FIELD_FLAG_PACKED = (1 << 0), 240 241 /** Set if the field is marked with the `deprecated` option. */ 242 PROTOBUF_C_FIELD_FLAG_DEPRECATED = (1 << 1), 243 } ProtobufCFieldFlag; 244 245 /** 246 * Message field rules. 247 * 248 * \see [Defining A Message Type] in the Protocol Buffers documentation. 249 * 250 * [Defining A Message Type]: 251 * https://developers.google.com/protocol-buffers/docs/proto#simple 252 */ 253 typedef enum { 254 /** A well-formed message must have exactly one of this field. */ 255 PROTOBUF_C_LABEL_REQUIRED, 256 257 /** 258 * A well-formed message can have zero or one of this field (but not 259 * more than one). 260 */ 261 PROTOBUF_C_LABEL_OPTIONAL, 262 263 /** 264 * This field can be repeated any number of times (including zero) in a 265 * well-formed message. The order of the repeated values will be 266 * preserved. 267 */ 268 PROTOBUF_C_LABEL_REPEATED, 269 } ProtobufCLabel; 270 271 /** 272 * Field value types. 273 * 274 * \see [Scalar Value Types] in the Protocol Buffers documentation. 275 * 276 * [Scalar Value Types]: 277 * https://developers.google.com/protocol-buffers/docs/proto#scalar 278 */ 279 typedef enum { 280 PROTOBUF_C_TYPE_INT32, /**< int32 */ 281 PROTOBUF_C_TYPE_SINT32, /**< signed int32 */ 282 PROTOBUF_C_TYPE_SFIXED32, /**< signed int32 (4 bytes) */ 283 PROTOBUF_C_TYPE_INT64, /**< int64 */ 284 PROTOBUF_C_TYPE_SINT64, /**< signed int64 */ 285 PROTOBUF_C_TYPE_SFIXED64, /**< signed int64 (8 bytes) */ 286 PROTOBUF_C_TYPE_UINT32, /**< unsigned int32 */ 287 PROTOBUF_C_TYPE_FIXED32, /**< unsigned int32 (4 bytes) */ 288 PROTOBUF_C_TYPE_UINT64, /**< unsigned int64 */ 289 PROTOBUF_C_TYPE_FIXED64, /**< unsigned int64 (8 bytes) */ 290 PROTOBUF_C_TYPE_FLOAT, /**< float */ 291 PROTOBUF_C_TYPE_DOUBLE, /**< double */ 292 PROTOBUF_C_TYPE_BOOL, /**< boolean */ 293 PROTOBUF_C_TYPE_ENUM, /**< enumerated type */ 294 PROTOBUF_C_TYPE_STRING, /**< UTF-8 or ASCII string */ 295 PROTOBUF_C_TYPE_BYTES, /**< arbitrary byte sequence */ 296 PROTOBUF_C_TYPE_MESSAGE, /**< nested message */ 297 } ProtobufCType; 298 299 /** 300 * Field wire types. 301 * 302 * \see [Message Structure] in the Protocol Buffers documentation. 303 * 304 * [Message Structure]: 305 * https://developers.google.com/protocol-buffers/docs/encoding#structure 306 */ 307 typedef enum { 308 PROTOBUF_C_WIRE_TYPE_VARINT = 0, 309 PROTOBUF_C_WIRE_TYPE_64BIT = 1, 310 PROTOBUF_C_WIRE_TYPE_LENGTH_PREFIXED = 2, 311 /* "Start group" and "end group" wire types are unsupported. */ 312 PROTOBUF_C_WIRE_TYPE_32BIT = 5, 313 } ProtobufCWireType; 314 315 struct ProtobufCAllocator; 316 struct ProtobufCBinaryData; 317 struct ProtobufCBuffer; 318 struct ProtobufCBufferSimple; 319 struct ProtobufCEnumDescriptor; 320 struct ProtobufCEnumValue; 321 struct ProtobufCEnumValueIndex; 322 struct ProtobufCFieldDescriptor; 323 struct ProtobufCIntRange; 324 struct ProtobufCMessage; 325 struct ProtobufCMessageDescriptor; 326 struct ProtobufCMessageUnknownField; 327 struct ProtobufCMethodDescriptor; 328 struct ProtobufCService; 329 struct ProtobufCServiceDescriptor; 330 331 typedef struct ProtobufCAllocator ProtobufCAllocator; 332 typedef struct ProtobufCBinaryData ProtobufCBinaryData; 333 typedef struct ProtobufCBuffer ProtobufCBuffer; 334 typedef struct ProtobufCBufferSimple ProtobufCBufferSimple; 335 typedef struct ProtobufCEnumDescriptor ProtobufCEnumDescriptor; 336 typedef struct ProtobufCEnumValue ProtobufCEnumValue; 337 typedef struct ProtobufCEnumValueIndex ProtobufCEnumValueIndex; 338 typedef struct ProtobufCFieldDescriptor ProtobufCFieldDescriptor; 339 typedef struct ProtobufCIntRange ProtobufCIntRange; 340 typedef struct ProtobufCMessage ProtobufCMessage; 341 typedef struct ProtobufCMessageDescriptor ProtobufCMessageDescriptor; 342 typedef struct ProtobufCMessageUnknownField ProtobufCMessageUnknownField; 343 typedef struct ProtobufCMethodDescriptor ProtobufCMethodDescriptor; 344 typedef struct ProtobufCService ProtobufCService; 345 typedef struct ProtobufCServiceDescriptor ProtobufCServiceDescriptor; 346 347 /** Boolean type. */ 348 typedef int protobuf_c_boolean; 349 350 typedef void (*ProtobufCClosure)(const ProtobufCMessage *, void *closure_data); 351 typedef void (*ProtobufCMessageInit)(ProtobufCMessage *); 352 typedef void (*ProtobufCServiceDestroy)(ProtobufCService *); 353 354 /** 355 * Structure for defining a custom memory allocator. 356 */ 357 struct ProtobufCAllocator { 358 /** Function to allocate memory. */ 359 void *(*alloc)(void *allocator_data, size_t size); 360 361 /** Function to free memory. */ 362 void (*free)(void *allocator_data, void *pointer); 363 364 /** Opaque pointer passed to `alloc` and `free` functions. */ 365 void *allocator_data; 366 }; 367 368 /** 369 * Structure for the protobuf `bytes` scalar type. 370 * 371 * The data contained in a `ProtobufCBinaryData` is an arbitrary sequence of 372 * bytes. It may contain embedded `NUL` characters and is not required to be 373 * `NUL`-terminated. 374 */ 375 struct ProtobufCBinaryData { 376 size_t len; /**< Number of bytes in the `data` field. */ 377 uint8_t *data; /**< Data bytes. */ 378 }; 379 380 /** 381 * Structure for defining a virtual append-only buffer. Used by 382 * protobuf_c_message_pack_to_buffer() to abstract the consumption of serialized 383 * bytes. 384 * 385 * `ProtobufCBuffer` "subclasses" may be defined on the stack. For example, to 386 * write to a `FILE` object: 387 * 388 ~~~{.c} 389 typedef struct { 390 ProtobufCBuffer base; 391 FILE *fp; 392 } BufferAppendToFile; 393 394 static void 395 my_buffer_file_append(ProtobufCBuffer *buffer, 396 size_t len, 397 const uint8_t *data) 398 { 399 BufferAppendToFile *file_buf = (BufferAppendToFile *) buffer; 400 fwrite(data, len, 1, file_buf->fp); // XXX: No error handling! 401 } 402 ~~~ 403 * 404 * To use this new type of ProtobufCBuffer, it could be called as follows: 405 * 406 ~~~{.c} 407 ... 408 BufferAppendToFile tmp = {0}; 409 tmp.base.append = my_buffer_file_append; 410 tmp.fp = fp; 411 protobuf_c_message_pack_to_buffer(&message, &tmp); 412 ... 413 ~~~ 414 */ 415 struct ProtobufCBuffer { 416 /** Append function. Consumes the `len` bytes stored at `data`. */ 417 void (*append)(ProtobufCBuffer *buffer, 418 size_t len, 419 const uint8_t *data); 420 }; 421 422 /** 423 * Simple buffer "subclass" of `ProtobufCBuffer`. 424 * 425 * A `ProtobufCBufferSimple` object is declared on the stack and uses a 426 * scratch buffer provided by the user for the initial allocation. It performs 427 * exponential resizing, using dynamically allocated memory. A 428 * `ProtobufCBufferSimple` object can be created and used as follows: 429 * 430 ~~~{.c} 431 uint8_t pad[128]; 432 ProtobufCBufferSimple simple = PROTOBUF_C_BUFFER_SIMPLE_INIT(pad); 433 ProtobufCBuffer *buffer = (ProtobufCBuffer *) &simple; 434 ~~~ 435 * 436 * `buffer` can now be used with `protobuf_c_message_pack_to_buffer()`. Once a 437 * message has been serialized to a `ProtobufCBufferSimple` object, the 438 * serialized data bytes can be accessed from the `.data` field. 439 * 440 * To free the memory allocated by a `ProtobufCBufferSimple` object, if any, 441 * call PROTOBUF_C_BUFFER_SIMPLE_CLEAR() on the object, for example: 442 * 443 ~~~{.c} 444 PROTOBUF_C_BUFFER_SIMPLE_CLEAR(&simple); 445 ~~~ 446 * 447 * \see PROTOBUF_C_BUFFER_SIMPLE_INIT 448 * \see PROTOBUF_C_BUFFER_SIMPLE_CLEAR 449 */ 450 struct ProtobufCBufferSimple { 451 /** "Base class". */ 452 ProtobufCBuffer base; 453 /** Number of bytes allocated in `data`. */ 454 size_t alloced; 455 /** Number of bytes currently stored in `data`. */ 456 size_t len; 457 /** Data bytes. */ 458 uint8_t *data; 459 /** Whether `data` must be freed. */ 460 protobuf_c_boolean must_free_data; 461 /** Allocator to use. May be NULL to indicate the system allocator. */ 462 ProtobufCAllocator *allocator; 463 }; 464 465 /** 466 * Describes an enumeration as a whole, with all of its values. 467 */ 468 struct ProtobufCEnumDescriptor { 469 /** Magic value checked to ensure that the API is used correctly. */ 470 uint32_t magic; 471 472 /** The qualified name (e.g., "namespace.Type"). */ 473 const char *name; 474 /** The unqualified name as given in the .proto file (e.g., "Type"). */ 475 const char *short_name; 476 /** Identifier used in generated C code. */ 477 const char *c_name; 478 /** The dot-separated namespace. */ 479 const char *package_name; 480 481 /** Number elements in `values`. */ 482 unsigned n_values; 483 /** Array of distinct values, sorted by numeric value. */ 484 const ProtobufCEnumValue *values; 485 486 /** Number of elements in `values_by_name`. */ 487 unsigned n_value_names; 488 /** Array of named values, including aliases, sorted by name. */ 489 const ProtobufCEnumValueIndex *values_by_name; 490 491 /** Number of elements in `value_ranges`. */ 492 unsigned n_value_ranges; 493 /** Value ranges, for faster lookups by numeric value. */ 494 const ProtobufCIntRange *value_ranges; 495 496 /** Reserved for future use. */ 497 void *reserved1; 498 /** Reserved for future use. */ 499 void *reserved2; 500 /** Reserved for future use. */ 501 void *reserved3; 502 /** Reserved for future use. */ 503 void *reserved4; 504 }; 505 506 /** 507 * Represents a single value of an enumeration. 508 */ 509 struct ProtobufCEnumValue { 510 /** The string identifying this value in the .proto file. */ 511 const char *name; 512 513 /** The string identifying this value in generated C code. */ 514 const char *c_name; 515 516 /** The numeric value assigned in the .proto file. */ 517 int value; 518 }; 519 520 /** 521 * Used by `ProtobufCEnumDescriptor` to look up enum values. 522 */ 523 struct ProtobufCEnumValueIndex { 524 /** Name of the enum value. */ 525 const char *name; 526 /** Index into values[] array. */ 527 unsigned index; 528 }; 529 530 /** 531 * Describes a single field in a message. 532 */ 533 struct ProtobufCFieldDescriptor { 534 /** Name of the field as given in the .proto file. */ 535 const char *name; 536 537 /** Tag value of the field as given in the .proto file. */ 538 uint32_t id; 539 540 /** Whether the field is `REQUIRED`, `OPTIONAL`, or `REPEATED`. */ 541 ProtobufCLabel label; 542 543 /** The type of the field. */ 544 ProtobufCType type; 545 546 /** 547 * The offset in bytes of the message's C structure's quantifier field 548 * (the `has_MEMBER` field for optional members or the `n_MEMBER` field 549 * for repeated members. 550 */ 551 unsigned quantifier_offset; 552 553 /** 554 * The offset in bytes into the message's C structure for the member 555 * itself. 556 */ 557 unsigned offset; 558 559 /** 560 * A type-specific descriptor. 561 * 562 * If `type` is `PROTOBUF_C_TYPE_ENUM`, then `descriptor` points to the 563 * corresponding `ProtobufCEnumDescriptor`. 564 * 565 * If `type` is `PROTOBUF_C_TYPE_MESSAGE`, then `descriptor` points to 566 * the corresponding `ProtobufCMessageDescriptor`. 567 * 568 * Otherwise this field is NULL. 569 */ 570 const void *descriptor; /* for MESSAGE and ENUM types */ 571 572 /** The default value for this field, if defined. May be NULL. */ 573 const void *default_value; 574 575 /** 576 * A flag word. Zero or more of the bits defined in the 577 * `ProtobufCFieldFlag` enum may be set. 578 */ 579 uint32_t flags; 580 581 /** Reserved for future use. */ 582 unsigned reserved_flags; 583 /** Reserved for future use. */ 584 void *reserved2; 585 /** Reserved for future use. */ 586 void *reserved3; 587 }; 588 589 /** 590 * Helper structure for optimizing int => index lookups in the case 591 * where the keys are mostly consecutive values, as they presumably are for 592 * enums and fields. 593 * 594 * The data structures requires that the values in the original array are 595 * sorted. 596 */ 597 struct ProtobufCIntRange { 598 int start_value; 599 unsigned orig_index; 600 /* 601 * NOTE: the number of values in the range can be inferred by looking 602 * at the next element's orig_index. A dummy element is added to make 603 * this simple. 604 */ 605 }; 606 607 /** 608 * An instance of a message. 609 * 610 * `ProtobufCMessage` is a light-weight "base class" for all messages. 611 * 612 * In particular, `ProtobufCMessage` doesn't have any allocation policy 613 * associated with it. That's because it's common to create `ProtobufCMessage` 614 * objects on the stack. In fact, that's what we recommend for sending messages. 615 * If the object is allocated from the stack, you can't really have a memory 616 * leak. 617 * 618 * This means that calls to functions like protobuf_c_message_unpack() which 619 * return a `ProtobufCMessage` must be paired with a call to a free function, 620 * like protobuf_c_message_free_unpacked(). 621 */ 622 struct ProtobufCMessage { 623 /** The descriptor for this message type. */ 624 const ProtobufCMessageDescriptor *descriptor; 625 /** The number of elements in `unknown_fields`. */ 626 unsigned n_unknown_fields; 627 /** The fields that weren't recognized by the parser. */ 628 ProtobufCMessageUnknownField *unknown_fields; 629 }; 630 631 /** 632 * Describes a message. 633 */ 634 struct ProtobufCMessageDescriptor { 635 /** Magic value checked to ensure that the API is used correctly. */ 636 uint32_t magic; 637 638 /** The qualified name (e.g., "namespace.Type"). */ 639 const char *name; 640 /** The unqualified name as given in the .proto file (e.g., "Type"). */ 641 const char *short_name; 642 /** Identifier used in generated C code. */ 643 const char *c_name; 644 /** The dot-separated namespace. */ 645 const char *package_name; 646 647 /** 648 * Size in bytes of the C structure representing an instance of this 649 * type of message. 650 */ 651 size_t sizeof_message; 652 653 /** Number of elements in `fields`. */ 654 unsigned n_fields; 655 /** Field descriptors, sorted by tag number. */ 656 const ProtobufCFieldDescriptor *fields; 657 /** Used for looking up fields by name. */ 658 const unsigned *fields_sorted_by_name; 659 660 /** Number of elements in `field_ranges`. */ 661 unsigned n_field_ranges; 662 /** Used for looking up fields by id. */ 663 const ProtobufCIntRange *field_ranges; 664 665 /** Message initialisation function. */ 666 ProtobufCMessageInit message_init; 667 668 /** Reserved for future use. */ 669 void *reserved1; 670 /** Reserved for future use. */ 671 void *reserved2; 672 /** Reserved for future use. */ 673 void *reserved3; 674 }; 675 676 /** 677 * An unknown message field. 678 */ 679 struct ProtobufCMessageUnknownField { 680 /** The tag number. */ 681 uint32_t tag; 682 /** The wire type of the field. */ 683 ProtobufCWireType wire_type; 684 /** Number of bytes in `data`. */ 685 size_t len; 686 /** Field data. */ 687 uint8_t *data; 688 }; 689 690 /** 691 * Method descriptor. 692 */ 693 struct ProtobufCMethodDescriptor { 694 /** Method name. */ 695 const char *name; 696 /** Input message descriptor. */ 697 const ProtobufCMessageDescriptor *input; 698 /** Output message descriptor. */ 699 const ProtobufCMessageDescriptor *output; 700 }; 701 702 /** 703 * Service. 704 */ 705 struct ProtobufCService { 706 /** Service descriptor. */ 707 const ProtobufCServiceDescriptor *descriptor; 708 /** Function to invoke the service. */ 709 void (*invoke)(ProtobufCService *service, 710 unsigned method_index, 711 const ProtobufCMessage *input, 712 ProtobufCClosure closure, 713 void *closure_data); 714 /** Function to destroy the service. */ 715 void (*destroy)(ProtobufCService *service); 716 }; 717 718 /** 719 * Service descriptor. 720 */ 721 struct ProtobufCServiceDescriptor { 722 /** Magic value checked to ensure that the API is used correctly. */ 723 uint32_t magic; 724 725 /** Service name. */ 726 const char *name; 727 /** Short version of service name. */ 728 const char *short_name; 729 /** C identifier for the service name. */ 730 const char *c_name; 731 /** Package name. */ 732 const char *package; 733 /** Number of elements in `methods`. */ 734 unsigned n_methods; 735 /** Method descriptors, in the order defined in the .proto file. */ 736 const ProtobufCMethodDescriptor *methods; 737 /** Sort index of methods. */ 738 const unsigned *method_indices_by_name; 739 }; 740 741 /** 742 * Get the version of the protobuf-c library. Note that this is the version of 743 * the library linked against, not the version of the headers compiled against. 744 * 745 * \return A string containing the version number of protobuf-c. 746 */ 747 PROTOBUF_C__API 748 const char * 749 protobuf_c_version(void); 750 751 /** 752 * Get the version of the protobuf-c library. Note that this is the version of 753 * the library linked against, not the version of the headers compiled against. 754 * 755 * \return A 32 bit unsigned integer containing the version number of 756 * protobuf-c, represented in base-10 as (MAJOR*1E6) + (MINOR*1E3) + PATCH. 757 */ 758 PROTOBUF_C__API 759 uint32_t 760 protobuf_c_version_number(void); 761 762 /** 763 * The version of the protobuf-c headers, represented as a string using the same 764 * format as protobuf_c_version(). 765 */ 766 #define PROTOBUF_C_VERSION "1.0.1" 767 768 /** 769 * The version of the protobuf-c headers, represented as an integer using the 770 * same format as protobuf_c_version_number(). 771 */ 772 #define PROTOBUF_C_VERSION_NUMBER 1000001 773 774 /** 775 * The minimum protoc-c version which works with the current version of the 776 * protobuf-c headers. 777 */ 778 #define PROTOBUF_C_MIN_COMPILER_VERSION 1000000 779 780 /** 781 * Look up a `ProtobufCEnumValue` from a `ProtobufCEnumDescriptor` by name. 782 * 783 * \param desc 784 * The `ProtobufCEnumDescriptor` object. 785 * \param name 786 * The `name` field from the corresponding `ProtobufCEnumValue` object to 787 * match. 788 * \return 789 * A `ProtobufCEnumValue` object. 790 * \retval NULL 791 * If not found. 792 */ 793 PROTOBUF_C__API 794 const ProtobufCEnumValue * 795 protobuf_c_enum_descriptor_get_value_by_name( 796 const ProtobufCEnumDescriptor *desc, 797 const char *name); 798 799 /** 800 * Look up a `ProtobufCEnumValue` from a `ProtobufCEnumDescriptor` by numeric 801 * value. 802 * 803 * \param desc 804 * The `ProtobufCEnumDescriptor` object. 805 * \param value 806 * The `value` field from the corresponding `ProtobufCEnumValue` object to 807 * match. 808 * 809 * \return 810 * A `ProtobufCEnumValue` object. 811 * \retval NULL 812 * If not found. 813 */ 814 PROTOBUF_C__API 815 const ProtobufCEnumValue * 816 protobuf_c_enum_descriptor_get_value( 817 const ProtobufCEnumDescriptor *desc, 818 int value); 819 820 /** 821 * Look up a `ProtobufCFieldDescriptor` from a `ProtobufCMessageDescriptor` by 822 * the name of the field. 823 * 824 * \param desc 825 * The `ProtobufCMessageDescriptor` object. 826 * \param name 827 * The name of the field. 828 * \return 829 * A `ProtobufCFieldDescriptor` object. 830 * \retval NULL 831 * If not found. 832 */ 833 PROTOBUF_C__API 834 const ProtobufCFieldDescriptor * 835 protobuf_c_message_descriptor_get_field_by_name( 836 const ProtobufCMessageDescriptor *desc, 837 const char *name); 838 839 /** 840 * Look up a `ProtobufCFieldDescriptor` from a `ProtobufCMessageDescriptor` by 841 * the tag value of the field. 842 * 843 * \param desc 844 * The `ProtobufCMessageDescriptor` object. 845 * \param value 846 * The tag value of the field. 847 * \return 848 * A `ProtobufCFieldDescriptor` object. 849 * \retval NULL 850 * If not found. 851 */ 852 PROTOBUF_C__API 853 const ProtobufCFieldDescriptor * 854 protobuf_c_message_descriptor_get_field( 855 const ProtobufCMessageDescriptor *desc, 856 unsigned value); 857 858 /** 859 * Determine the number of bytes required to store the serialised message. 860 * 861 * \param message 862 * The message object to serialise. 863 * \return 864 * Number of bytes. 865 */ 866 PROTOBUF_C__API 867 size_t 868 protobuf_c_message_get_packed_size(const ProtobufCMessage *message); 869 870 /** 871 * Serialise a message from its in-memory representation. 872 * 873 * This function stores the serialised bytes of the message in a pre-allocated 874 * buffer. 875 * 876 * \param message 877 * The message object to serialise. 878 * \param[out] out 879 * Buffer to store the bytes of the serialised message. This buffer must 880 * have enough space to store the packed message. Use 881 * protobuf_c_message_get_packed_size() to determine the number of bytes 882 * required. 883 * \return 884 * Number of bytes stored in `out`. 885 */ 886 PROTOBUF_C__API 887 size_t 888 protobuf_c_message_pack(const ProtobufCMessage *message, uint8_t *out); 889 890 /** 891 * Serialise a message from its in-memory representation to a virtual buffer. 892 * 893 * This function calls the `append` method of a `ProtobufCBuffer` object to 894 * consume the bytes generated by the serialiser. 895 * 896 * \param message 897 * The message object to serialise. 898 * \param buffer 899 * The virtual buffer object. 900 * \return 901 * Number of bytes passed to the virtual buffer. 902 */ 903 PROTOBUF_C__API 904 size_t 905 protobuf_c_message_pack_to_buffer( 906 const ProtobufCMessage *message, 907 ProtobufCBuffer *buffer); 908 909 /** 910 * Unpack a serialised message into an in-memory representation. 911 * 912 * \param descriptor 913 * The message descriptor. 914 * \param allocator 915 * `ProtobufCAllocator` to use for memory allocation. May be NULL to 916 * specify the default allocator. 917 * \param len 918 * Length in bytes of the serialised message. 919 * \param data 920 * Pointer to the serialised message. 921 * \return 922 * An unpacked message object. 923 * \retval NULL 924 * If an error occurred during unpacking. 925 */ 926 PROTOBUF_C__API 927 ProtobufCMessage * 928 protobuf_c_message_unpack( 929 const ProtobufCMessageDescriptor *descriptor, 930 ProtobufCAllocator *allocator, 931 size_t len, 932 const uint8_t *data); 933 934 /** 935 * Free an unpacked message object. 936 * 937 * This function should be used to deallocate the memory used by a call to 938 * protobuf_c_message_unpack(). 939 * 940 * \param message 941 * The message object to free. 942 * \param allocator 943 * `ProtobufCAllocator` to use for memory deallocation. May be NULL to 944 * specify the default allocator. 945 */ 946 PROTOBUF_C__API 947 void 948 protobuf_c_message_free_unpacked( 949 ProtobufCMessage *message, 950 ProtobufCAllocator *allocator); 951 952 /** 953 * Check the validity of a message object. 954 * 955 * Makes sure all required fields (`PROTOBUF_C_LABEL_REQUIRED`) are present. 956 * Recursively checks nested messages. 957 * 958 * \retval TRUE 959 * Message is valid. 960 * \retval FALSE 961 * Message is invalid. 962 */ 963 PROTOBUF_C__API 964 protobuf_c_boolean 965 protobuf_c_message_check(const ProtobufCMessage *); 966 967 /** Message initialiser. */ 968 #define PROTOBUF_C_MESSAGE_INIT(descriptor) { descriptor, 0, NULL } 969 970 /** 971 * Initialise a message object from a message descriptor. 972 * 973 * \param descriptor 974 * Message descriptor. 975 * \param message 976 * Allocated block of memory of size `descriptor->sizeof_message`. 977 */ 978 PROTOBUF_C__API 979 void 980 protobuf_c_message_init( 981 const ProtobufCMessageDescriptor *descriptor, 982 void *message); 983 984 /** 985 * Free a service. 986 * 987 * \param service 988 * The service object to free. 989 */ 990 PROTOBUF_C__API 991 void 992 protobuf_c_service_destroy(ProtobufCService *service); 993 994 /** 995 * Look up a `ProtobufCMethodDescriptor` by name. 996 * 997 * \param desc 998 * Service descriptor. 999 * \param name 1000 * Name of the method. 1001 * 1002 * \return 1003 * A `ProtobufCMethodDescriptor` object. 1004 * \retval NULL 1005 * If not found. 1006 */ 1007 PROTOBUF_C__API 1008 const ProtobufCMethodDescriptor * 1009 protobuf_c_service_descriptor_get_method_by_name( 1010 const ProtobufCServiceDescriptor *desc, 1011 const char *name); 1012 1013 /** 1014 * Initialise a `ProtobufCBufferSimple` object. 1015 */ 1016 #define PROTOBUF_C_BUFFER_SIMPLE_INIT(array_of_bytes) \ 1017 { \ 1018 { protobuf_c_buffer_simple_append }, \ 1019 sizeof(array_of_bytes), \ 1020 0, \ 1021 (array_of_bytes), \ 1022 0, \ 1023 NULL \ 1024 } 1025 1026 /** 1027 * Clear a `ProtobufCBufferSimple` object, freeing any allocated memory. 1028 */ 1029 #define PROTOBUF_C_BUFFER_SIMPLE_CLEAR(simp_buf) \ 1030 do { \ 1031 if ((simp_buf)->must_free_data) { \ 1032 if ((simp_buf)->allocator != NULL) \ 1033 (simp_buf)->allocator->free( \ 1034 (simp_buf)->allocator, \ 1035 (simp_buf)->data); \ 1036 else \ 1037 free((simp_buf)->data); \ 1038 } \ 1039 } while (0) 1040 1041 /** 1042 * The `append` method for `ProtobufCBufferSimple`. 1043 * 1044 * \param buffer 1045 * The buffer object to append to. Must actually be a 1046 * `ProtobufCBufferSimple` object. 1047 * \param len 1048 * Number of bytes in `data`. 1049 * \param data 1050 * Data to append. 1051 */ 1052 PROTOBUF_C__API 1053 void 1054 protobuf_c_buffer_simple_append( 1055 ProtobufCBuffer *buffer, 1056 size_t len, 1057 const unsigned char *data); 1058 1059 PROTOBUF_C__API 1060 void 1061 protobuf_c_service_generated_init( 1062 ProtobufCService *service, 1063 const ProtobufCServiceDescriptor *descriptor, 1064 ProtobufCServiceDestroy destroy); 1065 1066 PROTOBUF_C__API 1067 void 1068 protobuf_c_service_invoke_internal( 1069 ProtobufCService *service, 1070 unsigned method_index, 1071 const ProtobufCMessage *input, 1072 ProtobufCClosure closure, 1073 void *closure_data); 1074 1075 /**@}*/ 1076 1077 PROTOBUF_C__END_DECLS 1078 1079 #endif /* PROTOBUF_C_H */ 1080