Public API

Detailed Description

This is the public API for libprotobuf-c.

These interfaces are stable and subject to Semantic Versioning guarantees.

Data Structures
struct	ProtobufCAllocator
	Structure for defining a custom memory allocator. More...
struct	ProtobufCBinaryData
	Structure for the protobuf bytes scalar type. More...
struct	ProtobufCBuffer
	Structure for defining a virtual append-only buffer. More...
struct	ProtobufCBufferSimple
	Simple buffer "subclass" of ProtobufCBuffer. More...
struct	ProtobufCEnumDescriptor
	Describes an enumeration as a whole, with all of its values. More...
struct	ProtobufCEnumValue
	Represents a single value of an enumeration. More...
struct	ProtobufCEnumValueIndex
	Used by ProtobufCEnumDescriptor to look up enum values. More...
struct	ProtobufCFieldDescriptor
	Describes a single field in a message. More...
struct	ProtobufCIntRange
	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. More...
struct	ProtobufCMessage
	An instance of a message. More...
struct	ProtobufCMessageDescriptor
	Describes a message. More...
struct	ProtobufCMessageUnknownField
	An unknown message field. More...
struct	ProtobufCMethodDescriptor
	Method descriptor. More...
struct	ProtobufCService
	Service. More...
struct	ProtobufCServiceDescriptor
	Service descriptor. More...

Macros
#define	PROTOBUF_C_VERSION   "1.5.1"
	The version of the protobuf-c headers, represented as a string using the same format as protobuf_c_version().
#define	PROTOBUF_C_VERSION_NUMBER   1005001
	The version of the protobuf-c headers, represented as an integer using the same format as protobuf_c_version_number().
#define	PROTOBUF_C_MIN_COMPILER_VERSION   1000000
	The minimum protoc-gen-c version which works with the current version of the protobuf-c headers.
#define	PROTOBUF_C_MESSAGE_INIT(descriptor)   { descriptor, 0, NULL }
	Message initialiser.
#define	PROTOBUF_C_BUFFER_SIMPLE_INIT(array_of_bytes)
	Initialise a ProtobufCBufferSimple object.
#define	PROTOBUF_C_BUFFER_SIMPLE_CLEAR(simp_buf)
	Clear a ProtobufCBufferSimple object, freeing any allocated memory.

Typedefs
typedef int	protobuf_c_boolean
	Boolean type.
typedef void(*	ProtobufCClosure) (const ProtobufCMessage *, void *closure_data)
typedef void(*	ProtobufCMessageInit) (ProtobufCMessage *)
typedef void(*	ProtobufCServiceDestroy) (ProtobufCService *)

Enumerations
enum	ProtobufCFieldFlag
	Values for the flags word in ProtobufCFieldDescriptor. More...
enum	ProtobufCLabel
	Message field rules. More...
enum	ProtobufCType
	Field value types. More...
enum	ProtobufCWireType
	Field wire types. More...

Functions
const char *	protobuf_c_version (void)
	Get the version of the protobuf-c library.
uint32_t	protobuf_c_version_number (void)
	Get the version of the protobuf-c library.
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.
const ProtobufCEnumValue *	protobuf_c_enum_descriptor_get_value (const ProtobufCEnumDescriptor *desc, int value)
	Look up a ProtobufCEnumValue from a ProtobufCEnumDescriptor by numeric value.
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.
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.
size_t	protobuf_c_message_get_packed_size (const ProtobufCMessage *message)
	Determine the number of bytes required to store the serialised message.
size_t	protobuf_c_message_pack (const ProtobufCMessage *message, uint8_t *out)
	Serialise a message from its in-memory representation.
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.
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.
void	protobuf_c_message_free_unpacked (ProtobufCMessage *message, ProtobufCAllocator *allocator)
	Free an unpacked message object.
protobuf_c_boolean	protobuf_c_message_check (const ProtobufCMessage *)
	Check the validity of a message object.
void	protobuf_c_message_init (const ProtobufCMessageDescriptor *descriptor, void *message)
	Initialise a message object from a message descriptor.
void	protobuf_c_service_destroy (ProtobufCService *service)
	Free a service.
const ProtobufCMethodDescriptor *	protobuf_c_service_descriptor_get_method_by_name (const ProtobufCServiceDescriptor *desc, const char *name)
	Look up a ProtobufCMethodDescriptor by name.
void	protobuf_c_buffer_simple_append (ProtobufCBuffer *buffer, size_t len, const unsigned char *data)
	The append method for ProtobufCBufferSimple.
void	protobuf_c_service_generated_init (ProtobufCService *service, const ProtobufCServiceDescriptor *descriptor, ProtobufCServiceDestroy destroy)
void	protobuf_c_service_invoke_internal (ProtobufCService *service, unsigned method_index, const ProtobufCMessage *input, ProtobufCClosure closure, void *closure_data)

Macro Definition Documentation

PROTOBUF_C_VERSION

#define PROTOBUF_C_VERSION   "1.5.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   1005001

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

PROTOBUF_C_MIN_COMPILER_VERSION

#define PROTOBUF_C_MIN_COMPILER_VERSION   1000000

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

PROTOBUF_C_MESSAGE_INIT

#define PROTOBUF_C_MESSAGE_INIT

(

descriptor

)

{ descriptor, 0, NULL }

Message initialiser.

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

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.
PROTOBUF_C_LABEL_NONE	This field has no label. This is valid only in proto3 and is equivalent to OPTIONAL but no "has" quantifier will be consulted.

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_version()

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()

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.

protobuf_c_enum_descriptor_get_value_by_name()

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 or if the optimize_for = CODE_SIZE option was set.

protobuf_c_enum_descriptor_get_value()

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_message_descriptor_get_field_by_name()

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 or if the optimize_for = CODE_SIZE option was set.

protobuf_c_message_descriptor_get_field()

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_get_packed_size()

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_pack()

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()

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()

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_message_free_unpacked()

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. May be NULL.
allocator	ProtobufCAllocator to use for memory deallocation. May be NULL to specify the default allocator.

protobuf_c_message_check()

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_init()

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_service_destroy()

void protobuf_c_service_destroy

(

ProtobufCService *

service

)

Free a service.

Parameters

service

The service object to free.

protobuf_c_service_descriptor_get_method_by_name()

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 or if the optimize_for = CODE_SIZE option was set.

protobuf_c_buffer_simple_append()

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.