c_api.h 文件参考

Pure C API for the VLink communication middleware. 更多...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

c_api.h 的引用(Include)关系图:

浏览该文件的源代码.

类
struct	vlink_schema_info_t
	Bundled runtime schema metadata for C API node creation. 更多...
struct	vlink_publisher_handle_t
	Opaque handle for a Publisher node. 更多...
struct	vlink_subscriber_handle_t
	Opaque handle for a Subscriber node. 更多...
struct	vlink_server_handle_t
	Opaque handle for a Server node. 更多...
struct	vlink_client_handle_t
	Opaque handle for a Client node. 更多...
struct	vlink_setter_handle_t
	Opaque handle for a Setter node. 更多...
struct	vlink_getter_handle_t
	Opaque handle for a Getter node. 更多...

宏定义
#define	VLINK_C_API_EXPORT   __attribute__((visibility("default")))

类型定义
typedef void(*	vlink_connect_callback_t) (const bool is_connected, void *user_data)
	Callback invoked when the connection state of a Publisher or Client changes.
typedef void(*	vlink_msg_callback_t) (const uint8_t *data, const size_t size, void *user_data)
	Callback invoked when a Subscriber or Getter receives a message.
typedef void(*	vlink_req_callback_t) (const uint8_t *data, const size_t size, void *user_data)
	Callback invoked when a Server receives an RPC request.
typedef void(*	vlink_resp_callback_t) (const uint8_t *data, const size_t size, void *user_data)
	Callback invoked when a Client receives an RPC response.

枚举
enum	vlink_ret_t {   VLINK_RET_UNKNOWN_ERROR = -1 , VLINK_RET_NO_ERROR = 0 , VLINK_RET_UNEXPECTED_ERROR = 1 , VLINK_RET_INVALID_ERROR = 2 ,   VLINK_RET_MEMORY_ERROR = 3 , VLINK_RET_RUNTIME_ERROR = 4 , VLINK_RET_TRANSFER_ERROR = 5 }
	Return code for all VLink C API functions. 更多...
enum	vlink_schema_t {   VLINK_SCHEMA_UNKNOWN = 0 , VLINK_SCHEMA_RAW = 1 , VLINK_SCHEMA_ZEROCOPY = 2 , VLINK_SCHEMA_PROTOBUF = 3 ,   VLINK_SCHEMA_FLATBUFFERS = 4 }
	Coarse runtime schema family used for raw C API nodes. 更多...

函数
VLINK_C_API_EXPORT int	vlink_create_publisher (const char *url, const vlink_schema_info_t *schema_info, vlink_publisher_handle_t *handle)
	Publisher
VLINK_C_API_EXPORT int	vlink_destroy_publisher (vlink_publisher_handle_t *handle)
	Destroys a Publisher node and releases all associated resources.
VLINK_C_API_EXPORT int	vlink_has_subscribers (const vlink_publisher_handle_t handle)
	Checks whether at least one Subscriber has matched this Publisher.
VLINK_C_API_EXPORT int	vlink_wait_for_subscribers (const vlink_publisher_handle_t handle, const int timeout_ms)
	Blocks until at least one Subscriber matches or the timeout elapses.
VLINK_C_API_EXPORT int	vlink_detect_subscribers (const vlink_publisher_handle_t handle, const vlink_connect_callback_t connect_callback, void *user_data)
	Registers a callback fired whenever the Subscriber connection state changes.
VLINK_C_API_EXPORT int	vlink_publish (const vlink_publisher_handle_t handle, const uint8_t *data, const size_t size)
	Publishes a message to all matched Subscribers.
VLINK_C_API_EXPORT int	vlink_publish_by_force (const vlink_publisher_handle_t handle, const uint8_t *data, const size_t size)
	Publishes a message even when no Subscribers are currently matched.
VLINK_C_API_EXPORT int	vlink_create_subscriber (const char *url, const vlink_schema_info_t *schema_info, vlink_subscriber_handle_t *handle, const vlink_msg_callback_t msg_callback, void *user_data)
	Subscriber
VLINK_C_API_EXPORT int	vlink_destroy_subscriber (vlink_subscriber_handle_t *handle)
	Destroys a Subscriber node and releases all associated resources.
VLINK_C_API_EXPORT int	vlink_create_server (const char *url, const vlink_schema_info_t *schema_info, vlink_server_handle_t *handle, const vlink_req_callback_t req_callback, void *user_data)
	Server
VLINK_C_API_EXPORT int	vlink_destroy_server (vlink_server_handle_t *handle)
	Destroys a Server node and frees all internal resources including the internal mutex and any pending response buffer.
VLINK_C_API_EXPORT int	vlink_reply (vlink_server_handle_t *handle, const uint8_t *data, const size_t size)
	Provides the response data for the current in-progress RPC request.
VLINK_C_API_EXPORT int	vlink_create_client (const char *url, const vlink_schema_info_t *schema_info, vlink_client_handle_t *handle)
	Client
VLINK_C_API_EXPORT int	vlink_destroy_client (vlink_client_handle_t *handle)
	Destroys a Client node and releases all associated resources.
VLINK_C_API_EXPORT int	vlink_has_server (const vlink_client_handle_t handle)
	Checks whether the Client is connected to a Server.
VLINK_C_API_EXPORT int	vlink_wait_for_server (const vlink_client_handle_t handle, const int timeout_ms)
	Blocks until a Server is available or the timeout elapses.
VLINK_C_API_EXPORT int	vlink_detect_server (const vlink_client_handle_t handle, const vlink_connect_callback_t connect_callback, void *user_data)
	Registers a callback fired whenever the Server connection state changes.
VLINK_C_API_EXPORT int	vlink_invoke (const vlink_client_handle_t handle, const uint8_t *data, const size_t size, const vlink_resp_callback_t resp_callback, void *user_data)
	Sends an RPC request and registers a callback to receive the response.
VLINK_C_API_EXPORT int	vlink_create_setter (const char *url, const vlink_schema_info_t *schema_info, vlink_setter_handle_t *handle)
	Setter
VLINK_C_API_EXPORT int	vlink_destroy_setter (vlink_setter_handle_t *handle)
	Destroys a Setter node and releases all associated resources.
VLINK_C_API_EXPORT int	vlink_set (const vlink_setter_handle_t handle, const uint8_t *data, const size_t size)
	Publishes the latest field value.
VLINK_C_API_EXPORT int	vlink_create_getter (const char *url, const vlink_schema_info_t *schema_info, vlink_getter_handle_t *handle, const vlink_msg_callback_t msg_callback, void *user_data)
	Getter
VLINK_C_API_EXPORT int	vlink_destroy_getter (vlink_getter_handle_t *handle)
	Destroys a Getter node and releases all associated resources.
VLINK_C_API_EXPORT int	vlink_get (const vlink_getter_handle_t handle, uint8_t *data, size_t *size)
	Retrieves the latest field value into a caller-provided buffer.

详细描述

Pure C API for the VLink communication middleware.

Provides a stable, language-agnostic C binding over the VLink C++ core. Each of the three VLink communication models is exposed through a handle-based interface that wraps the corresponding C++ template class:

Model	C++ class	C handle types
Event	Publisher / Subscriber	vlink_publisher_handle_t / vlink_subscriber_handle_t
Method	Server / Client	vlink_server_handle_t / vlink_client_handle_t
Field	Setter / Getter	vlink_setter_handle_t / vlink_getter_handle_t

All handles are opaque structs that contain a native_handle pointer to the underlying C++ object and a reserved array used for internal state (e.g., the std::mutex and response buffer used by vlink_server_handle_t).

Return value conventions

Every function returns a vlink_ret_t integer:

Code	Meaning
VLINK_RET_NO_ERROR (0)	Success
VLINK_RET_UNEXPECTED_ERROR	Condition not met (e.g., no subscribers yet)
VLINK_RET_INVALID_ERROR	Null pointer or invalid handle
VLINK_RET_MEMORY_ERROR	Output buffer too small
VLINK_RET_RUNTIME_ERROR	Exception thrown during C++ construction
VLINK_RET_TRANSFER_ERROR	Publish / listen / invoke operation failed
VLINK_RET_UNKNOWN_ERROR (-1)	Unclassified error

Server reply protocol

The vlink_server_handle_t::reserved array is used to coordinate the synchronous request-reply flow:

static void on_request(const uint8_t* data, size_t size, void* user_data) {
    vlink_server_handle_t* handle = (vlink_server_handle_t*) user_data;
    vlink_reply(handle, resp_data, resp_size);
}
 
vlink_schema_info_t schema = {"demo.raw.Text", VLINK_SCHEMA_RAW};
vlink_create_server(url, &schema, &handle, on_request, &handle);

If vlink_reply() is not called, the request completes with an empty response payload. Calling vlink_reply() after the callback returns is undefined behaviour; the internal mutex lock will no longer be held.

Usage – publisher / subscriber

vlink_publisher_handle_t pub;
vlink_schema_info_t schema = {"demo.proto.PointCloud", VLINK_SCHEMA_PROTOBUF};
vlink_create_publisher("dds://my/topic", &schema, &pub);
vlink_wait_for_subscribers(pub, 1000);
vlink_publish(pub, data_buf, data_size);
vlink_destroy_publisher(&pub);
 
static void on_message(const uint8_t* data, size_t size, void* user_data) {
    (void) data;
    (void) size;
    (void) user_data;
}
 
vlink_subscriber_handle_t sub;
vlink_create_subscriber("dds://my/topic", &schema, &sub, on_message, user_data);

Usage – getter (polling)

vlink_getter_handle_t getter;
vlink_schema_info_t schema = {"demo.proto.State", VLINK_SCHEMA_PROTOBUF};
vlink_create_getter("dds://state/topic", &schema, &getter, NULL, NULL);
 
uint8_t buf[4096];
size_t  sz = sizeof(buf);
if (vlink_get(getter, buf, &sz) == VLINK_RET_NO_ERROR) {
    // buf[0..sz-1] contains the latest value
}

注解

• The C API uses vlink::Publisher<vlink::Bytes> and similar internally. Pass vlink_schema_info_t to configure ser + schema atomically.
• All create/destroy pairs must be balanced. Handles are not thread-safe across concurrent create/destroy calls.
• vlink_get() copies the latest value into the caller-supplied buffer. Returns VLINK_RET_MEMORY_ERROR if *size is smaller than the payload.
• vlink_publish_by_force() publishes even when no subscribers are matched, useful for transient-local-durability scenarios.

宏定义说明

VLINK_C_API_EXPORT

#define VLINK_C_API_EXPORT   __attribute__((visibility("default")))

类型定义说明

vlink_connect_callback_t

typedef void(* vlink_connect_callback_t) (const bool is_connected, void *user_data)

Callback invoked when the connection state of a Publisher or Client changes.

参数

is_connected	true when at least one peer has matched, false otherwise.
user_data	Opaque pointer supplied at registration time.

vlink_msg_callback_t

typedef void(* vlink_msg_callback_t) (const uint8_t *data, const size_t size, void *user_data)

Callback invoked when a Subscriber or Getter receives a message.

参数

data	Pointer to the received payload bytes.
size	Number of bytes in data.
user_data	Opaque pointer supplied at creation time.

vlink_req_callback_t

typedef void(* vlink_req_callback_t) (const uint8_t *data, const size_t size, void *user_data)

Callback invoked when a Server receives an RPC request.

Called synchronously on the Server's dispatch thread while an internal mutex is held. Call vlink_reply() from within this callback if you want to provide a non-empty response before returning. If it is not called, the request completes with an empty payload. Calling it after the callback returns is undefined behaviour.

参数

data	Pointer to the request payload bytes.
size	Number of bytes in data.
user_data	Opaque pointer supplied at creation time.

vlink_resp_callback_t

typedef void(* vlink_resp_callback_t) (const uint8_t *data, const size_t size, void *user_data)

Callback invoked when a Client receives an RPC response.

参数

data	Pointer to the response payload bytes. May be null if the server did not provide a response.
size	Number of bytes in data.
user_data	Opaque pointer supplied at invocation time.

枚举类型说明

vlink_ret_t

enum vlink_ret_t

Return code for all VLink C API functions.

A non-negative value indicates success or an expected condition. Negative values indicate hard errors. Check the return of every API call.

枚举值
VLINK_RET_UNKNOWN_ERROR	Unclassified or unexpected internal error.
VLINK_RET_NO_ERROR	Operation succeeded.
VLINK_RET_UNEXPECTED_ERROR	Condition not yet met (e.g., no subscribers).
VLINK_RET_INVALID_ERROR	Null pointer argument or invalid handle.
VLINK_RET_MEMORY_ERROR	Caller-provided buffer is too small.
VLINK_RET_RUNTIME_ERROR	C++ exception thrown during node construction.
VLINK_RET_TRANSFER_ERROR	Publish, listen, or invoke operation failed.

vlink_schema_t

enum vlink_schema_t

Coarse runtime schema family used for raw C API nodes.

Numerical values are intentionally kept in sync with the C++ vlink::SchemaType enum (see include/vlink/impl/types.h). This allows the C API implementation to cast between the two enums safely. Clients should always reference the symbolic names rather than the raw integer values so the mapping remains opaque at the source level.

枚举值
VLINK_SCHEMA_UNKNOWN	Schema family is not specified.
VLINK_SCHEMA_RAW	Opaque/raw payload.
VLINK_SCHEMA_ZEROCOPY	VLink zero-copy payload.
VLINK_SCHEMA_PROTOBUF	Protocol Buffers payload.
VLINK_SCHEMA_FLATBUFFERS	FlatBuffers payload.

函数说明

vlink_create_client()

VLINK_C_API_EXPORT int vlink_create_client	(	const char *	url,
		const vlink_schema_info_t *	schema_info,
		vlink_client_handle_t *	handle )

Client

Creates a Client node and initialises it on the given URL.

参数

url	VLink service URL. Must not be NULL.
schema_info	Optional bundled ser + schema metadata.
handle	Output handle. Must not be NULL.

返回

VLINK_RET_NO_ERROR on success, VLINK_RET_INVALID_ERROR if url or handle is NULL, if schema_info is only partially filled, if schema_info->schema is invalid, or VLINK_RET_RUNTIME_ERROR on construction exception.

vlink_create_getter()

VLINK_C_API_EXPORT int vlink_create_getter	(	const char *	url,
		const vlink_schema_info_t *	schema_info,
		vlink_getter_handle_t *	handle,
		const vlink_msg_callback_t	msg_callback,
		void *	user_data )

Getter

Creates a Getter node, initialises it, and optionally registers a change callback.

Allocates a vlink::Getter<vlink::Bytes>. If msg_callback is non-null, listen() is called and the callback is invoked on every value update. If msg_callback is NULL the Getter operates in polling mode – use vlink_get() to retrieve the latest value.

参数

url	VLink field URL. Must not be NULL.
schema_info	Optional bundled ser + schema metadata.
handle	Output handle. Must not be NULL.
msg_callback	Callback for push-mode updates, or NULL for poll mode.
user_data	Opaque pointer forwarded to msg_callback.

返回

VLINK_RET_NO_ERROR on success, VLINK_RET_INVALID_ERROR if url or handle is NULL, if schema_info is only partially filled, if schema_info->schema is invalid, or VLINK_RET_RUNTIME_ERROR on construction exception.

vlink_create_publisher()

VLINK_C_API_EXPORT int vlink_create_publisher	(	const char *	url,
		const vlink_schema_info_t *	schema_info,
		vlink_publisher_handle_t *	handle )

Publisher

Creates a Publisher node and initialises it on the given URL.

Allocates a vlink::Publisher<vlink::Bytes> on the heap and stores the pointer in handle. Pass schema_info to set ser + schema before the underlying node is initialised. Pass NULL to leave both unset.

参数

url	VLink topic URL (e.g., "dds://my/topic"). Must not be NULL.
schema_info	Optional bundled ser + schema metadata.
handle	Output handle to fill. Must not be NULL.

返回

VLINK_RET_NO_ERROR on success, VLINK_RET_INVALID_ERROR if url or handle is NULL, if schema_info is only partially filled, if schema_info->schema is invalid, or VLINK_RET_RUNTIME_ERROR if construction throws.

vlink_create_server()

VLINK_C_API_EXPORT int vlink_create_server	(	const char *	url,
		const vlink_schema_info_t *	schema_info,
		vlink_server_handle_t *	handle,
		const vlink_req_callback_t	req_callback,
		void *	user_data )

Server

Creates a Server node, initialises it, and registers the request callback.

Allocates a vlink::Server<vlink::Bytes, vlink::Bytes> and calls listen() with an internal handler that wraps req_callback.

The internal handler holds a std::mutex (stored in handle->reserved[0]) during each invocation. Call vlink_reply() from within req_callback to set a non-empty response before the callback returns.

参数

url	VLink service URL. Must not be NULL.
schema_info	Optional bundled ser + schema metadata.
handle	Output handle. Must not be NULL.
req_callback	Request handler. Must not be NULL. Call vlink_reply() before returning if a non-empty response is required.
user_data	Opaque pointer forwarded to req_callback.

返回

VLINK_RET_NO_ERROR on success, VLINK_RET_INVALID_ERROR if url or handle is NULL, if req_callback is NULL, if schema_info is only partially filled, if schema_info->schema is invalid, VLINK_RET_TRANSFER_ERROR if listen() fails, or VLINK_RET_RUNTIME_ERROR on construction exception.

vlink_create_setter()

VLINK_C_API_EXPORT int vlink_create_setter	(	const char *	url,
		const vlink_schema_info_t *	schema_info,
		vlink_setter_handle_t *	handle )

Setter

Creates a Setter node and initialises it on the given URL.

参数

url	VLink field URL. Must not be NULL.
schema_info	Optional bundled ser + schema metadata.
handle	Output handle. Must not be NULL.

返回

VLINK_RET_NO_ERROR on success, VLINK_RET_INVALID_ERROR if url or handle is NULL, if schema_info is only partially filled, if schema_info->schema is invalid, or VLINK_RET_RUNTIME_ERROR on construction exception.

vlink_create_subscriber()

VLINK_C_API_EXPORT int vlink_create_subscriber	(	const char *	url,
		const vlink_schema_info_t *	schema_info,
		vlink_subscriber_handle_t *	handle,
		const vlink_msg_callback_t	msg_callback,
		void *	user_data )

Subscriber

Creates a Subscriber node, initialises it, and registers the message callback.

Allocates a vlink::Subscriber<vlink::Bytes> and immediately calls listen() with the provided msg_callback. The callback is invoked on the Subscriber's internal receive thread.

参数

url	VLink topic URL. Must not be NULL.
schema_info	Optional bundled ser + schema metadata.
handle	Output handle. Must not be NULL.
msg_callback	Callback invoked on each received message. Must not be NULL.
user_data	Opaque pointer forwarded to msg_callback.

返回

VLINK_RET_NO_ERROR on success, VLINK_RET_INVALID_ERROR if any required argument is NULL, if schema_info is only partially filled, if schema_info->schema is invalid, VLINK_RET_TRANSFER_ERROR if listen() fails, or VLINK_RET_RUNTIME_ERROR on construction exception.

vlink_destroy_client()

VLINK_C_API_EXPORT int vlink_destroy_client

(

vlink_client_handle_t *

handle

)

Destroys a Client node and releases all associated resources.

参数

handle

Client handle to destroy. Must not be NULL.

返回

VLINK_RET_NO_ERROR on success, or VLINK_RET_INVALID_ERROR on bad handle.

vlink_destroy_getter()

VLINK_C_API_EXPORT int vlink_destroy_getter

(

vlink_getter_handle_t *

handle

)

Destroys a Getter node and releases all associated resources.

参数

handle

Getter handle to destroy. Must not be NULL.

返回

VLINK_RET_NO_ERROR on success, or VLINK_RET_INVALID_ERROR on bad handle.

vlink_destroy_publisher()

VLINK_C_API_EXPORT int vlink_destroy_publisher

(

vlink_publisher_handle_t *

handle

)

Destroys a Publisher node and releases all associated resources.

参数

handle

Publisher handle to destroy. Must not be NULL.

返回

VLINK_RET_NO_ERROR on success, VLINK_RET_INVALID_ERROR if handle or its native_handle is NULL.

vlink_destroy_server()

VLINK_C_API_EXPORT int vlink_destroy_server

(

vlink_server_handle_t *

handle

)

Destroys a Server node and frees all internal resources including the internal mutex and any pending response buffer.

参数

handle

Server handle to destroy. Must not be NULL.

返回

VLINK_RET_NO_ERROR on success, or VLINK_RET_INVALID_ERROR on bad handle.

vlink_destroy_setter()

VLINK_C_API_EXPORT int vlink_destroy_setter

(

vlink_setter_handle_t *

handle

)

Destroys a Setter node and releases all associated resources.

参数

handle

Setter handle to destroy. Must not be NULL.

返回

VLINK_RET_NO_ERROR on success, or VLINK_RET_INVALID_ERROR on bad handle.

vlink_destroy_subscriber()

VLINK_C_API_EXPORT int vlink_destroy_subscriber

(

vlink_subscriber_handle_t *

handle

)

Destroys a Subscriber node and releases all associated resources.

参数

handle

Subscriber handle to destroy. Must not be NULL.

返回

VLINK_RET_NO_ERROR on success, or VLINK_RET_INVALID_ERROR on bad handle.

vlink_detect_server()

VLINK_C_API_EXPORT int vlink_detect_server	(	const vlink_client_handle_t	handle,
		const vlink_connect_callback_t	connect_callback,
		void *	user_data )

Registers a callback fired whenever the Server connection state changes.

参数

handle	Client handle.
connect_callback	Callback to invoke on connection change.
user_data	Opaque pointer forwarded to connect_callback.

返回

VLINK_RET_NO_ERROR on success, or VLINK_RET_INVALID_ERROR on bad handle or NULL connect_callback.

vlink_detect_subscribers()

VLINK_C_API_EXPORT int vlink_detect_subscribers	(	const vlink_publisher_handle_t	handle,
		const vlink_connect_callback_t	connect_callback,
		void *	user_data )

Registers a callback fired whenever the Subscriber connection state changes.

The callback is invoked from the Publisher's internal event thread.

参数

handle	Publisher handle.
connect_callback	Callback to invoke on connection change.
user_data	Opaque pointer forwarded to connect_callback.

返回

VLINK_RET_NO_ERROR on success, or VLINK_RET_INVALID_ERROR on bad handle or NULL connect_callback.

vlink_get()

VLINK_C_API_EXPORT int vlink_get	(	const vlink_getter_handle_t	handle,
		uint8_t *	data,
		size_t *	size )

Retrieves the latest field value into a caller-provided buffer.

Copies the current cached value into data. On entry *size must hold the capacity of data; on success *size is updated to the actual byte count. When the buffer is too small returns VLINK_RET_MEMORY_ERROR and sets *size to the required byte count so the caller can allocate and retry. data is left unmodified in the error case.

参数

handle	Getter handle.
data	Output buffer. Must not be NULL.
size	In/out: buffer capacity on entry, actual size on exit (or required size when the buffer is too small). Must not be NULL.

返回

VLINK_RET_NO_ERROR on success, VLINK_RET_TRANSFER_ERROR if no value is available yet, VLINK_RET_MEMORY_ERROR if *size is too small (the required size is written back into *size), or VLINK_RET_INVALID_ERROR on bad arguments.

vlink_has_server()

VLINK_C_API_EXPORT int vlink_has_server

(

const vlink_client_handle_t

handle

)

Checks whether the Client is connected to a Server.

参数

handle

Client handle.

返回

VLINK_RET_NO_ERROR if connected, VLINK_RET_UNEXPECTED_ERROR if not yet connected, or VLINK_RET_INVALID_ERROR on bad handle.

vlink_has_subscribers()

VLINK_C_API_EXPORT int vlink_has_subscribers

(

const vlink_publisher_handle_t

handle

)

Checks whether at least one Subscriber has matched this Publisher.

参数

handle

Publisher handle.

返回

VLINK_RET_NO_ERROR if subscribers are present, VLINK_RET_UNEXPECTED_ERROR if none are matched yet, or VLINK_RET_INVALID_ERROR on bad handle.

vlink_invoke()

VLINK_C_API_EXPORT int vlink_invoke	(	const vlink_client_handle_t	handle,
		const uint8_t *	data,
		const size_t	size,
		const vlink_resp_callback_t	resp_callback,
		void *	user_data )

Sends an RPC request and registers a callback to receive the response.

Internally calls vlink::Client::invoke() using a shallow-copy Bytes wrapping data. The resp_callback is invoked asynchronously on the underlying vlink::Client callback context when the Server's response arrives. Pass NULL for resp_callback if the response is not needed.

参数

handle	Client handle.
data	Request payload. Must remain valid until the call returns.
size	Number of bytes in data.
resp_callback	Callback invoked with the response, or NULL.
user_data	Opaque pointer forwarded to resp_callback.

返回

VLINK_RET_NO_ERROR on success, VLINK_RET_TRANSFER_ERROR if the invoke failed, or VLINK_RET_INVALID_ERROR on bad handle.

vlink_publish()

VLINK_C_API_EXPORT int vlink_publish	(	const vlink_publisher_handle_t	handle,
		const uint8_t *	data,
		const size_t	size )

Publishes a message to all matched Subscribers.

Internally wraps data in a shallow-copy vlink::Bytes (zero-copy when the underlying transport supports it). Returns VLINK_RET_TRANSFER_ERROR if no subscribers are matched and the publisher does not allow forced delivery.

参数

handle	Publisher handle.
data	Payload to publish. Must remain valid until the call returns.
size	Number of bytes in data.

返回

VLINK_RET_NO_ERROR on success, VLINK_RET_TRANSFER_ERROR if publishing failed, or VLINK_RET_INVALID_ERROR on bad handle.

vlink_publish_by_force()

VLINK_C_API_EXPORT int vlink_publish_by_force	(	const vlink_publisher_handle_t	handle,
		const uint8_t *	data,
		const size_t	size )

Publishes a message even when no Subscribers are currently matched.

Identical to vlink_publish() but passes force=true to the underlying publisher, bypassing the subscriber-presence check. Useful for transient-local-durability or late-joining subscriber scenarios.

参数

handle	Publisher handle.
data	Payload to publish.
size	Number of bytes in data.

返回

VLINK_RET_NO_ERROR on success, VLINK_RET_TRANSFER_ERROR on failure, or VLINK_RET_INVALID_ERROR on bad handle.

vlink_reply()

VLINK_C_API_EXPORT int vlink_reply	(	vlink_server_handle_t *	handle,
		const uint8_t *	data,
		const size_t	size )

Provides the response data for the current in-progress RPC request.

Must be called from within the vlink_req_callback_t while the internal mutex lock is still held. Copies data into a heap buffer stored in handle->reserved[1] and sets handle->reserved[2] to the size. Sets handle->reserved[3] to NULL to signal that a reply is ready.

参数

handle	Server handle. Must not be NULL.
data	Response payload bytes.
size	Number of bytes in data.

返回

VLINK_RET_NO_ERROR on success, VLINK_RET_INVALID_ERROR on bad handle, or VLINK_RET_RUNTIME_ERROR if no pending request is in progress.

vlink_set()

VLINK_C_API_EXPORT int vlink_set	(	const vlink_setter_handle_t	handle,
		const uint8_t *	data,
		const size_t	size )

Publishes the latest field value.

The new value overwrites the previous value held by all matched Getters. Internally wraps data in a shallow-copy vlink::Bytes (zero-copy).

警告

The Setter caches the latest value internally so that late-joining Getters can sync. Because data is wrapped without copying, the buffer it points to must remain valid until either (a) the next vlink_set() call on the same handle (which overrides the cached value), or (b) vlink_destroy_setter() is called. Releasing data sooner causes a use-after-free when a late Getter tries to read the cache. Static storage (string literals, file-scope buffers) or a pinned allocation that lives for the Setter's lifetime is the typical pattern; if that is inconvenient, copy the value into a long-lived buffer before calling vlink_set().

参数

handle	Setter handle.
data	New field value bytes. Must remain valid until the next vlink_set() or vlink_destroy_setter().
size	Number of bytes in data.

返回

VLINK_RET_NO_ERROR on success, or VLINK_RET_INVALID_ERROR on bad handle.

vlink_wait_for_server()

VLINK_C_API_EXPORT int vlink_wait_for_server	(	const vlink_client_handle_t	handle,
		const int	timeout_ms )

Blocks until a Server is available or the timeout elapses.

参数

handle	Client handle.
timeout_ms	Maximum wait time in milliseconds.

返回

VLINK_RET_NO_ERROR if connected, VLINK_RET_UNEXPECTED_ERROR on timeout, or VLINK_RET_INVALID_ERROR on bad handle.

vlink_wait_for_subscribers()

VLINK_C_API_EXPORT int vlink_wait_for_subscribers	(	const vlink_publisher_handle_t	handle,
		const int	timeout_ms )

Blocks until at least one Subscriber matches or the timeout elapses.

参数

handle	Publisher handle.
timeout_ms	Maximum wait time in milliseconds.

返回

VLINK_RET_NO_ERROR if a subscriber matched, VLINK_RET_UNEXPECTED_ERROR if the timeout expired, or VLINK_RET_INVALID_ERROR on bad handle.