c_api.h File Reference

Pure C binding over the VLink communication middleware. More...

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

Include dependency graph for c_api.h:

Go to the source code of this file.

Classes
struct	vlink_schema_info_t
	Bundled runtime schema metadata supplied at node creation. More...
struct	vlink_publisher_handle_t
	Opaque handle for a Publisher node. More...
struct	vlink_subscriber_handle_t
	Opaque handle for a Subscriber node. More...
struct	vlink_server_handle_t
	Opaque handle for a Server node. More...
struct	vlink_client_handle_t
	Opaque handle for a Client node. More...
struct	vlink_setter_handle_t
	Opaque handle for a Setter node. More...
struct	vlink_getter_handle_t
	Opaque handle for a Getter node. More...
struct	vlink_security_advanced_config_t
	Low-frequency security options: AAD, replay protection, and signing keys. More...
struct	vlink_security_config_s
	Configuration aggregate for vlink_security_create() and the vlink_create_secure_*() entry points. More...
struct	vlink_ssl_options_t
	Transport-layer TLS configuration aggregate. More...

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

Typedefs
typedef struct vlink_security_config_s	vlink_security_config_t
Callback typedefs
typedef void(*	vlink_connect_callback_t) (const bool is_connected, void *user_data)
	Callback fired when the connection state of a Publisher or Client changes. More...
typedef void(*	vlink_msg_callback_t) (const uint8_t *data, const size_t size, void *user_data)
	Callback fired when a Subscriber or Getter receives a message. More...
typedef void(*	vlink_req_callback_t) (const uint8_t *data, const size_t size, void *user_data)
	Callback fired when a Server receives an RPC request. More...
typedef void(*	vlink_resp_callback_t) (const uint8_t *data, const size_t size, void *user_data)
	Callback fired when a Client receives an RPC response. More...

Enumerations
Common types and return codes
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 VLink C API functions that report vlink_ret_t. More...
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. More...

Functions
Event model – Publisher
Publisher
VLINK_C_API_EXPORT int	vlink_create_publisher (const char *url, const vlink_schema_info_t *schema_info, vlink_publisher_handle_t *handle)
	Creates a Publisher node and initialises it on the given URL. More...
VLINK_C_API_EXPORT int	vlink_destroy_publisher (vlink_publisher_handle_t *handle)
	Destroys a Publisher node and releases every associated resource. More...
VLINK_C_API_EXPORT int	vlink_has_subscribers (const vlink_publisher_handle_t handle)
	Checks whether at least one Subscriber has matched this Publisher. More...
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 timeout_ms expires. More...
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. More...
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 every matched Subscriber. More...
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 matched. More...
Event model – Subscriber
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)
	Creates a Subscriber node, initialises it, and registers the message callback. More...
VLINK_C_API_EXPORT int	vlink_create_secure_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, const vlink_security_config_t *security_cfg)
	Atomically creates a Subscriber, installs Security, and calls listen(). More...
VLINK_C_API_EXPORT int	vlink_destroy_subscriber (vlink_subscriber_handle_t *handle)
	Destroys a Subscriber node and releases every associated resource. More...
Method model – Server
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)
	Creates a Server node, initialises it, and registers the request callback. More...
VLINK_C_API_EXPORT int	vlink_create_secure_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, const vlink_security_config_t *security_cfg)
	Atomically creates a Server, installs Security, and calls listen(). More...
VLINK_C_API_EXPORT int	vlink_destroy_server (vlink_server_handle_t *handle)
	Destroys a Server node and frees every internal resource, including the request/reply coordination state. More...
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. More...
Method model – Client
Client
VLINK_C_API_EXPORT int	vlink_create_client (const char *url, const vlink_schema_info_t *schema_info, vlink_client_handle_t *handle)
	Creates a Client node and initialises it on the given URL. More...
VLINK_C_API_EXPORT int	vlink_destroy_client (vlink_client_handle_t *handle)
	Destroys a Client node and releases every associated resource. More...
VLINK_C_API_EXPORT int	vlink_has_server (const vlink_client_handle_t handle)
	Checks whether the Client is connected to a Server. More...
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 timeout_ms expires. More...
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. More...
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 for the response. More...
Field model – Setter
Setter
VLINK_C_API_EXPORT int	vlink_create_setter (const char *url, const vlink_schema_info_t *schema_info, vlink_setter_handle_t *handle)
	Creates a Setter node and initialises it on the given URL. More...
VLINK_C_API_EXPORT int	vlink_destroy_setter (vlink_setter_handle_t *handle)
	Destroys a Setter node and releases every associated resource. More...
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. More...
Field model – Getter
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)
	Creates a Getter node, initialises it, and optionally registers a change callback. More...
VLINK_C_API_EXPORT int	vlink_create_secure_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, const vlink_security_config_t *security_cfg)
	Atomically creates a Getter, installs Security, and calls listen(). More...
VLINK_C_API_EXPORT int	vlink_destroy_getter (vlink_getter_handle_t *handle)
	Destroys a Getter node and releases every associated resource. More...
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. More...
Transport-layer TLS (SSL options)
VLINK_C_API_EXPORT void	vlink_ssl_options_init (vlink_ssl_options_t *opt)
	Zero-initialises opt and applies the canonical TLS defaults. More...
VLINK_C_API_EXPORT int	vlink_create_publisher_with_ssl_options (const char *url, const vlink_schema_info_t *schema_info, vlink_publisher_handle_t *handle, const vlink_ssl_options_t *opt)
	Creates a Publisher and applies TLS options before transport initialisation. More...
VLINK_C_API_EXPORT int	vlink_create_subscriber_with_ssl_options (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, const vlink_ssl_options_t *opt)
	Creates a Subscriber and applies TLS options before transport initialisation. More...
VLINK_C_API_EXPORT int	vlink_create_server_with_ssl_options (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, const vlink_ssl_options_t *opt)
	Creates a Server and applies TLS options before transport initialisation. More...
VLINK_C_API_EXPORT int	vlink_create_client_with_ssl_options (const char *url, const vlink_schema_info_t *schema_info, vlink_client_handle_t *handle, const vlink_ssl_options_t *opt)
	Creates a Client and applies TLS options before transport initialisation. More...
VLINK_C_API_EXPORT int	vlink_create_setter_with_ssl_options (const char *url, const vlink_schema_info_t *schema_info, vlink_setter_handle_t *handle, const vlink_ssl_options_t *opt)
	Creates a Setter and applies TLS options before transport initialisation. More...
VLINK_C_API_EXPORT int	vlink_create_getter_with_ssl_options (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, const vlink_ssl_options_t *opt)
	Creates a Getter and applies TLS options before transport initialisation. More...
VLINK_C_API_EXPORT int	vlink_create_secure_publisher_with_ssl_options (const char *url, const vlink_schema_info_t *schema_info, vlink_publisher_handle_t *handle, const vlink_security_config_t *security_cfg, const vlink_ssl_options_t *opt)
	Creates a secure Publisher and applies TLS options before transport initialisation. More...
VLINK_C_API_EXPORT int	vlink_create_secure_subscriber_with_ssl_options (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, const vlink_security_config_t *security_cfg, const vlink_ssl_options_t *opt)
	Creates a secure Subscriber and applies TLS options before transport initialisation. More...
VLINK_C_API_EXPORT int	vlink_create_secure_server_with_ssl_options (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, const vlink_security_config_t *security_cfg, const vlink_ssl_options_t *opt)
	Creates a secure Server and applies TLS options before transport initialisation. More...
VLINK_C_API_EXPORT int	vlink_create_secure_client_with_ssl_options (const char *url, const vlink_schema_info_t *schema_info, vlink_client_handle_t *handle, const vlink_security_config_t *security_cfg, const vlink_ssl_options_t *opt)
	Creates a secure Client and applies TLS options before transport initialisation. More...
VLINK_C_API_EXPORT int	vlink_create_secure_setter_with_ssl_options (const char *url, const vlink_schema_info_t *schema_info, vlink_setter_handle_t *handle, const vlink_security_config_t *security_cfg, const vlink_ssl_options_t *opt)
	Creates a secure Setter and applies TLS options before transport initialisation. More...
VLINK_C_API_EXPORT int	vlink_create_secure_getter_with_ssl_options (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, const vlink_security_config_t *security_cfg, const vlink_ssl_options_t *opt)
	Creates a secure Getter and applies TLS options before transport initialisation. More...
VLINK_C_API_EXPORT int	vlink_publisher_set_ssl_options (vlink_publisher_handle_t *handle, const vlink_ssl_options_t *opt)
	Applies TLS options to a Publisher handle. More...
VLINK_C_API_EXPORT int	vlink_subscriber_set_ssl_options (vlink_subscriber_handle_t *handle, const vlink_ssl_options_t *opt)
	Applies TLS options to a Subscriber handle. More...
VLINK_C_API_EXPORT int	vlink_server_set_ssl_options (vlink_server_handle_t *handle, const vlink_ssl_options_t *opt)
	Applies TLS options to a Server handle. More...
VLINK_C_API_EXPORT int	vlink_client_set_ssl_options (vlink_client_handle_t *handle, const vlink_ssl_options_t *opt)
	Applies TLS options to a Client handle. More...
VLINK_C_API_EXPORT int	vlink_setter_set_ssl_options (vlink_setter_handle_t *handle, const vlink_ssl_options_t *opt)
	Applies TLS options to a Setter handle. More...
VLINK_C_API_EXPORT int	vlink_getter_set_ssl_options (vlink_getter_handle_t *handle, const vlink_ssl_options_t *opt)
	Applies TLS options to a Getter handle. More...

Security – standalone Security handle and node-side helpers
Security
typedef struct vlink_security *	vlink_security_handle_t
	Opaque handle for a standalone Security instance. More...
typedef int(*	vlink_security_callback_t) (const uint8_t *in, size_t in_size, uint8_t **out, size_t *out_size, void *user)
	Optional user-provided encrypt/decrypt callback for vlink_security_config_t. More...
VLINK_C_API_EXPORT void	vlink_security_config_init (vlink_security_config_t *cfg)
	Zero-initialises cfg and applies the C API default PBKDF2 / replay settings. More...
VLINK_C_API_EXPORT vlink_security_handle_t	vlink_security_create (const vlink_security_config_t *cfg)
	Creates a standalone Security instance from cfg. More...
VLINK_C_API_EXPORT void	vlink_security_destroy (vlink_security_handle_t sec)
	Destroys a standalone Security instance. More...
VLINK_C_API_EXPORT int	vlink_security_encrypt (vlink_security_handle_t sec, const uint8_t *in, const size_t in_size, uint8_t **out, size_t *out_size)
	Encrypts a plaintext buffer using the active mode configured on sec. More...
VLINK_C_API_EXPORT int	vlink_security_decrypt (vlink_security_handle_t sec, const uint8_t *in, const size_t in_size, uint8_t **out, size_t *out_size)
	Decrypts a ciphertext buffer using the active mode configured on sec. More...
VLINK_C_API_EXPORT void	vlink_security_free_buffer (uint8_t *buf)
	Releases a buffer returned by vlink_security_encrypt() or vlink_security_decrypt(). More...
VLINK_C_API_EXPORT int	vlink_create_secure_publisher (const char *url, const vlink_schema_info_t *schema_info, vlink_publisher_handle_t *handle, const vlink_security_config_t *security_cfg)
	Atomically creates a Publisher and installs Security. More...
VLINK_C_API_EXPORT int	vlink_create_secure_client (const char *url, const vlink_schema_info_t *schema_info, vlink_client_handle_t *handle, const vlink_security_config_t *security_cfg)
	Atomically creates a Client and installs Security. More...
VLINK_C_API_EXPORT int	vlink_create_secure_setter (const char *url, const vlink_schema_info_t *schema_info, vlink_setter_handle_t *handle, const vlink_security_config_t *security_cfg)
	Atomically creates a Setter and installs Security. More...

Detailed Description

Pure C binding over the VLink communication middleware.

Exposes a stable, language-agnostic C surface across the three VLink communication models. Every public function wraps a corresponding C++ template instantiation that uses vlink::Bytes as its payload type, so the C ABI never has to leak C++ type information.

Model Mapping

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

C / C++ Boundary

+-----------------------+        +---------------------------------+
|   User C / C++ code   |        |  vlink C++ core templates       |
|                       |        |  Publisher<Bytes>, Server<...>, |
|  vlink_publish(...)   |        |  Setter<Bytes>, Security, ...   |
|  vlink_invoke(...)    |        +----------------+----------------+
|  vlink_set(...)       |                         ^
+-----------+-----------+                         |
            |   handle.native_handle (opaque)     |
            v                                     |
+-----------------------+   shallow Bytes::wrap   |
|   c_api.h boundary    +-------------------------+
|  (this file)          |
+-----------------------+

Return Code Family

Code	Meaning
VLINK_RET_NO_ERROR (0)	Success.
VLINK_RET_UNEXPECTED_ERROR	Condition not met yet (e.g. no subscribers).
VLINK_RET_INVALID_ERROR	Null pointer / invalid handle / bad arguments.
VLINK_RET_MEMORY_ERROR	Allocation failure or output buffer too small.
VLINK_RET_RUNTIME_ERROR	Runtime state error or C++ construction exception.
VLINK_RET_TRANSFER_ERROR	Publish / listen / invoke operation failed.
VLINK_RET_UNKNOWN_ERROR (-1)	Unclassified internal error.

Server Reply Protocol

The vlink_server_handle_t::reserved array coordinates the synchronous request-reply flow. Inside vlink_req_callback_t a call to vlink_reply() stores the response. When the callback returns, the relayed reply is sent to the client. Calling vlink_reply() after the callback returns fails with VLINK_RET_RUNTIME_ERROR because no request is in progress.

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

Example – Event (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; }
vlink_subscriber_handle_t sub;
vlink_create_subscriber("dds://my/topic", &schema, &sub, on_message, NULL);

Example – Method (Server / Client)

vlink_client_handle_t cli;
vlink_schema_info_t schema = {"demo.raw.Echo", VLINK_SCHEMA_RAW};
vlink_create_client("dds://echo", &schema, &cli);
vlink_wait_for_server(cli, 1000);
vlink_invoke(cli, req_buf, req_size, on_response, NULL);

Example – Field (Setter / Getter)

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] holds the latest value
}

Note

• Internally the C API uses vlink::Publisher<vlink::Bytes> and equivalents. The vlink_schema_info_t aggregate configures ser + schema atomically.
• Every create/destroy pair must be balanced; handles are not thread-safe for concurrent create/destroy calls.
• vlink_get() copies the latest value into the caller-supplied buffer and returns VLINK_RET_MEMORY_ERROR when the buffer is smaller than the payload.
• vlink_publish_by_force() publishes even with no matched subscribers, useful for transient-local-durability scenarios.

Macro Definition Documentation

VLINK_C_API_EXPORT

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

Typedef Documentation

vlink_connect_callback_t

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

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

Parameters

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

Note

Invoked from a VLink-internal event thread; keep the body short and avoid blocking calls.

vlink_msg_callback_t

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

Callback fired when a Subscriber or Getter receives a message.

Parameters

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

Note

Invoked on the underlying receive thread. The data buffer is only valid for the duration of the callback – copy if you need to retain it.

vlink_req_callback_t

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

Callback fired when a Server receives an RPC request.

Invoked synchronously on the Server's dispatch thread while an internal mutex is held. Call vlink_reply() from inside this callback to provide a non-empty response before it returns. Without a vlink_reply() call the request completes with an empty payload. Calling vlink_reply() after the callback returns fails with VLINK_RET_RUNTIME_ERROR because no request is in progress.

Parameters

data	Pointer to the request payload bytes.
size	Number of bytes available at 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 fired when a Client receives an RPC response.

Parameters

data	Pointer to the response payload bytes; may be NULL when the server did not provide a response.
size	Number of bytes available at data.
user_data	Opaque pointer supplied at invocation time.

vlink_security_callback_t

typedef int(* vlink_security_callback_t) (const uint8_t *in, size_t in_size, uint8_t **out, size_t *out_size, void *user)

Optional user-provided encrypt/decrypt callback for vlink_security_config_t.

Installing both encrypt_callback and decrypt_callback overrides the built-in AEAD path entirely. Implementations must allocate *out with malloc (or another allocator compatible with free) and write the byte count into *out_size. The C API releases the buffer with free() after copying its contents into the destination supplied to vlink_security_encrypt() / vlink_security_decrypt(). Custom encrypt/decrypt callbacks attached to the same security handle are serialised by VLink; callbacks shared across handles must protect their own shared state.

Parameters

in	Plaintext (encrypt) or ciphertext (decrypt) input pointer.
in_size	Number of bytes available at in.
out	Output parameter receiving a freshly allocated buffer.
out_size	Output parameter receiving the byte count of out.
user	Opaque pointer supplied via callback_user_data.

Returns

0 on success, non-zero on failure.

Note

On Windows the buffer returned through out is released inside the vlink shared library using its own CRT free(). The callback implementation MUST therefore allocate *out with the matching CRT (e.g. the msvcrt / UCRT malloc linked into the vlink DLL). Mixing CRTs across DLL boundaries leads to heap corruption. When in doubt, build the callback host with the same toolchain/runtime as the vlink shared library, or expose your own free helper through callback_user_data.

vlink_security_config_t

typedef struct vlink_security_config_s vlink_security_config_t

vlink_security_handle_t

typedef struct vlink_security* vlink_security_handle_t

Opaque handle for a standalone Security instance.

Wraps a heap-allocated vlink::Security that performs authenticated, message-level encryption. Construct via vlink_security_create() and destroy via vlink_security_destroy(). The same handle drives both vlink_security_encrypt() and vlink_security_decrypt() as long as the configuration supplies the matching key material for each direction.

Enumeration Type Documentation

vlink_ret_t

enum vlink_ret_t

Return code for VLink C API functions that report vlink_ret_t.

VLINK_RET_NO_ERROR is the only success code. Positive values classify recoverable API states or errors and VLINK_RET_UNKNOWN_ERROR (-1) indicates an unclassified internal error. Always check the symbolic value – do not treat every non-negative result as success.

Enumerator
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 matched).
VLINK_RET_INVALID_ERROR	Null pointer argument or otherwise invalid handle / arguments.
VLINK_RET_MEMORY_ERROR	Allocation failure or caller-provided buffer is too small.
VLINK_RET_RUNTIME_ERROR	Runtime state error or C++ construction exception.
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.

The numeric values are kept in sync with vlink::SchemaType (see include/vlink/impl/types.h), so the C API implementation can cast between the two enums safely. Always reference the symbolic names – the underlying mapping is intentionally opaque at source level.

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

Function Documentation

vlink_client_set_ssl_options()

VLINK_C_API_EXPORT int vlink_client_set_ssl_options	(	vlink_client_handle_t *	handle,
		const vlink_ssl_options_t *	opt
	)

Applies TLS options to a Client handle.

Parameters

handle	Client handle. Must not be NULL.
opt	Options aggregate. Must not be NULL.

Returns

Same status codes as vlink_publisher_set_ssl_options().

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
	)

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

Parameters

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

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR for NULL url / handle, partially-filled schema_info, or invalid schema_info->schema; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_client().

vlink_create_client_with_ssl_options()

VLINK_C_API_EXPORT int vlink_create_client_with_ssl_options	(	const char *	url,
		const vlink_schema_info_t *	schema_info,
		vlink_client_handle_t *	handle,
		const vlink_ssl_options_t *	opt
	)

Creates a Client and applies TLS options before transport initialisation.

Parameters

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

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad arguments including opt == NULL; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_client().

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
	)

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

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

Parameters

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

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR for NULL url / handle, partially-filled schema_info, or invalid schema_info->schema; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_TRANSFER_ERROR if listen() fails; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_getter().

vlink_create_getter_with_ssl_options()

VLINK_C_API_EXPORT int vlink_create_getter_with_ssl_options	(	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,
		const vlink_ssl_options_t *	opt
	)

Creates a Getter and applies TLS options before transport initialisation.

Parameters

url	VLink field URL. Must not be NULL.
schema_info	Optional bundled ser + schema metadata.
handle	Output handle. Must not be NULL.
msg_callback	Push-mode callback, or NULL for poll mode.
user_data	Opaque pointer forwarded to msg_callback.
opt	TLS options. Must not be NULL.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad arguments including opt == NULL; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_TRANSFER_ERROR if listen() fails; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_getter().

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
	)

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

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

Parameters

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

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR when url or handle is NULL, when schema_info is only partially filled, or when schema_info->schema is invalid; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_RUNTIME_ERROR if construction throws.

Note

Caller owns the handle and must release it through vlink_destroy_publisher(). Not thread-safe with concurrent create/destroy on the same handle.

vlink_create_publisher_with_ssl_options()

VLINK_C_API_EXPORT int vlink_create_publisher_with_ssl_options	(	const char *	url,
		const vlink_schema_info_t *	schema_info,
		vlink_publisher_handle_t *	handle,
		const vlink_ssl_options_t *	opt
	)

Creates a Publisher and applies TLS options before transport initialisation.

Parameters

url	VLink topic URL. Must not be NULL.
schema_info	Optional bundled ser + schema metadata.
handle	Output handle. Must not be NULL.
opt	TLS options. Must not be NULL.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad arguments including opt == NULL; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_publisher().

vlink_create_secure_client()

VLINK_C_API_EXPORT int vlink_create_secure_client	(	const char *	url,
		const vlink_schema_info_t *	schema_info,
		vlink_client_handle_t *	handle,
		const vlink_security_config_t *	security_cfg
	)

Atomically creates a Client and installs Security.

Builds the vlink::Security from security_cfg before init() returns, so outbound requests through vlink_invoke() are encrypted from the very first call and inbound responses are decrypted before vlink_resp_callback_t fires.

Parameters

url	VLink service URL. Must not be NULL.
schema_info	Optional bundled ser + schema metadata.
handle	Output handle. Must not be NULL.
security_cfg	Security configuration. Must not be NULL. A zero-initialised configuration uses the built-in default symmetric slot with replay protection disabled; otherwise both encrypt- and decrypt-capable slots are required.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad arguments; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_client().

vlink_create_secure_client_with_ssl_options()

VLINK_C_API_EXPORT int vlink_create_secure_client_with_ssl_options	(	const char *	url,
		const vlink_schema_info_t *	schema_info,
		vlink_client_handle_t *	handle,
		const vlink_security_config_t *	security_cfg,
		const vlink_ssl_options_t *	opt
	)

Creates a secure Client and applies TLS options before transport initialisation.

Parameters

url	VLink service URL. Must not be NULL.
schema_info	Optional bundled ser + schema metadata.
handle	Output handle. Must not be NULL.
security_cfg	Security configuration. Must not be NULL.
opt	TLS options. Must not be NULL.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad arguments including security_cfg == NULL or opt == NULL; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_client().

vlink_create_secure_getter()

VLINK_C_API_EXPORT int vlink_create_secure_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,
		const vlink_security_config_t *	security_cfg
	)

Atomically creates a Getter, installs Security, and calls listen().

Builds the vlink::Security from security_cfg before the internal push-mode listen() registration completes. Polling-mode Getters (msg_callback == NULL) see the attached Security from the very first vlink_get() call. A secure polling Getter caches the last authenticated ciphertext/plaintext pair internally so repeated vlink_get() calls for the same latest field value return the cached plaintext without tripping replay protection. Fresh inbound frames still flow through Security::decrypt(). Security configuration is one-shot at creation – no separate runtime entry point exists.

Parameters

url	VLink field URL. Must not be NULL.
schema_info	Optional bundled ser + schema metadata.
handle	Output handle. Must not be NULL.
msg_callback	Push-mode callback, or NULL for poll mode.
user_data	Opaque pointer forwarded to msg_callback.
security_cfg	Security configuration. Must not be NULL. A zero-initialised configuration uses the built-in default symmetric slot with replay protection disabled; otherwise a decrypt-capable slot is required.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad arguments; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_TRANSFER_ERROR if listen() fails; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_getter().

vlink_create_secure_getter_with_ssl_options()

VLINK_C_API_EXPORT int vlink_create_secure_getter_with_ssl_options	(	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,
		const vlink_security_config_t *	security_cfg,
		const vlink_ssl_options_t *	opt
	)

Creates a secure Getter and applies TLS options before transport initialisation.

Parameters

url	VLink field URL. Must not be NULL.
schema_info	Optional bundled ser + schema metadata.
handle	Output handle. Must not be NULL.
msg_callback	Push-mode callback, or NULL for poll mode.
user_data	Opaque pointer forwarded to msg_callback.
security_cfg	Security configuration. Must not be NULL.
opt	TLS options. Must not be NULL.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad arguments including security_cfg == NULL or opt == NULL; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_TRANSFER_ERROR if listen() fails; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_getter().

vlink_create_secure_publisher()

VLINK_C_API_EXPORT int vlink_create_secure_publisher	(	const char *	url,
		const vlink_schema_info_t *	schema_info,
		vlink_publisher_handle_t *	handle,
		const vlink_security_config_t *	security_cfg
	)

Atomically creates a Publisher and installs Security.

Builds the vlink::Security from security_cfg before init() returns, so the encrypt path is wired the first time vlink_publish() is called. Security configuration is one-shot at creation – no separate enable_security() entry point exists.

Parameters

url	VLink topic URL. Must not be NULL.
schema_info	Optional bundled ser + schema metadata.
handle	Output handle. Must not be NULL.
security_cfg	Security configuration. Must not be NULL. A zero-initialised configuration uses the built-in default symmetric slot with replay protection disabled; otherwise an encrypt-capable slot is required.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad arguments (including a non-encrypt-capable security_cfg); VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_publisher().

vlink_create_secure_publisher_with_ssl_options()

VLINK_C_API_EXPORT int vlink_create_secure_publisher_with_ssl_options	(	const char *	url,
		const vlink_schema_info_t *	schema_info,
		vlink_publisher_handle_t *	handle,
		const vlink_security_config_t *	security_cfg,
		const vlink_ssl_options_t *	opt
	)

Creates a secure Publisher and applies TLS options before transport initialisation.

Parameters

url	VLink topic URL. Must not be NULL.
schema_info	Optional bundled ser + schema metadata.
handle	Output handle. Must not be NULL.
security_cfg	Security configuration. Must not be NULL.
opt	TLS options. Must not be NULL.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad arguments including security_cfg == NULL or opt == NULL; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_publisher().

vlink_create_secure_server()

VLINK_C_API_EXPORT int vlink_create_secure_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,
		const vlink_security_config_t *	security_cfg
	)

Atomically creates a Server, installs Security, and calls listen().

Builds the vlink::Security from security_cfg before the internal listen() registration completes. Inbound requests are decrypted through Security::decrypt(); replies written via vlink_reply() are encrypted through Security::encrypt(). Without a vlink_reply() call, or with size == 0, the request still completes with an empty response so the C API reply protocol is preserved. When security_cfg->advanced.aad_context is empty the wrapper binds security to url|ser|schema; absent schema_info defaults to the C API Bytes binding url||VLINK_SCHEMA_RAW. Security configuration is one-shot at creation – no separate runtime entry point exists.

Parameters

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.
user_data	Opaque pointer forwarded to req_callback.
security_cfg	Security configuration. Must not be NULL. A zero-initialised configuration uses the built-in default symmetric slot with replay protection disabled; otherwise both encrypt- and decrypt-capable slots are required.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad arguments; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_TRANSFER_ERROR if listen() fails; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_server().

vlink_create_secure_server_with_ssl_options()

VLINK_C_API_EXPORT int vlink_create_secure_server_with_ssl_options	(	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,
		const vlink_security_config_t *	security_cfg,
		const vlink_ssl_options_t *	opt
	)

Creates a secure Server and applies TLS options before transport initialisation.

Parameters

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.
user_data	Opaque pointer forwarded to req_callback.
security_cfg	Security configuration. Must not be NULL.
opt	TLS options. Must not be NULL.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad arguments including security_cfg == NULL or opt == NULL; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_TRANSFER_ERROR if listen() fails; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_server().

vlink_create_secure_setter()

VLINK_C_API_EXPORT int vlink_create_secure_setter	(	const char *	url,
		const vlink_schema_info_t *	schema_info,
		vlink_setter_handle_t *	handle,
		const vlink_security_config_t *	security_cfg
	)

Atomically creates a Setter and installs Security.

Builds the vlink::Security from security_cfg before init() returns, so the encrypt path is wired the first time vlink_set() is called. The Setter's normal latest-value cache owns the encrypted Bytes payload, so late-joining Getters receive the current value without depending on the caller's input buffer.

Parameters

url	VLink field URL. Must not be NULL.
schema_info	Optional bundled ser + schema metadata.
handle	Output handle. Must not be NULL.
security_cfg	Security configuration. Must not be NULL. A zero-initialised configuration uses the built-in default symmetric slot with replay protection disabled; otherwise an encrypt-capable slot is required.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad arguments; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_setter().

vlink_create_secure_setter_with_ssl_options()

VLINK_C_API_EXPORT int vlink_create_secure_setter_with_ssl_options	(	const char *	url,
		const vlink_schema_info_t *	schema_info,
		vlink_setter_handle_t *	handle,
		const vlink_security_config_t *	security_cfg,
		const vlink_ssl_options_t *	opt
	)

Creates a secure Setter and applies TLS options before transport initialisation.

Parameters

url	VLink field URL. Must not be NULL.
schema_info	Optional bundled ser + schema metadata.
handle	Output handle. Must not be NULL.
security_cfg	Security configuration. Must not be NULL.
opt	TLS options. Must not be NULL.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad arguments including security_cfg == NULL or opt == NULL; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_setter().

vlink_create_secure_subscriber()

VLINK_C_API_EXPORT int vlink_create_secure_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,
		const vlink_security_config_t *	security_cfg
	)

Atomically creates a Subscriber, installs Security, and calls listen().

Builds the vlink::Security from security_cfg before the internal listen() registration completes, so every inbound frame is run through Security::decrypt(). Security configuration is one-shot at creation – no separate runtime entry point exists.

On failure (bad URL/schema/cfg, non-decrypt-capable security state, listen failure) no resources leak; any internal handle stored before the failure is cleared.

Parameters

url	VLink subscriber URL. Must not be NULL.
schema_info	Optional bundled ser + schema metadata.
handle	Output handle. Must not be NULL.
msg_callback	Message handler. Must not be NULL.
user_data	Opaque pointer forwarded to msg_callback.
security_cfg	Security configuration. Must not be NULL. A zero-initialised configuration uses the built-in default symmetric slot with replay protection disabled; otherwise a decrypt-capable slot is required.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad arguments (including a non-decrypt-capable security_cfg); VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_TRANSFER_ERROR if listen() fails; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_subscriber().

vlink_create_secure_subscriber_with_ssl_options()

VLINK_C_API_EXPORT int vlink_create_secure_subscriber_with_ssl_options	(	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,
		const vlink_security_config_t *	security_cfg,
		const vlink_ssl_options_t *	opt
	)

Creates a secure Subscriber and applies TLS options before transport initialisation.

Parameters

url	VLink subscriber URL. Must not be NULL.
schema_info	Optional bundled ser + schema metadata.
handle	Output handle. Must not be NULL.
msg_callback	Message handler. Must not be NULL.
user_data	Opaque pointer forwarded to msg_callback.
security_cfg	Security configuration. Must not be NULL.
opt	TLS options. Must not be NULL.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad arguments including security_cfg == NULL or opt == NULL; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_TRANSFER_ERROR if listen() fails; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_subscriber().

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
	)

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 serialises request/reply state during each invocation. Call vlink_reply() from inside req_callback to set a response before the callback returns.

Parameters

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.
user_data	Opaque pointer forwarded to req_callback.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR for NULL arguments, partially-filled schema_info, or invalid schema_info->schema; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_TRANSFER_ERROR if listen() fails; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_server().

vlink_create_server_with_ssl_options()

VLINK_C_API_EXPORT int vlink_create_server_with_ssl_options	(	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,
		const vlink_ssl_options_t *	opt
	)

Creates a Server and applies TLS options before transport initialisation.

Parameters

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.
user_data	Opaque pointer forwarded to req_callback.
opt	TLS options. Must not be NULL.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad arguments including opt == NULL; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_TRANSFER_ERROR if listen() fails; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_server().

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
	)

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

Parameters

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

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR for NULL url / handle, partially-filled schema_info, or invalid schema_info->schema; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_setter().

vlink_create_setter_with_ssl_options()

VLINK_C_API_EXPORT int vlink_create_setter_with_ssl_options	(	const char *	url,
		const vlink_schema_info_t *	schema_info,
		vlink_setter_handle_t *	handle,
		const vlink_ssl_options_t *	opt
	)

Creates a Setter and applies TLS options before transport initialisation.

Parameters

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

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad arguments including opt == NULL; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_setter().

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
	)

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

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

Parameters

url	VLink topic URL. Must not be NULL.
schema_info	Optional bundled ser + schema metadata.
handle	Output handle. Must not be NULL.
msg_callback	Message handler. Must not be NULL.
user_data	Opaque pointer forwarded to msg_callback.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR for NULL arguments, partially-filled schema_info, or invalid schema_info->schema; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_TRANSFER_ERROR if listen() fails; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_subscriber().

vlink_create_subscriber_with_ssl_options()

VLINK_C_API_EXPORT int vlink_create_subscriber_with_ssl_options	(	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,
		const vlink_ssl_options_t *	opt
	)

Creates a Subscriber and applies TLS options before transport initialisation.

Parameters

url	VLink topic URL. Must not be NULL.
schema_info	Optional bundled ser + schema metadata.
handle	Output handle. Must not be NULL.
msg_callback	Message handler. Must not be NULL.
user_data	Opaque pointer forwarded to msg_callback.
opt	TLS options. Must not be NULL.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad arguments including opt == NULL; VLINK_RET_MEMORY_ERROR on pool allocation failure; VLINK_RET_TRANSFER_ERROR if listen() fails; VLINK_RET_RUNTIME_ERROR on construction exception.

Note

Caller owns the handle and must release it with vlink_destroy_subscriber().

vlink_destroy_client()

VLINK_C_API_EXPORT int vlink_destroy_client

(

vlink_client_handle_t *

handle

)

Destroys a Client node and releases every associated resource.

Parameters

handle

Client handle to destroy. Must not be NULL.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad handle.

Note

Must not be called concurrently with any other operation on the same handle.

vlink_destroy_getter()

VLINK_C_API_EXPORT int vlink_destroy_getter

(

vlink_getter_handle_t *

handle

)

Destroys a Getter node and releases every associated resource.

Parameters

handle

Getter handle to destroy. Must not be NULL.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad handle.

Note

Must not be called concurrently with any other operation on the same handle.

vlink_destroy_publisher()

VLINK_C_API_EXPORT int vlink_destroy_publisher

(

vlink_publisher_handle_t *

handle

)

Destroys a Publisher node and releases every associated resource.

Parameters

handle

Publisher handle to destroy. Must not be NULL.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR when handle or its native_handle is NULL.

Note

Must not be called concurrently with any other operation on the same handle.

vlink_destroy_server()

VLINK_C_API_EXPORT int vlink_destroy_server

(

vlink_server_handle_t *

handle

)

Destroys a Server node and frees every internal resource, including the request/reply coordination state.

Parameters

handle

Server handle to destroy. Must not be NULL.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad handle.

Note

Must not be called concurrently with any other operation on the same handle.

vlink_destroy_setter()

VLINK_C_API_EXPORT int vlink_destroy_setter

(

vlink_setter_handle_t *

handle

)

Destroys a Setter node and releases every associated resource.

Parameters

handle

Setter handle to destroy. Must not be NULL.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad handle.

Note

Must not be called concurrently with any other operation on the same handle.

vlink_destroy_subscriber()

VLINK_C_API_EXPORT int vlink_destroy_subscriber

(

vlink_subscriber_handle_t *

handle

)

Destroys a Subscriber node and releases every associated resource.

Parameters

handle

Subscriber handle to destroy. Must not be NULL.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad handle.

Note

Must not be called concurrently with any other operation on the same 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.

Parameters

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

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad handle or a NULL connect_callback.

Note

The callback runs on the Client's internal event thread.

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.

Parameters

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

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad handle or a NULL connect_callback.

Note

The callback runs on the Publisher's internal event thread.

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 buffer capacity; on success it is updated to the actual byte count. When the buffer is too small the function returns VLINK_RET_MEMORY_ERROR and writes the required byte count into *size so the caller can allocate and retry. data is left unmodified in the error case.

Parameters

handle	Getter handle.
data	Output buffer. Must not be NULL.
size	In/out: buffer capacity on entry; actual or required size on exit. Must not be NULL.

Returns

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 (required size written back); VLINK_RET_INVALID_ERROR on bad arguments.

Note

Thread-safe.

vlink_getter_set_ssl_options()

VLINK_C_API_EXPORT int vlink_getter_set_ssl_options	(	vlink_getter_handle_t *	handle,
		const vlink_ssl_options_t *	opt
	)

Applies TLS options to a Getter handle.

Parameters

handle	Getter handle. Must not be NULL.
opt	Options aggregate. Must not be NULL.

Returns

Same status codes as vlink_publisher_set_ssl_options().

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.

Parameters

handle

Client handle.

Returns

VLINK_RET_NO_ERROR if connected; VLINK_RET_UNEXPECTED_ERROR if not yet connected; VLINK_RET_INVALID_ERROR on bad handle.

Note

Thread-safe.

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.

Parameters

handle

Publisher handle.

Returns

VLINK_RET_NO_ERROR if subscribers are present; VLINK_RET_UNEXPECTED_ERROR when none are matched yet; VLINK_RET_INVALID_ERROR on bad handle.

Note

Thread-safe.

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 for the response.

Internally invokes vlink::Client::invoke() with a shallow-copy Bytes wrapping data. resp_callback fires asynchronously on the underlying vlink::Client callback context once the Server reply arrives. Pass NULL for resp_callback when the response is not needed. Secure clients treat an empty transport response as the protocol's empty response and do not route it through Security::decrypt().

Parameters

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.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_TRANSFER_ERROR if encryption or invoke fails; VLINK_RET_INVALID_ERROR on bad handle or data == NULL with size > 0.

Note

Thread-safe. The resp_callback may fire on a transport-managed thread.

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 every matched Subscriber.

The implementation wraps data in a shallow-copy vlink::Bytes – zero-copy when the transport supports it. Returns VLINK_RET_TRANSFER_ERROR when no subscribers are matched and the publisher does not allow forced delivery.

Parameters

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

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_TRANSFER_ERROR when publishing fails; VLINK_RET_INVALID_ERROR on bad handle or data == NULL with size > 0.

Note

Thread-safe with respect to other publishes on the same 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 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.

Parameters

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

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_TRANSFER_ERROR on failure; VLINK_RET_INVALID_ERROR on bad handle or data == NULL with size > 0.

Note

Same threading guarantees as vlink_publish().

vlink_publisher_set_ssl_options()

VLINK_C_API_EXPORT int vlink_publisher_set_ssl_options	(	vlink_publisher_handle_t *	handle,
		const vlink_ssl_options_t *	opt
	)

Applies TLS options to a Publisher handle.

Forwards opt to Node::set_ssl_options() on the underlying transport, which writes the corresponding ssl.* property entries. The transport backend reads those entries during connection setup. Handles returned by this C API are already initialised, so this setter returns VLINK_RET_RUNTIME_ERROR for normal C handles. Use the matching vlink_create_*_with_ssl_options() function when TLS must affect the initial transport connection.

Parameters

handle	Publisher handle. Must not be NULL.
opt	Options aggregate. Must not be NULL.

Returns

VLINK_RET_NO_ERROR on success for an uninitialised internal handle; VLINK_RET_INVALID_ERROR on bad arguments; VLINK_RET_RUNTIME_ERROR once the handle has been initialised.

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 inside vlink_req_callback_t while the internal request context is active. The response is copied into owned internal storage, or encrypted into owned internal storage for secure servers. A size of 0 is accepted and produces the protocol's empty response.

Parameters

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

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad handle or data == NULL with size > 0; VLINK_RET_RUNTIME_ERROR when no pending request is in progress; VLINK_RET_MEMORY_ERROR if internal allocation fails; VLINK_RET_TRANSFER_ERROR if secure response encryption fails.

Note

Only valid inside the vlink_req_callback_t.

vlink_security_config_init()

VLINK_C_API_EXPORT void vlink_security_config_init

(

vlink_security_config_t *

cfg

)

Zero-initialises cfg and applies the C API default PBKDF2 / replay settings.

Convenience initialiser that avoids relying on {0} aggregate initialisation in client code. Once it returns, every string pointer is NULL, the salt buffer is empty, both callbacks and callback_user_data are NULL, pbkdf2_iterations equals 200000, and advanced.replay_window equals 4096. Set advanced.replay_window back to 0 to disable replay checks explicitly. Safe to call on a stack variable before populating fields. Passing the initialised configuration to a Security constructor uses the built-in default symmetric slot when built-in algorithms are enabled.

Example

vlink_security_config_t cfg;
vlink_security_config_init(&cfg);
cfg.passphrase       = "correct horse battery staple";
cfg.pbkdf2_salt      = my_salt_bytes;
cfg.pbkdf2_salt_size = my_salt_size;

Parameters

cfg	Configuration aggregate to initialise. No-op when cfg is NULL.

Note

Safe to call on a freshly declared stack variable.

vlink_security_create()

VLINK_C_API_EXPORT vlink_security_handle_t vlink_security_create

(

const vlink_security_config_t *

cfg

)

Creates a standalone Security instance from cfg.

Allocates a vlink::Security on the heap. When cfg is NULL the call returns NULL and logs a warning. A zero-initialised cfg uses the built-in default symmetric slot when built-in algorithms are enabled, but it leaves advanced.replay_window at 0 so replay protection is disabled. Call vlink_security_config_init() to obtain the C API default PBKDF2/replay settings. Invalid PEM fields or weak RSA keys are logged via VLOG_W and the offending slot is left empty as long as at least one other slot validated.

Example

vlink_security_config_t cfg;
vlink_security_config_init(&cfg);
cfg.passphrase       = "correct horse battery staple";
cfg.pbkdf2_salt      = my_salt_bytes;
cfg.pbkdf2_salt_size = my_salt_size;
 
vlink_security_handle_t sec = vlink_security_create(&cfg);
 
uint8_t* cipher = NULL;
size_t   cipher_size = 0;
vlink_security_encrypt(sec, plain, plain_size, &cipher, &cipher_size);
vlink_security_free_buffer(cipher);
 
vlink_security_destroy(sec);

Parameters

cfg	Configuration aggregate. A zero-initialised aggregate uses the built-in default symmetric slot with replay protection disabled; otherwise provide a callback pair, symmetric key/passphrase, or RSA PEM.

Returns

New vlink_security_handle_t handle; NULL on NULL cfg, on a configuration with no usable cryptographic slot after validation, on allocation failure, or on a C++ construction exception.

Note

Caller owns the handle and must release it via vlink_security_destroy().

vlink_security_decrypt()

VLINK_C_API_EXPORT int vlink_security_decrypt	(	vlink_security_handle_t	sec,
		const uint8_t *	in,
		const size_t	in_size,
		uint8_t **	out,
		size_t *	out_size
	)

Decrypts a ciphertext buffer using the active mode configured on sec.

The plaintext lands in a freshly allocated buffer that the caller owns; release it with vlink_security_free_buffer(). Empty inputs are rejected with VLINK_RET_INVALID_ERROR (a valid built-in ciphertext carries an envelope, tag, and at least one ciphertext byte). Authentication failures – tampered ciphertext, wrong key, invalid signature, or replay – are reported as VLINK_RET_TRANSFER_ERROR.

Parameters

sec	Security handle.
in	Ciphertext input bytes.
in_size	Number of bytes available at in.
out	Output pointer receiving the allocated plaintext buffer. Must not be NULL.
out_size	Output pointer receiving the plaintext byte count. Must not be NULL.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad arguments; VLINK_RET_MEMORY_ERROR if output allocation fails; VLINK_RET_TRANSFER_ERROR if Security::decrypt() fails.

Note

Caller owns *out and must release it via vlink_security_free_buffer().

vlink_security_destroy()

VLINK_C_API_EXPORT void vlink_security_destroy

(

vlink_security_handle_t

sec

)

Destroys a standalone Security instance.

Safe to call with NULL sec (no-op). Symmetric key material is zeroised in place inside the vlink::Security destructor before the buffer is freed.

Parameters

sec	Handle returned by vlink_security_create(), or NULL.

vlink_security_encrypt()

VLINK_C_API_EXPORT int vlink_security_encrypt	(	vlink_security_handle_t	sec,
		const uint8_t *	in,
		const size_t	in_size,
		uint8_t **	out,
		size_t *	out_size
	)

Encrypts a plaintext buffer using the active mode configured on sec.

The ciphertext lands in a freshly allocated buffer that the caller owns; release it with vlink_security_free_buffer(). Following the underlying Security::encrypt() contract, empty inputs (in == NULL or in_size == 0) are rejected with VLINK_RET_INVALID_ERROR.

Parameters

sec	Security handle.
in	Plaintext input bytes.
in_size	Number of bytes available at in.
out	Output pointer receiving the allocated ciphertext buffer. Must not be NULL.
out_size	Output pointer receiving the ciphertext byte count. Must not be NULL.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_INVALID_ERROR on bad arguments; VLINK_RET_MEMORY_ERROR if output allocation fails; VLINK_RET_TRANSFER_ERROR if Security::encrypt() fails.

Note

Caller owns *out and must release it via vlink_security_free_buffer().

vlink_security_free_buffer()

VLINK_C_API_EXPORT void vlink_security_free_buffer

(

uint8_t *

buf

)

Releases a buffer returned by vlink_security_encrypt() or vlink_security_decrypt().

Safe to call with NULL buf (no-op). Buffers obtained from any other source must not be freed through this function.

Parameters

buf	Buffer pointer previously written by an encrypt/decrypt call.

vlink_server_set_ssl_options()

VLINK_C_API_EXPORT int vlink_server_set_ssl_options	(	vlink_server_handle_t *	handle,
		const vlink_ssl_options_t *	opt
	)

Applies TLS options to a Server handle.

Parameters

handle	Server handle. Must not be NULL.
opt	Options aggregate. Must not be NULL.

Returns

Same status codes as vlink_publisher_set_ssl_options().

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 one held by every matched Getter. The input buffer is only read during the vlink_set() call. The underlying Setter<vlink::Bytes> keeps its latest-value cache as an owned Bytes copy, so callers may reuse or release data once the function returns.

Parameters

handle	Setter handle.
data	New field value bytes. Must remain valid for the call.
size	Number of bytes in data.

Returns

VLINK_RET_NO_ERROR on success; VLINK_RET_TRANSFER_ERROR if secure encryption fails; VLINK_RET_INVALID_ERROR on bad handle or data == NULL with size > 0.

Note

Thread-safe with respect to other vlink_set() calls on the same handle.

vlink_setter_set_ssl_options()

VLINK_C_API_EXPORT int vlink_setter_set_ssl_options	(	vlink_setter_handle_t *	handle,
		const vlink_ssl_options_t *	opt
	)

Applies TLS options to a Setter handle.

Parameters

handle	Setter handle. Must not be NULL.
opt	Options aggregate. Must not be NULL.

Returns

Same status codes as vlink_publisher_set_ssl_options().

vlink_ssl_options_init()

VLINK_C_API_EXPORT void vlink_ssl_options_init

(

vlink_ssl_options_t *

opt

)

Zero-initialises opt and applies the canonical TLS defaults.

After the call every string pointer is NULL and verify_peer equals 1 (matching vlink::SslOptions defaults). Safe to call on a stack variable before populating the fields you actually need.

Example

vlink_ssl_options_t opt;
vlink_ssl_options_init(&opt);
opt.ca_file   = "/etc/certs/ca.pem";
opt.cert_file = "/etc/certs/client.pem";
opt.key_file  = "/etc/certs/client-key.pem";
vlink_create_publisher_with_ssl_options("mqtt://sensor/data", &schema, &pub, &opt);

Parameters

opt	Options aggregate to initialise. No-op when opt is NULL.

vlink_subscriber_set_ssl_options()

VLINK_C_API_EXPORT int vlink_subscriber_set_ssl_options	(	vlink_subscriber_handle_t *	handle,
		const vlink_ssl_options_t *	opt
	)

Applies TLS options to a Subscriber handle.

Parameters

handle	Subscriber handle. Must not be NULL.
opt	Options aggregate. Must not be NULL.

Returns

Same status codes as vlink_publisher_set_ssl_options().

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 timeout_ms expires.

Parameters

handle	Client handle.
timeout_ms	Maximum wait time in milliseconds.

Returns

VLINK_RET_NO_ERROR if connected; VLINK_RET_UNEXPECTED_ERROR on timeout; VLINK_RET_INVALID_ERROR on bad handle.

Note

Blocks the calling thread.

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 timeout_ms expires.

Parameters

handle	Publisher handle.
timeout_ms	Maximum wait time in milliseconds.

Returns

VLINK_RET_NO_ERROR if a subscriber matched; VLINK_RET_UNEXPECTED_ERROR on timeout; VLINK_RET_INVALID_ERROR on bad handle.

Note

Blocks the calling thread.