Public API

Classes
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

Macros
#define	PROTOBUF_C_VERSION   "1.1.1"
#define	PROTOBUF_C_VERSION_NUMBER   1001001
#define	PROTOBUF_C_MIN_COMPILER_VERSION   1000000
#define	PROTOBUF_C_MESSAGE_INIT(descriptor)   { descriptor, 0, NULL }
#define	PROTOBUF_C_BUFFER_SIMPLE_INIT(array_of_bytes)
#define	PROTOBUF_C_BUFFER_SIMPLE_CLEAR(simp_buf)

Typedefs
typedef struct ProtobufCAllocator	ProtobufCAllocator
typedef struct ProtobufCBinaryData	ProtobufCBinaryData
typedef struct ProtobufCBuffer	ProtobufCBuffer
typedef struct ProtobufCBufferSimple	ProtobufCBufferSimple
typedef struct ProtobufCEnumDescriptor	ProtobufCEnumDescriptor
typedef struct ProtobufCEnumValue	ProtobufCEnumValue
typedef struct ProtobufCEnumValueIndex	ProtobufCEnumValueIndex
typedef struct ProtobufCFieldDescriptor	ProtobufCFieldDescriptor
typedef struct ProtobufCIntRange	ProtobufCIntRange
typedef struct ProtobufCMessage	ProtobufCMessage
typedef struct ProtobufCMessageDescriptor	ProtobufCMessageDescriptor
typedef struct ProtobufCMessageUnknownField	ProtobufCMessageUnknownField
typedef struct ProtobufCMethodDescriptor	ProtobufCMethodDescriptor
typedef struct ProtobufCService	ProtobufCService
typedef struct ProtobufCServiceDescriptor	ProtobufCServiceDescriptor
typedef int	protobuf_c_boolean
typedef void(*	ProtobufCClosure) (const ProtobufCMessage *, void *closure_data)
typedef void(*	ProtobufCMessageInit) (ProtobufCMessage *)
typedef void(*	ProtobufCServiceDestroy) (ProtobufCService *)

Enumerations
enum	ProtobufCFieldFlag { PROTOBUF_C_FIELD_FLAG_PACKED = (1 << 0), PROTOBUF_C_FIELD_FLAG_DEPRECATED = (1 << 1), PROTOBUF_C_FIELD_FLAG_ONEOF = (1 << 2) }
enum	ProtobufCLabel { PROTOBUF_C_LABEL_REQUIRED, PROTOBUF_C_LABEL_OPTIONAL, PROTOBUF_C_LABEL_REPEATED }
enum	ProtobufCType {   PROTOBUF_C_TYPE_INT32, PROTOBUF_C_TYPE_SINT32, PROTOBUF_C_TYPE_SFIXED32, PROTOBUF_C_TYPE_INT64,   PROTOBUF_C_TYPE_SINT64, PROTOBUF_C_TYPE_SFIXED64, PROTOBUF_C_TYPE_UINT32, PROTOBUF_C_TYPE_FIXED32,   PROTOBUF_C_TYPE_UINT64, PROTOBUF_C_TYPE_FIXED64, PROTOBUF_C_TYPE_FLOAT, PROTOBUF_C_TYPE_DOUBLE,   PROTOBUF_C_TYPE_BOOL, PROTOBUF_C_TYPE_ENUM, PROTOBUF_C_TYPE_STRING, PROTOBUF_C_TYPE_BYTES,   PROTOBUF_C_TYPE_MESSAGE }
enum	ProtobufCWireType { PROTOBUF_C_WIRE_TYPE_VARINT = 0, PROTOBUF_C_WIRE_TYPE_64BIT = 1, PROTOBUF_C_WIRE_TYPE_LENGTH_PREFIXED = 2, PROTOBUF_C_WIRE_TYPE_32BIT = 5 }

Functions
PROTOBUF_C__API const char *	protobuf_c_version (void)
PROTOBUF_C__API uint32_t	protobuf_c_version_number (void)
PROTOBUF_C__API const ProtobufCEnumValue *	protobuf_c_enum_descriptor_get_value_by_name (const ProtobufCEnumDescriptor *desc, const char *name)
PROTOBUF_C__API const ProtobufCEnumValue *	protobuf_c_enum_descriptor_get_value (const ProtobufCEnumDescriptor *desc, int value)
PROTOBUF_C__API const ProtobufCFieldDescriptor *	protobuf_c_message_descriptor_get_field_by_name (const ProtobufCMessageDescriptor *desc, const char *name)
PROTOBUF_C__API const ProtobufCFieldDescriptor *	protobuf_c_message_descriptor_get_field (const ProtobufCMessageDescriptor *desc, unsigned value)
PROTOBUF_C__API size_t	protobuf_c_message_get_packed_size (const ProtobufCMessage *message)
PROTOBUF_C__API size_t	protobuf_c_message_pack (const ProtobufCMessage *message, uint8_t *out)
PROTOBUF_C__API size_t	protobuf_c_message_pack_to_buffer (const ProtobufCMessage *message, ProtobufCBuffer *buffer)
PROTOBUF_C__API ProtobufCMessage *	protobuf_c_message_unpack (const ProtobufCMessageDescriptor *descriptor, ProtobufCAllocator *allocator, size_t len, const uint8_t *data)
PROTOBUF_C__API void	protobuf_c_message_free_unpacked (ProtobufCMessage *message, ProtobufCAllocator *allocator)
PROTOBUF_C__API protobuf_c_boolean	protobuf_c_message_check (const ProtobufCMessage *)
PROTOBUF_C__API void	protobuf_c_message_init (const ProtobufCMessageDescriptor *descriptor, void *message)
PROTOBUF_C__API void	protobuf_c_service_destroy (ProtobufCService *service)
PROTOBUF_C__API const ProtobufCMethodDescriptor *	protobuf_c_service_descriptor_get_method_by_name (const ProtobufCServiceDescriptor *desc, const char *name)
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)

Detailed Description

This is the public API for libprotobuf-c. These interfaces are stable and subject to Semantic Versioning guarantees.

Macro Definition Documentation

PROTOBUF_C_BUFFER_SIMPLE_CLEAR

#define PROTOBUF_C_BUFFER_SIMPLE_CLEAR

(

simp_buf

)

Value:

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)

Clear a ProtobufCBufferSimple object, freeing any allocated memory.

PROTOBUF_C_BUFFER_SIMPLE_INIT

#define PROTOBUF_C_BUFFER_SIMPLE_INIT

(

array_of_bytes

)

Value:

{                                                                       \
    { protobuf_c_buffer_simple_append },                            \
    sizeof(array_of_bytes),                                         \
    0,                                                              \
    (array_of_bytes),                                               \
    0,                                                              \
    NULL                                                            \
}

Initialise a ProtobufCBufferSimple object.

PROTOBUF_C_MESSAGE_INIT

#define PROTOBUF_C_MESSAGE_INIT

(

descriptor

)

{ descriptor, 0, NULL }

Message initialiser.

PROTOBUF_C_MIN_COMPILER_VERSION

#define PROTOBUF_C_MIN_COMPILER_VERSION   1000000

The minimum protoc-c version which works with the current version of the protobuf-c headers.

PROTOBUF_C_VERSION

#define PROTOBUF_C_VERSION   "1.1.1"

The version of the protobuf-c headers, represented as a string using the same format as protobuf_c_version().

PROTOBUF_C_VERSION_NUMBER

#define PROTOBUF_C_VERSION_NUMBER   1001001

The version of the protobuf-c headers, represented as an integer using the same format as protobuf_c_version_number().

Typedef Documentation

protobuf_c_boolean

typedef int protobuf_c_boolean

Boolean type.

Enumeration Type Documentation

ProtobufCFieldFlag

enum ProtobufCFieldFlag

Values for the flags word in ProtobufCFieldDescriptor.

Enumerator
PROTOBUF_C_FIELD_FLAG_PACKED	Set if the field is repeated and marked with the packed option.
PROTOBUF_C_FIELD_FLAG_DEPRECATED	Set if the field is marked with the deprecated option.
PROTOBUF_C_FIELD_FLAG_ONEOF	Set if the field is a member of a oneof (union).

ProtobufCLabel

enum ProtobufCLabel

Message field rules.

See also

Defining A Message Type in the Protocol Buffers documentation.

Enumerator
PROTOBUF_C_LABEL_REQUIRED	A well-formed message must have exactly one of this field.
PROTOBUF_C_LABEL_OPTIONAL	A well-formed message can have zero or one of this field (but not more than one).
PROTOBUF_C_LABEL_REPEATED	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.

ProtobufCType

enum ProtobufCType

Field value types.

See also

Scalar Value Types in the Protocol Buffers documentation.

Enumerator
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

ProtobufCWireType

enum ProtobufCWireType

Field wire types.

See also

Message Structure in the Protocol Buffers documentation.

Function Documentation

protobuf_c_buffer_simple_append()

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

The append method for ProtobufCBufferSimple.

Parameters

buffer	The buffer object to append to. Must actually be a ProtobufCBufferSimple object.
len	Number of bytes in data.
data	Data to append.

protobuf_c_enum_descriptor_get_value()

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

Look up a ProtobufCEnumValue from a ProtobufCEnumDescriptor by numeric value.

Parameters

desc	The ProtobufCEnumDescriptor object.
value	The value field from the corresponding ProtobufCEnumValue object to match.

Returns

A ProtobufCEnumValue object.

Return values

NULL	If not found.

protobuf_c_enum_descriptor_get_value_by_name()

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 name.

Parameters

desc	The ProtobufCEnumDescriptor object.
name	The name field from the corresponding ProtobufCEnumValue object to match.

Returns

A ProtobufCEnumValue object.

Return values

NULL	If not found.

protobuf_c_message_check()

PROTOBUF_C__API protobuf_c_boolean protobuf_c_message_check

(

const ProtobufCMessage *

)

Check the validity of a message object.

Makes sure all required fields (PROTOBUF_C_LABEL_REQUIRED) are present. Recursively checks nested messages.

Return values

TRUE	Message is valid.
FALSE	Message is invalid.

protobuf_c_message_descriptor_get_field()

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

Look up a ProtobufCFieldDescriptor from a ProtobufCMessageDescriptor by the tag value of the field.

Parameters

desc	The ProtobufCMessageDescriptor object.
value	The tag value of the field.

Returns

A ProtobufCFieldDescriptor object.

Return values

NULL	If not found.

protobuf_c_message_descriptor_get_field_by_name()

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 name of the field.

Parameters

desc	The ProtobufCMessageDescriptor object.
name	The name of the field.

Returns

A ProtobufCFieldDescriptor object.

Return values

NULL	If not found.

protobuf_c_message_free_unpacked()

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

Free an unpacked message object.

This function should be used to deallocate the memory used by a call to protobuf_c_message_unpack().

Parameters

message	The message object to free.
allocator	ProtobufCAllocator to use for memory deallocation. May be NULL to specify the default allocator.

protobuf_c_message_get_packed_size()

PROTOBUF_C__API size_t protobuf_c_message_get_packed_size

(

const ProtobufCMessage *

message

)

Determine the number of bytes required to store the serialised message.

Parameters

message

The message object to serialise.

Returns

Number of bytes.

protobuf_c_message_init()

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

Initialise a message object from a message descriptor.

Parameters

descriptor	Message descriptor.
message	Allocated block of memory of size descriptor->sizeof_message.

protobuf_c_message_pack()

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

Serialise a message from its in-memory representation.

This function stores the serialised bytes of the message in a pre-allocated buffer.

Parameters

	message	The message object to serialise.
[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.

Returns

Number of bytes stored in out.

protobuf_c_message_pack_to_buffer()

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

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.

Parameters

message	The message object to serialise.
buffer	The virtual buffer object.

Returns

Number of bytes passed to the virtual buffer.

protobuf_c_message_unpack()

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

Unpack a serialised message into an in-memory representation.

Parameters

descriptor	The message descriptor.
allocator	ProtobufCAllocator to use for memory allocation. May be NULL to specify the default allocator.
len	Length in bytes of the serialised message.
data	Pointer to the serialised message.

Returns

An unpacked message object.

Return values

NULL	If an error occurred during unpacking.

protobuf_c_service_descriptor_get_method_by_name()

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

Look up a ProtobufCMethodDescriptor by name.

Parameters

desc	Service descriptor.
name	Name of the method.

Returns

A ProtobufCMethodDescriptor object.

Return values

NULL	If not found.

protobuf_c_service_destroy()

PROTOBUF_C__API void protobuf_c_service_destroy

(

ProtobufCService *

service

)

Free a service.

Parameters

service

The service object to free.

protobuf_c_version()

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.

Returns

A string containing the version number of protobuf-c.

protobuf_c_version_number()

PROTOBUF_C__API uint32_t protobuf_c_version_number

(

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.

Returns

A 32 bit unsigned integer containing the version number of protobuf-c, represented in base-10 as (MAJOR*1E6) + (MINOR*1E3) + PATCH.