VLink  2.3.0
A high-performance communication middleware
c_api.h
浏览该文件的文档.
1 /*
2  * Copyright (C) 2026 by Thun Lu. All rights reserved.
3  * Author: Thun Lu <thun.lu@zohomail.cn>
4  * Repo: https://github.com/thun-res/vlink
5  * _ __ __ _ __
6  * | | / / / / (_) ____ / /__
7  * | | / / / / / / / __ \ / //_/
8  * | |/ / / /___ / / / / / / / ,<
9  * |___/ /_____/ /_/ /_/ /_/ /_/|_|
10  *
11  * Licensed under the Apache License, Version 2.0 (the "License");
12  * you may not use this file except in compliance with the License.
13  * You may obtain a copy of the License at
14  *
15  * http://www.apache.org/licenses/LICENSE-2.0
16  *
17  * Unless required by applicable law or agreed to in writing, software
18  * distributed under the License is distributed on an "AS IS" BASIS,
19  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20  * See the License for the specific language governing permissions and
21  * limitations under the License.
22  */
23 
24 /**
25  * @file c_api.h
26  * @brief Pure C binding over the VLink communication middleware.
27  *
28  * @details
29  * Exposes a stable, language-agnostic C surface across the three VLink
30  * communication models. Every public function wraps a corresponding C++
31  * template instantiation that uses @c vlink::Bytes as its payload type, so the
32  * C ABI never has to leak C++ type information.
33  *
34  * @par Model Mapping
35  *
36  * | Model | C++ class | C handle types |
37  * | ------- | ---------------------------- | ---------------------------------------------------------- |
38  * | Event | @c Publisher / @c Subscriber | @c vlink_publisher_handle_t / @c vlink_subscriber_handle_t |
39  * | Method | @c Server / @c Client | @c vlink_server_handle_t / @c vlink_client_handle_t |
40  * | Field | @c Setter / @c Getter | @c vlink_setter_handle_t / @c vlink_getter_handle_t |
41  *
42  * @par C / C++ Boundary
43  * @code
44  * +-----------------------+ +---------------------------------+
45  * | User C / C++ code | | vlink C++ core templates |
46  * | | | Publisher<Bytes>, Server<...>, |
47  * | vlink_publish(...) | | Setter<Bytes>, Security, ... |
48  * | vlink_invoke(...) | +----------------+----------------+
49  * | vlink_set(...) | ^
50  * +-----------+-----------+ |
51  * | handle.native_handle (opaque) |
52  * v |
53  * +-----------------------+ shallow Bytes::wrap |
54  * | c_api.h boundary +-------------------------+
55  * | (this file) |
56  * +-----------------------+
57  * @endcode
58  *
59  * @par Return Code Family
60  *
61  * | Code | Meaning |
62  * | ------------------------------- | -------------------------------------------------- |
63  * | @c VLINK_RET_NO_ERROR (0) | Success. |
64  * | @c VLINK_RET_UNEXPECTED_ERROR | Condition not met yet (e.g. no subscribers). |
65  * | @c VLINK_RET_INVALID_ERROR | Null pointer / invalid handle / bad arguments. |
66  * | @c VLINK_RET_MEMORY_ERROR | Allocation failure or output buffer too small. |
67  * | @c VLINK_RET_RUNTIME_ERROR | Runtime state error or C++ construction exception. |
68  * | @c VLINK_RET_TRANSFER_ERROR | Publish / listen / invoke operation failed. |
69  * | @c VLINK_RET_UNKNOWN_ERROR (-1) | Unclassified internal error. |
70  *
71  * @par Server Reply Protocol
72  * The @c vlink_server_handle_t::reserved array coordinates the synchronous
73  * request-reply flow. Inside @c vlink_req_callback_t a call to @c vlink_reply()
74  * stores the response. When the callback returns, the relayed reply is sent to
75  * the client. Calling @c vlink_reply() after the callback returns fails with
76  * @c VLINK_RET_RUNTIME_ERROR because no request is in progress.
77  * @code
78  * static void on_request(const uint8_t* data, size_t size, void* user_data) {
79  * vlink_server_handle_t* handle = (vlink_server_handle_t*) user_data;
80  * vlink_reply(handle, resp_data, resp_size);
81  * }
82  *
83  * vlink_schema_info_t schema = {"demo.raw.Text", VLINK_SCHEMA_RAW};
84  * vlink_create_server(url, &schema, &handle, on_request, &handle);
85  * @endcode
86  *
87  * @par Example -- Event (Publisher / Subscriber)
88  * @code
89  * vlink_publisher_handle_t pub;
90  * vlink_schema_info_t schema = {"demo.proto.PointCloud", VLINK_SCHEMA_PROTOBUF};
91  * vlink_create_publisher("dds://my/topic", &schema, &pub);
92  * vlink_wait_for_subscribers(pub, 1000);
93  * vlink_publish(pub, data_buf, data_size);
94  * vlink_destroy_publisher(&pub);
95  *
96  * static void on_message(const uint8_t* data, size_t size, void* user_data) { (void)data; }
97  * vlink_subscriber_handle_t sub;
98  * vlink_create_subscriber("dds://my/topic", &schema, &sub, on_message, NULL);
99  * @endcode
100  *
101  * @par Example -- Method (Server / Client)
102  * @code
103  * vlink_client_handle_t cli;
104  * vlink_schema_info_t schema = {"demo.raw.Echo", VLINK_SCHEMA_RAW};
105  * vlink_create_client("dds://echo", &schema, &cli);
106  * vlink_wait_for_server(cli, 1000);
107  * vlink_invoke(cli, req_buf, req_size, on_response, NULL);
108  * @endcode
109  *
110  * @par Example -- Field (Setter / Getter)
111  * @code
112  * vlink_getter_handle_t getter;
113  * vlink_schema_info_t schema = {"demo.proto.State", VLINK_SCHEMA_PROTOBUF};
114  * vlink_create_getter("dds://state/topic", &schema, &getter, NULL, NULL);
115  *
116  * uint8_t buf[4096];
117  * size_t sz = sizeof(buf);
118  * if (vlink_get(getter, buf, &sz) == VLINK_RET_NO_ERROR) {
119  * // buf[0..sz-1] holds the latest value
120  * }
121  * @endcode
122  *
123  * @note
124  * - Internally the C API uses @c vlink::Publisher<vlink::Bytes> and equivalents.
125  * The @c vlink_schema_info_t aggregate configures @c ser + @c schema atomically.
126  * - Every create/destroy pair must be balanced; handles are not thread-safe for
127  * concurrent create/destroy calls.
128  * - @c vlink_get() copies the latest value into the caller-supplied buffer and
129  * returns @c VLINK_RET_MEMORY_ERROR when the buffer is smaller than the payload.
130  * - @c vlink_publish_by_force() publishes even with no matched subscribers,
131  * useful for transient-local-durability scenarios.
132  */
133 
134 #pragma once
135 
136 // NOLINTBEGIN
137 
138 #undef VLINK_C_API_EXPORT
139 #ifdef VLINK_C_API_LIBRARY_STATIC
140 #define VLINK_C_API_EXPORT
141 #elif defined(_WIN32) || defined(__CYGWIN__)
142 #ifdef VLINK_C_API_LIBRARY
143 #define VLINK_C_API_EXPORT __declspec(dllexport)
144 #else
145 #define VLINK_C_API_EXPORT __declspec(dllimport)
146 #endif
147 #else
148 #define VLINK_C_API_EXPORT __attribute__((visibility("default")))
149 #endif
150 
151 #include <stdbool.h>
152 #include <stddef.h>
153 #include <stdint.h>
154 
155 #ifdef __cplusplus
156 extern "C" {
157 #endif
158 
159 /**
160  * @name Common types and return codes
161  * @{
162  */
163 
164 /**
165  * @brief Return code for VLink C API functions that report @c vlink_ret_t.
166  *
167  * @details
168  * @c VLINK_RET_NO_ERROR is the only success code. Positive values classify
169  * recoverable API states or errors and @c VLINK_RET_UNKNOWN_ERROR (-1) indicates
170  * an unclassified internal error. Always check the symbolic value -- do not
171  * treat every non-negative result as success.
172  */
173 typedef enum {
174  VLINK_RET_UNKNOWN_ERROR = -1, /**< Unclassified or unexpected internal error. */
175  VLINK_RET_NO_ERROR = 0, /**< Operation succeeded. */
176  VLINK_RET_UNEXPECTED_ERROR = 1, /**< Condition not yet met (e.g. no subscribers matched). */
177  VLINK_RET_INVALID_ERROR = 2, /**< Null pointer argument or otherwise invalid handle / arguments. */
178  VLINK_RET_MEMORY_ERROR = 3, /**< Allocation failure or caller-provided buffer is too small. */
179  VLINK_RET_RUNTIME_ERROR = 4, /**< Runtime state error or C++ construction exception. */
180  VLINK_RET_TRANSFER_ERROR = 5, /**< Publish, listen, or invoke operation failed. */
181 } vlink_ret_t;
182 
183 /**
184  * @brief Coarse runtime schema family used for raw C API nodes.
185  *
186  * @details
187  * The numeric values are kept in sync with @c vlink::SchemaType (see
188  * @c include/vlink/impl/types.h), so the C API implementation can cast between
189  * the two enums safely. Always reference the symbolic names -- the underlying
190  * mapping is intentionally opaque at source level.
191  */
192 typedef enum {
193  VLINK_SCHEMA_UNKNOWN = 0, /**< Schema family is not specified. */
194  VLINK_SCHEMA_RAW = 1, /**< Opaque / raw payload. */
195  VLINK_SCHEMA_ZEROCOPY = 2, /**< VLink zero-copy payload. */
196  VLINK_SCHEMA_PROTOBUF = 3, /**< Protocol Buffers payload. */
197  VLINK_SCHEMA_FLATBUFFERS = 4, /**< FlatBuffers payload. */
198  VLINK_SCHEMA_CDR = 5, /**< Native DDS CDR payload. */
200 
201 /**
202  * @brief Bundled runtime schema metadata supplied at node creation.
203  *
204  * @details
205  * Mirrors the C++ pair of @c ser_type + @c schema_type so callers can configure
206  * both atomically before the underlying node is initialised. Both fields must
207  * either be provided together or left unset (@c ser == @c NULL / empty and
208  * @c schema == @c VLINK_SCHEMA_UNKNOWN).
209  */
210 typedef struct {
211  const char* ser; /**< Concrete type name / serialisation identifier, or @c NULL. */
212  vlink_schema_t schema; /**< Coarse schema family. */
214 
215 /** @} */
216 
217 /**
218  * @name Opaque node handles
219  *
220  * @details
221  * Each handle is a small POD struct holding @c native_handle (a pointer to the
222  * underlying heap-allocated C++ instance) plus a @c reserved scratch area used
223  * by the C API for internal state -- security context, request/reply
224  * coordination, etc. Treat every @c reserved slot as opaque: the layout is
225  * private and may change between releases.
226  *
227  * @{
228  */
229 
230 /**
231  * @brief Opaque handle for a @c Publisher node.
232  *
233  * @details
234  * Created by @c vlink_create_publisher() and destroyed by
235  * @c vlink_destroy_publisher(). @c native_handle references a heap-allocated
236  * @c vlink::Publisher<vlink::Bytes>.
237  */
238 typedef struct {
239  void* native_handle; /**< Internal C++ Publisher object pointer. */
240  void* reserved[8]; /**< Reserved for internal state; do not touch.*/
242 
243 /**
244  * @brief Opaque handle for a @c Subscriber node.
245  *
246  * @details
247  * Created by @c vlink_create_subscriber() and destroyed by
248  * @c vlink_destroy_subscriber(). @c native_handle references a heap-allocated
249  * @c vlink::Subscriber<vlink::Bytes>.
250  */
251 typedef struct {
252  void* native_handle; /**< Internal C++ Subscriber object pointer. */
253  void* reserved[8]; /**< Reserved for internal state; do not touch.*/
255 
256 /**
257  * @brief Opaque handle for a @c Server node.
258  *
259  * @details
260  * Created by @c vlink_create_server() and destroyed by
261  * @c vlink_destroy_server(). @c native_handle references a heap-allocated
262  * @c vlink::Server<vlink::Bytes, vlink::Bytes>. The @c reserved array holds the
263  * coordination data used to implement the synchronous request-reply protocol;
264  * its layout is intentionally private.
265  */
266 typedef struct {
267  void* native_handle; /**< Internal C++ Server object pointer. */
268  void* reserved[8]; /**< Internal coordination state; do not touch. */
270 
271 /**
272  * @brief Opaque handle for a @c Client node.
273  *
274  * @details
275  * Created by @c vlink_create_client() and destroyed by
276  * @c vlink_destroy_client(). @c native_handle references a heap-allocated
277  * @c vlink::Client<vlink::Bytes, vlink::Bytes>.
278  */
279 typedef struct {
280  void* native_handle; /**< Internal C++ Client object pointer. */
281  void* reserved[8]; /**< Reserved for internal state; do not touch. */
283 
284 /**
285  * @brief Opaque handle for a @c Setter node.
286  *
287  * @details
288  * Created by @c vlink_create_setter() and destroyed by
289  * @c vlink_destroy_setter(). @c native_handle references a heap-allocated
290  * @c vlink::Setter<vlink::Bytes>.
291  */
292 typedef struct {
293  void* native_handle; /**< Internal C++ Setter object pointer. */
294  void* reserved[8]; /**< Reserved for internal state; do not touch. */
296 
297 /**
298  * @brief Opaque handle for a @c Getter node.
299  *
300  * @details
301  * Created by @c vlink_create_getter() and destroyed by
302  * @c vlink_destroy_getter(). @c native_handle references a heap-allocated
303  * @c vlink::Getter<vlink::Bytes>.
304  */
305 typedef struct {
306  void* native_handle; /**< Internal C++ Getter object pointer. */
307  void* reserved[8]; /**< Reserved for internal state; do not touch. */
309 
310 /** @} */
311 
312 /**
313  * @name Callback typedefs
314  * @{
315  */
316 
317 /**
318  * @brief Callback fired when the connection state of a Publisher or Client changes.
319  *
320  * @param is_connected @c true when at least one peer is matched, @c false otherwise.
321  * @param user_data Opaque pointer supplied at registration time.
322  *
323  * @note May run synchronously during registration or in the backend's delivery
324  * context. Keep the body short and avoid blocking calls.
325  */
326 typedef void (*vlink_connect_callback_t)(const bool is_connected, void* user_data);
327 
328 /**
329  * @brief Callback fired when a Subscriber or Getter receives a message.
330  *
331  * @param data Pointer to the received payload bytes.
332  * @param size Number of bytes available at @p data.
333  * @param user_data Opaque pointer supplied at creation time.
334  *
335  * @note Invoked in the backend's delivery context, which may be synchronous.
336  * The @p data buffer is only
337  * valid for the duration of the callback -- copy if you need to retain it.
338  */
339 typedef void (*vlink_msg_callback_t)(const uint8_t* data, const size_t size, void* user_data);
340 
341 /**
342  * @brief Callback fired when a Server receives an RPC request.
343  *
344  * @details
345  * Invoked synchronously on the Server's dispatch thread while an internal mutex
346  * is held. Call @c vlink_reply() from inside this callback to provide a
347  * non-empty response before it returns. Without a @c vlink_reply() call the
348  * request completes with an empty payload. Calling @c vlink_reply() after the
349  * callback returns fails with @c VLINK_RET_RUNTIME_ERROR because no request is
350  * in progress.
351  *
352  * @param data Pointer to the request payload bytes.
353  * @param size Number of bytes available at @p data.
354  * @param user_data Opaque pointer supplied at creation time.
355  */
356 typedef void (*vlink_req_callback_t)(const uint8_t* data, const size_t size, void* user_data);
357 
358 /**
359  * @brief Callback fired when a Client receives an RPC response.
360  *
361  * @param data Pointer to the response payload bytes; may be @c NULL when
362  * the server did not provide a response.
363  * @param size Number of bytes available at @p data.
364  * @param user_data Opaque pointer supplied at invocation time.
365  */
366 typedef void (*vlink_resp_callback_t)(const uint8_t* data, const size_t size, void* user_data);
367 
368 /** @} */
369 
370 /* Forward declaration of the Security configuration aggregate. The full
371  * definition lives further down with the Security API; this forward declaration
372  * lets the @c vlink_create_secure_*() node creation entry points reference
373  * @c const vlink_security_config_t* before the struct body is in scope. */
376 
377 ////////////////////////////////////////////////////////////////
378 /// Publisher
379 ////////////////////////////////////////////////////////////////
380 
381 /**
382  * @name Event model -- Publisher
383  * @{
384  */
385 
386 /**
387  * @brief Creates a Publisher node and initialises it on the given URL.
388  *
389  * @details
390  * Allocates a @c vlink::Publisher<vlink::Bytes> on the heap and stores its
391  * pointer in @p handle. Supply @p schema_info to configure @c ser + @c schema
392  * before the underlying node is initialised; pass @c NULL to leave both unset.
393  *
394  * @param url VLink topic URL (e.g. @c "dds://my/topic"). Must not be @c NULL.
395  * @param schema_info Optional bundled @c ser + @c schema metadata.
396  * @param handle Output handle. Must not be @c NULL.
397  * @return @c VLINK_RET_NO_ERROR on success; @c VLINK_RET_INVALID_ERROR when
398  * @p url or @p handle is @c NULL, when @p schema_info is only
399  * partially filled, or when @c schema_info->schema is invalid;
400  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
401  * @c VLINK_RET_RUNTIME_ERROR if construction throws.
402  *
403  * @note Caller owns the handle and must release it through
404  * @c vlink_destroy_publisher(). Not thread-safe with concurrent
405  * create/destroy on the same handle.
406  */
407 VLINK_C_API_EXPORT int vlink_create_publisher(const char* url, const vlink_schema_info_t* schema_info,
408  vlink_publisher_handle_t* handle);
409 
410 /**
411  * @brief Destroys a Publisher node and releases every associated resource.
412  *
413  * @param handle Publisher handle to destroy. Must not be @c NULL.
414  * @return @c VLINK_RET_NO_ERROR on success; @c VLINK_RET_INVALID_ERROR
415  * when @p handle or its @c native_handle is @c NULL.
416  *
417  * @note Must not be called concurrently with any other operation on the same
418  * handle.
419  */
421 
422 /**
423  * @brief Checks whether at least one Subscriber has matched this Publisher.
424  *
425  * @param handle Publisher handle.
426  * @return @c VLINK_RET_NO_ERROR if subscribers are present;
427  * @c VLINK_RET_UNEXPECTED_ERROR when none are matched yet;
428  * @c VLINK_RET_INVALID_ERROR on bad handle.
429  *
430  * @note Thread-safe.
431  */
433 
434 /**
435  * @brief Blocks until at least one Subscriber matches or @p timeout_ms expires.
436  *
437  * @param handle Publisher handle.
438  * @param timeout_ms Maximum wait time in milliseconds.
439  * @return @c VLINK_RET_NO_ERROR if a subscriber matched;
440  * @c VLINK_RET_UNEXPECTED_ERROR on timeout;
441  * @c VLINK_RET_INVALID_ERROR on bad handle.
442  *
443  * @note Blocks the calling thread.
444  */
446 
447 /**
448  * @brief Registers a callback fired whenever the Subscriber connection state changes.
449  *
450  * @param handle Publisher handle.
451  * @param connect_callback Callback to invoke on every state change.
452  * @param user_data Opaque pointer forwarded to @p connect_callback.
453  * @return @c VLINK_RET_NO_ERROR on success;
454  * @c VLINK_RET_INVALID_ERROR on bad handle or a @c NULL
455  * @p connect_callback.
456  *
457  * @note The callback may run synchronously during registration when the state is
458  * already known, or later in the backend's delivery context.
459  */
461  const vlink_connect_callback_t connect_callback, void* user_data);
462 
463 /**
464  * @brief Publishes a message to every matched Subscriber.
465  *
466  * @details
467  * The implementation wraps @p data in a shallow-copy @c vlink::Bytes -- zero-copy
468  * when the transport supports it. Returns @c VLINK_RET_TRANSFER_ERROR when no
469  * subscribers are matched and the publisher does not allow forced delivery.
470  *
471  * @param handle Publisher handle.
472  * @param data Payload to publish. Must remain valid until the call returns.
473  * @param size Number of bytes in @p data.
474  * @return @c VLINK_RET_NO_ERROR on success;
475  * @c VLINK_RET_TRANSFER_ERROR when publishing fails;
476  * @c VLINK_RET_INVALID_ERROR on bad handle or
477  * @p data == @c NULL with @p size > 0.
478  *
479  * @note Thread-safe with respect to other publishes on the same handle.
480  */
481 VLINK_C_API_EXPORT int vlink_publish(const vlink_publisher_handle_t handle, const uint8_t* data, const size_t size);
482 
483 /**
484  * @brief Publishes a message even when no Subscribers are matched.
485  *
486  * @details
487  * Identical to @c vlink_publish() but passes @c force=true to the underlying
488  * publisher, bypassing the subscriber-presence check. Useful for
489  * transient-local-durability or late-joining subscriber scenarios.
490  *
491  * @param handle Publisher handle.
492  * @param data Payload to publish.
493  * @param size Number of bytes in @p data.
494  * @return @c VLINK_RET_NO_ERROR on success;
495  * @c VLINK_RET_TRANSFER_ERROR on failure;
496  * @c VLINK_RET_INVALID_ERROR on bad handle or
497  * @p data == @c NULL with @p size > 0.
498  *
499  * @note Same threading guarantees as @c vlink_publish().
500  */
502  const size_t size);
503 
504 /** @} */
505 
506 ////////////////////////////////////////////////////////////////
507 /// Subscriber
508 ////////////////////////////////////////////////////////////////
509 
510 /**
511  * @name Event model -- Subscriber
512  * @{
513  */
514 
515 /**
516  * @brief Creates a Subscriber node, initialises it, and registers the message callback.
517  *
518  * @details
519  * Allocates a @c vlink::Subscriber<vlink::Bytes> and immediately calls
520  * @c listen() with @p msg_callback. The callback runs on the Subscriber's
521  * internal receive thread.
522  *
523  * @param url VLink topic URL. Must not be @c NULL.
524  * @param schema_info Optional bundled @c ser + @c schema metadata.
525  * @param handle Output handle. Must not be @c NULL.
526  * @param msg_callback Message handler. Must not be @c NULL.
527  * @param user_data Opaque pointer forwarded to @p msg_callback.
528  * @return @c VLINK_RET_NO_ERROR on success;
529  * @c VLINK_RET_INVALID_ERROR for @c NULL arguments,
530  * partially-filled @p schema_info, or invalid
531  * @c schema_info->schema;
532  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
533  * @c VLINK_RET_TRANSFER_ERROR if @c listen() fails;
534  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
535  *
536  * @note Caller owns the handle and must release it with
537  * @c vlink_destroy_subscriber().
538  */
539 VLINK_C_API_EXPORT int vlink_create_subscriber(const char* url, const vlink_schema_info_t* schema_info,
541  const vlink_msg_callback_t msg_callback, void* user_data);
542 
543 /**
544  * @brief Atomically creates a Subscriber, installs @c Security, and calls @c listen().
545  *
546  * @details
547  * Builds the @c vlink::Security from @p security_cfg @b before the internal
548  * @c listen() registration completes, so every inbound frame is run through
549  * @c Security::decrypt(). Security configuration is one-shot at creation -- no
550  * separate runtime entry point exists.
551  *
552  * On failure (bad URL/schema/cfg, non-decrypt-capable security state, listen
553  * failure) no resources leak; any internal handle stored before the failure is
554  * cleared.
555  *
556  * @param url VLink subscriber URL. Must not be @c NULL.
557  * @param schema_info Optional bundled @c ser + @c schema metadata.
558  * @param handle Output handle. Must not be @c NULL.
559  * @param msg_callback Message handler. Must not be @c NULL.
560  * @param user_data Opaque pointer forwarded to @p msg_callback.
561  * @param security_cfg Security configuration. Must not be @c NULL. A
562  * zero-initialised configuration uses the built-in default
563  * symmetric slot with replay protection disabled;
564  * otherwise a decrypt-capable slot is required.
565  * @return @c VLINK_RET_NO_ERROR on success;
566  * @c VLINK_RET_INVALID_ERROR on bad arguments (including a
567  * non-decrypt-capable @p security_cfg);
568  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
569  * @c VLINK_RET_TRANSFER_ERROR if @c listen() fails;
570  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
571  *
572  * @note Caller owns the handle and must release it with
573  * @c vlink_destroy_subscriber().
574  */
577  const vlink_msg_callback_t msg_callback, void* user_data,
578  const vlink_security_config_t* security_cfg);
579 
580 /**
581  * @brief Destroys a Subscriber node and releases every associated resource.
582  *
583  * @param handle Subscriber handle to destroy. Must not be @c NULL.
584  * @return @c VLINK_RET_NO_ERROR on success;
585  * @c VLINK_RET_INVALID_ERROR on bad handle.
586  *
587  * @note Must not be called concurrently with any other operation on the same
588  * handle.
589  */
591 
592 /** @} */
593 
594 ////////////////////////////////////////////////////////////////
595 /// Server
596 ////////////////////////////////////////////////////////////////
597 
598 /**
599  * @name Method model -- Server
600  * @{
601  */
602 
603 /**
604  * @brief Creates a Server node, initialises it, and registers the request callback.
605  *
606  * @details
607  * Allocates a @c vlink::Server<vlink::Bytes, vlink::Bytes> and calls @c listen()
608  * with an internal handler that wraps @p req_callback. The internal handler
609  * serialises request/reply state during each invocation. Call @c vlink_reply()
610  * from inside @p req_callback to set a response before the callback returns.
611  *
612  * @param url VLink service URL. Must not be @c NULL.
613  * @param schema_info Optional bundled @c ser + @c schema metadata.
614  * @param handle Output handle. Must not be @c NULL.
615  * @param req_callback Request handler. Must not be @c NULL.
616  * @param user_data Opaque pointer forwarded to @p req_callback.
617  * @return @c VLINK_RET_NO_ERROR on success;
618  * @c VLINK_RET_INVALID_ERROR for @c NULL arguments,
619  * partially-filled @p schema_info, or invalid
620  * @c schema_info->schema;
621  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
622  * @c VLINK_RET_TRANSFER_ERROR if @c listen() fails;
623  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
624  *
625  * @note Caller owns the handle and must release it with @c vlink_destroy_server().
626  */
627 VLINK_C_API_EXPORT int vlink_create_server(const char* url, const vlink_schema_info_t* schema_info,
628  vlink_server_handle_t* handle, const vlink_req_callback_t req_callback,
629  void* user_data);
630 
631 /**
632  * @brief Atomically creates a Server, installs @c Security, and calls @c listen().
633  *
634  * @details
635  * Builds the @c vlink::Security from @p security_cfg @b before the internal
636  * @c listen() registration completes. Inbound requests are decrypted through
637  * @c Security::decrypt(); replies written via @c vlink_reply() are encrypted
638  * through @c Security::encrypt(). Without a @c vlink_reply() call, or with
639  * @c size == @c 0, the request still completes with an empty response so the C
640  * API reply protocol is preserved. When @c security_cfg->advanced.aad_context
641  * is empty the wrapper binds security to @c url|ser|schema; absent
642  * @p schema_info defaults to the C API @c Bytes binding @c url||VLINK_SCHEMA_RAW.
643  * Security configuration is one-shot at creation -- no separate runtime entry
644  * point exists.
645  *
646  * @param url VLink service URL. Must not be @c NULL.
647  * @param schema_info Optional bundled @c ser + @c schema metadata.
648  * @param handle Output handle. Must not be @c NULL.
649  * @param req_callback Request handler. Must not be @c NULL.
650  * @param user_data Opaque pointer forwarded to @p req_callback.
651  * @param security_cfg Security configuration. Must not be @c NULL. A
652  * zero-initialised configuration uses the built-in default
653  * symmetric slot with replay protection disabled;
654  * otherwise both encrypt- and decrypt-capable slots are
655  * required.
656  * @return @c VLINK_RET_NO_ERROR on success;
657  * @c VLINK_RET_INVALID_ERROR on bad arguments;
658  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
659  * @c VLINK_RET_TRANSFER_ERROR if @c listen() fails;
660  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
661  *
662  * @note Caller owns the handle and must release it with @c vlink_destroy_server().
663  */
664 VLINK_C_API_EXPORT int vlink_create_secure_server(const char* url, const vlink_schema_info_t* schema_info,
665  vlink_server_handle_t* handle,
666  const vlink_req_callback_t req_callback, void* user_data,
667  const vlink_security_config_t* security_cfg);
668 
669 /**
670  * @brief Destroys a Server node and frees every internal resource, including the
671  * request/reply coordination state.
672  *
673  * @param handle Server handle to destroy. Must not be @c NULL.
674  * @return @c VLINK_RET_NO_ERROR on success;
675  * @c VLINK_RET_INVALID_ERROR on bad handle.
676  *
677  * @note Must not be called concurrently with any other operation on the same
678  * handle.
679  */
681 
682 /**
683  * @brief Provides the response data for the current in-progress RPC request.
684  *
685  * @details
686  * Must be called from inside @c vlink_req_callback_t while the internal request
687  * context is active. The response is copied into owned internal storage, or
688  * encrypted into owned internal storage for secure servers. A @p size of @c 0
689  * is accepted and produces the protocol's empty response.
690  *
691  * @param handle Server handle. Must not be @c NULL.
692  * @param data Response payload bytes.
693  * @param size Number of bytes in @p data.
694  * @return @c VLINK_RET_NO_ERROR on success;
695  * @c VLINK_RET_INVALID_ERROR on bad handle or
696  * @p data == @c NULL with @p size > 0;
697  * @c VLINK_RET_RUNTIME_ERROR when no pending request is in
698  * progress;
699  * @c VLINK_RET_MEMORY_ERROR if internal allocation fails;
700  * @c VLINK_RET_TRANSFER_ERROR if secure response encryption
701  * fails.
702  *
703  * @note Only valid inside the @c vlink_req_callback_t.
704  */
705 VLINK_C_API_EXPORT int vlink_reply(vlink_server_handle_t* handle, const uint8_t* data, const size_t size);
706 
707 /** @} */
708 
709 ////////////////////////////////////////////////////////////////
710 /// Client
711 ////////////////////////////////////////////////////////////////
712 
713 /**
714  * @name Method model -- Client
715  * @{
716  */
717 
718 /**
719  * @brief Creates a Client node and initialises it on the given URL.
720  *
721  * @param url VLink service URL. Must not be @c NULL.
722  * @param schema_info Optional bundled @c ser + @c schema metadata.
723  * @param handle Output handle. Must not be @c NULL.
724  * @return @c VLINK_RET_NO_ERROR on success;
725  * @c VLINK_RET_INVALID_ERROR for @c NULL @p url / @p handle,
726  * partially-filled @p schema_info, or invalid
727  * @c schema_info->schema;
728  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
729  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
730  *
731  * @note Caller owns the handle and must release it with @c vlink_destroy_client().
732  */
733 VLINK_C_API_EXPORT int vlink_create_client(const char* url, const vlink_schema_info_t* schema_info,
734  vlink_client_handle_t* handle);
735 
736 /**
737  * @brief Destroys a Client node and releases every associated resource.
738  *
739  * @param handle Client handle to destroy. Must not be @c NULL.
740  * @return @c VLINK_RET_NO_ERROR on success;
741  * @c VLINK_RET_INVALID_ERROR on bad handle.
742  *
743  * @note Must not be called concurrently with any other operation on the same
744  * handle.
745  */
747 
748 /**
749  * @brief Checks whether the Client is connected to a Server.
750  *
751  * @param handle Client handle.
752  * @return @c VLINK_RET_NO_ERROR if connected;
753  * @c VLINK_RET_UNEXPECTED_ERROR if not yet connected;
754  * @c VLINK_RET_INVALID_ERROR on bad handle.
755  *
756  * @note Thread-safe.
757  */
759 
760 /**
761  * @brief Blocks until a Server is available or @p timeout_ms expires.
762  *
763  * @param handle Client handle.
764  * @param timeout_ms Maximum wait time in milliseconds.
765  * @return @c VLINK_RET_NO_ERROR if connected;
766  * @c VLINK_RET_UNEXPECTED_ERROR on timeout;
767  * @c VLINK_RET_INVALID_ERROR on bad handle.
768  *
769  * @note Blocks the calling thread.
770  */
771 VLINK_C_API_EXPORT int vlink_wait_for_server(const vlink_client_handle_t handle, const int timeout_ms);
772 
773 /**
774  * @brief Registers a callback fired whenever the Server connection state changes.
775  *
776  * @param handle Client handle.
777  * @param connect_callback Callback to invoke on every state change.
778  * @param user_data Opaque pointer forwarded to @p connect_callback.
779  * @return @c VLINK_RET_NO_ERROR on success;
780  * @c VLINK_RET_INVALID_ERROR on bad handle or a @c NULL
781  * @p connect_callback.
782  *
783  * @note The callback may run synchronously during registration when the state is
784  * already known, or later in the backend's delivery context.
785  */
787  const vlink_connect_callback_t connect_callback, void* user_data);
788 
789 /**
790  * @brief Sends an RPC request and registers a callback for the response.
791  *
792  * @details
793  * Internally invokes @c vlink::Client::invoke() with a shallow-copy @c Bytes
794  * wrapping @p data. @p resp_callback fires in the underlying backend's delivery
795  * context once the Server reply arrives; intra direct mode may invoke it before
796  * this function returns. Pass
797  * @c NULL for @p resp_callback when the response is not needed. Secure clients
798  * treat an empty transport response as the protocol's empty response and do not
799  * route it through @c Security::decrypt().
800  *
801  * @param handle Client handle.
802  * @param data Request payload. Must remain valid until the call returns.
803  * @param size Number of bytes in @p data.
804  * @param resp_callback Callback invoked with the response, or @c NULL.
805  * @param user_data Opaque pointer forwarded to @p resp_callback.
806  * @return @c VLINK_RET_NO_ERROR on success;
807  * @c VLINK_RET_TRANSFER_ERROR if encryption or invoke
808  * fails;
809  * @c VLINK_RET_INVALID_ERROR on bad handle or
810  * @p data == @c NULL with @p size > 0.
811  *
812  * @note Thread-safe. The @p resp_callback may fire on a transport-managed
813  * thread.
814  */
815 VLINK_C_API_EXPORT int vlink_invoke(const vlink_client_handle_t handle, const uint8_t* data, const size_t size,
816  const vlink_resp_callback_t resp_callback, void* user_data);
817 
818 /** @} */
819 
820 ////////////////////////////////////////////////////////////////
821 /// Setter
822 ////////////////////////////////////////////////////////////////
823 
824 /**
825  * @name Field model -- Setter
826  * @{
827  */
828 
829 /**
830  * @brief Creates a Setter node and initialises it on the given URL.
831  *
832  * @param url VLink field URL. Must not be @c NULL.
833  * @param schema_info Optional bundled @c ser + @c schema metadata.
834  * @param handle Output handle. Must not be @c NULL.
835  * @return @c VLINK_RET_NO_ERROR on success;
836  * @c VLINK_RET_INVALID_ERROR for @c NULL @p url / @p handle,
837  * partially-filled @p schema_info, or invalid
838  * @c schema_info->schema;
839  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
840  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
841  *
842  * @note Caller owns the handle and must release it with @c vlink_destroy_setter().
843  */
844 VLINK_C_API_EXPORT int vlink_create_setter(const char* url, const vlink_schema_info_t* schema_info,
845  vlink_setter_handle_t* handle);
846 
847 /**
848  * @brief Destroys a Setter node and releases every associated resource.
849  *
850  * @param handle Setter handle to destroy. Must not be @c NULL.
851  * @return @c VLINK_RET_NO_ERROR on success;
852  * @c VLINK_RET_INVALID_ERROR on bad handle.
853  *
854  * @note Must not be called concurrently with any other operation on the same
855  * handle.
856  */
858 
859 /**
860  * @brief Publishes the latest field value.
861  *
862  * @details
863  * The new value overwrites the previous one held by every matched Getter. The
864  * input buffer is only read during the @c vlink_set() call. The underlying
865  * @c Setter<vlink::Bytes> keeps its latest-value cache as an owned @c Bytes
866  * copy, so callers may reuse or release @p data once the function returns.
867  *
868  * @param handle Setter handle.
869  * @param data New field value bytes. Must remain valid for the call.
870  * @param size Number of bytes in @p data.
871  * @return @c VLINK_RET_NO_ERROR on success;
872  * @c VLINK_RET_TRANSFER_ERROR if secure encryption fails;
873  * @c VLINK_RET_INVALID_ERROR on bad handle or
874  * @p data == @c NULL with @p size > 0.
875  *
876  * @note Thread-safe with respect to other @c vlink_set() calls on the same handle.
877  */
878 VLINK_C_API_EXPORT int vlink_set(const vlink_setter_handle_t handle, const uint8_t* data, const size_t size);
879 
880 /** @} */
881 
882 ////////////////////////////////////////////////////////////////
883 /// Getter
884 ////////////////////////////////////////////////////////////////
885 
886 /**
887  * @name Field model -- Getter
888  * @{
889  */
890 
891 /**
892  * @brief Creates a Getter node, initialises it, and optionally registers a change callback.
893  *
894  * @details
895  * Allocates a @c vlink::Getter<vlink::Bytes>. When @p msg_callback is non-NULL,
896  * @c listen() is called and the callback fires on every value update. When
897  * @p msg_callback is @c NULL the Getter operates in polling mode -- use
898  * @c vlink_get() to retrieve the latest value.
899  *
900  * @param url VLink field URL. Must not be @c NULL.
901  * @param schema_info Optional bundled @c ser + @c schema metadata.
902  * @param handle Output handle. Must not be @c NULL.
903  * @param msg_callback Push-mode callback, or @c NULL for poll mode.
904  * @param user_data Opaque pointer forwarded to @p msg_callback.
905  * @return @c VLINK_RET_NO_ERROR on success;
906  * @c VLINK_RET_INVALID_ERROR for @c NULL @p url / @p handle,
907  * partially-filled @p schema_info, or invalid
908  * @c schema_info->schema;
909  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
910  * @c VLINK_RET_TRANSFER_ERROR if @c listen() fails;
911  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
912  *
913  * @note Caller owns the handle and must release it with @c vlink_destroy_getter().
914  */
915 VLINK_C_API_EXPORT int vlink_create_getter(const char* url, const vlink_schema_info_t* schema_info,
916  vlink_getter_handle_t* handle, const vlink_msg_callback_t msg_callback,
917  void* user_data);
918 
919 /**
920  * @brief Atomically creates a Getter, installs @c Security, and calls @c listen().
921  *
922  * @details
923  * Builds the @c vlink::Security from @p security_cfg @b before the internal
924  * push-mode @c listen() registration completes. Polling-mode Getters
925  * (@p msg_callback == @c NULL) see the attached @c Security from the very first
926  * @c vlink_get() call. A secure polling Getter caches the last authenticated
927  * ciphertext/plaintext pair internally so repeated @c vlink_get() calls for the
928  * same latest field value return the cached plaintext without tripping replay
929  * protection. Fresh inbound frames still flow through @c Security::decrypt().
930  * Push-mode Getters authenticate before invoking the callback; concurrent
931  * @c vlink_get() reads that same authenticated value. A different ciphertext
932  * that fails authentication makes the value unavailable until the next valid update.
933  * An existing Field value may invoke @p msg_callback before creation returns;
934  * prepare @p user_data before calling this function.
935  * Security configuration is one-shot at creation -- no separate runtime entry
936  * point exists.
937  *
938  * @param url VLink field URL. Must not be @c NULL.
939  * @param schema_info Optional bundled @c ser + @c schema metadata.
940  * @param handle Output handle. Must not be @c NULL.
941  * @param msg_callback Push-mode callback, or @c NULL for poll mode.
942  * @param user_data Opaque pointer forwarded to @p msg_callback.
943  * @param security_cfg Security configuration. Must not be @c NULL. A
944  * zero-initialised configuration uses the built-in default
945  * symmetric slot with replay protection disabled;
946  * otherwise a decrypt-capable slot is required.
947  * @return @c VLINK_RET_NO_ERROR on success;
948  * @c VLINK_RET_INVALID_ERROR on bad arguments;
949  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
950  * @c VLINK_RET_TRANSFER_ERROR if @c listen() fails;
951  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
952  *
953  * @note Caller owns the handle and must release it with @c vlink_destroy_getter().
954  */
955 VLINK_C_API_EXPORT int vlink_create_secure_getter(const char* url, const vlink_schema_info_t* schema_info,
956  vlink_getter_handle_t* handle,
957  const vlink_msg_callback_t msg_callback, void* user_data,
958  const vlink_security_config_t* security_cfg);
959 
960 /**
961  * @brief Destroys a Getter node and releases every associated resource.
962  *
963  * @param handle Getter handle to destroy. Must not be @c NULL.
964  * @return @c VLINK_RET_NO_ERROR on success;
965  * @c VLINK_RET_INVALID_ERROR on bad handle.
966  *
967  * @note Must not be called concurrently with any other operation on the same
968  * handle.
969  */
971 
972 /**
973  * @brief Retrieves the latest field value into a caller-provided buffer.
974  *
975  * @details
976  * Copies the current cached value into @p data. On entry @c *size must hold
977  * the buffer capacity; on success it is updated to the actual byte count. When
978  * the buffer is too small the function returns @c VLINK_RET_MEMORY_ERROR and
979  * writes the required byte count into @c *size so the caller can allocate and
980  * retry. @p data is left unmodified in the error case.
981  *
982  * @param handle Getter handle.
983  * @param data Output buffer. Must not be @c NULL.
984  * @param size In/out: buffer capacity on entry; actual or required size on
985  * exit. Must not be @c NULL.
986  * @return @c VLINK_RET_NO_ERROR on success;
987  * @c VLINK_RET_TRANSFER_ERROR if no value is available yet;
988  * @c VLINK_RET_MEMORY_ERROR if @c *size is too small (required
989  * size written back);
990  * @c VLINK_RET_INVALID_ERROR on bad arguments.
991  *
992  * @note Thread-safe.
993  */
994 VLINK_C_API_EXPORT int vlink_get(const vlink_getter_handle_t handle, uint8_t* data, size_t* size);
995 
996 /** @} */
997 
998 ////////////////////////////////////////////////////////////////
999 /// Security
1000 ////////////////////////////////////////////////////////////////
1001 
1002 /**
1003  * @name Security -- standalone Security handle and node-side helpers
1004  * @{
1005  */
1006 
1007 /**
1008  * @brief Opaque handle for a standalone @c Security instance.
1009  *
1010  * @details
1011  * Wraps a heap-allocated @c vlink::Security that performs authenticated,
1012  * message-level encryption. Construct via @c vlink_security_create() and
1013  * destroy via @c vlink_security_destroy(). The same handle drives both
1014  * @c vlink_security_encrypt() and @c vlink_security_decrypt() as long as the
1015  * configuration supplies the matching key material for each direction.
1016  */
1017 typedef struct vlink_security* vlink_security_handle_t;
1018 
1019 /**
1020  * @brief Optional user-provided encrypt/decrypt callback for @c vlink_security_config_t.
1021  *
1022  * @details
1023  * Installing both @c encrypt_callback and @c decrypt_callback overrides the
1024  * built-in AEAD path entirely. Implementations must allocate @c *out with
1025  * @c malloc (or another allocator compatible with @c free) and write the byte
1026  * count into @c *out_size. The C API releases the buffer with @c free() after
1027  * copying its contents into the destination supplied to
1028  * @c vlink_security_encrypt() / @c vlink_security_decrypt(). Custom
1029  * encrypt/decrypt callbacks attached to the same security handle are serialised
1030  * by VLink; callbacks shared across handles must protect their own shared state.
1031  *
1032  * @param in Plaintext (encrypt) or ciphertext (decrypt) input pointer.
1033  * @param in_size Number of bytes available at @p in.
1034  * @param out Output parameter receiving a freshly allocated buffer.
1035  * @param out_size Output parameter receiving the byte count of @p out.
1036  * @param user Opaque pointer supplied via @c callback_user_data.
1037  * @return @c 0 on success, non-zero on failure.
1038  *
1039  * @note On Windows the buffer returned through @p out is released inside the
1040  * vlink shared library using its own CRT @c free(). The callback
1041  * implementation MUST therefore allocate @p *out with the matching CRT
1042  * (e.g. the @c msvcrt / UCRT @c malloc linked into the vlink DLL).
1043  * Mixing CRTs across DLL boundaries leads to heap corruption. When in
1044  * doubt, build the callback host with the same toolchain/runtime as the
1045  * vlink shared library, or expose your own @c free helper through
1046  * @c callback_user_data.
1047  */
1048 typedef int (*vlink_security_callback_t)(const uint8_t* in, size_t in_size, uint8_t** out, size_t* out_size,
1049  void* user);
1050 
1051 /**
1052  * @brief Low-frequency security options: AAD, replay protection, and signing keys.
1053  */
1054 typedef struct {
1055  const char* aad_context; /**< AEAD context binding (<=65535 bytes), or @c NULL. */
1056  uint32_t replay_window; /**< Replay window size; @c 0 disables replay checks. */
1057  const char* signing_key_pem; /**< Local RSA private key (PEM) for RSA-PSS signing, or @c NULL. */
1058  const char* verify_key_pem; /**< Peer RSA public key (PEM) for RSA-PSS verification, or @c NULL. */
1060 
1061 /**
1062  * @brief Configuration aggregate for @c vlink_security_create() and the
1063  * @c vlink_create_secure_*() entry points.
1064  *
1065  * @details
1066  * Each field maps onto the field of the same name on @c vlink::Security::Config.
1067  * String fields are null-terminated; @c NULL or empty strings disable the
1068  * matching explicit field. When every explicit cryptographic field is empty,
1069  * the configuration maps to the built-in default symmetric slot, provided
1070  * built-in algorithms are enabled. A zero-initialised aggregate leaves
1071  * @c advanced.replay_window at @c 0, so replay checks are disabled until the
1072  * caller sets the field or calls @c vlink_security_config_init().
1073  * @c pbkdf2_salt is a raw byte buffer of @c pbkdf2_salt_size bytes; pass
1074  * @c NULL / @c 0 to leave it empty. Setting @c pbkdf2_iterations to @c 0
1075  * selects the default (200000).
1076  *
1077  * @par Mode Selection
1078  * - When both @c encrypt_callback and @c decrypt_callback are non-NULL the
1079  * custom-callback path overrides every other slot.
1080  * - When @c public_key_pem / @c private_key_pem are installed the RSA hybrid
1081  * path drives outbound / inbound messages.
1082  * - Otherwise the symmetric path is used with a key derived from @c key,
1083  * @c passphrase + @c pbkdf2_salt, or the built-in default.
1084  *
1085  * @note @c key / @c passphrase are the symmetric key sources. @c advanced
1086  * holds low-frequency options such as AAD, replay protection, and signing.
1087  */
1089  const char* key; /**< Raw symmetric seed (SHA-256 truncated), or @c NULL. */
1090  const char* passphrase; /**< Low-entropy passphrase fed into PBKDF2-HMAC-SHA256, or @c NULL.*/
1091  const uint8_t* pbkdf2_salt; /**< PBKDF2 salt (>=16 bytes), or @c NULL. */
1092  size_t pbkdf2_salt_size; /**< Byte count of @c pbkdf2_salt. */
1093  uint32_t pbkdf2_iterations; /**< PBKDF2 iteration count; @c 0 means default (200000). */
1094  const char* public_key_pem; /**< Peer RSA public key (PEM) for outbound encryption, or @c NULL. */
1095  const char* private_key_pem; /**< Local RSA private key (PEM) for inbound decryption, or @c NULL.*/
1096  vlink_security_callback_t encrypt_callback; /**< Custom encrypt callback, or @c NULL. */
1097  vlink_security_callback_t decrypt_callback; /**< Custom decrypt callback, or @c NULL. */
1098  void* callback_user_data; /**< Opaque pointer forwarded to both callbacks. */
1099  vlink_security_advanced_config_t advanced; /**< Low-frequency security options. */
1100 };
1101 
1102 /**
1103  * @brief Zero-initialises @p cfg and applies the C API default PBKDF2 / replay settings.
1104  *
1105  * @details
1106  * Convenience initialiser that avoids relying on @c {0} aggregate initialisation
1107  * in client code. Once it returns, every string pointer is @c NULL, the salt
1108  * buffer is empty, both callbacks and @c callback_user_data are @c NULL,
1109  * @c pbkdf2_iterations equals 200000, and @c advanced.replay_window equals 4096.
1110  * Set @c advanced.replay_window back to @c 0 to disable replay checks
1111  * explicitly. Safe to call on a stack variable before populating fields.
1112  * Passing the initialised configuration to a Security constructor uses the
1113  * built-in default symmetric slot when built-in algorithms are enabled.
1114  *
1115  * @par Example
1116  * @code
1117  * vlink_security_config_t cfg;
1118  * vlink_security_config_init(&cfg);
1119  * cfg.passphrase = "correct horse battery staple";
1120  * cfg.pbkdf2_salt = my_salt_bytes;
1121  * cfg.pbkdf2_salt_size = my_salt_size;
1122  * @endcode
1123  *
1124  * @param cfg Configuration aggregate to initialise. No-op when @p cfg is @c NULL.
1125  *
1126  * @note Safe to call on a freshly declared stack variable.
1127  */
1129 
1130 /**
1131  * @brief Creates a standalone @c Security instance from @p cfg.
1132  *
1133  * @details
1134  * Allocates a @c vlink::Security on the heap. When @p cfg is @c NULL the call
1135  * returns @c NULL and logs a warning. A zero-initialised @p cfg uses the
1136  * built-in default symmetric slot when built-in algorithms are enabled, but it
1137  * leaves @c advanced.replay_window at @c 0 so replay protection is disabled.
1138  * Call @c vlink_security_config_init() to obtain the C API default PBKDF2/replay
1139  * settings. Invalid PEM fields or weak RSA keys are logged via @c VLOG_W and
1140  * the offending slot is left empty as long as at least one other slot validated.
1141  *
1142  * @par Example
1143  * @code
1144  * vlink_security_config_t cfg;
1145  * vlink_security_config_init(&cfg);
1146  * cfg.passphrase = "correct horse battery staple";
1147  * cfg.pbkdf2_salt = my_salt_bytes;
1148  * cfg.pbkdf2_salt_size = my_salt_size;
1149  *
1150  * vlink_security_handle_t sec = vlink_security_create(&cfg);
1151  *
1152  * uint8_t* cipher = NULL;
1153  * size_t cipher_size = 0;
1154  * vlink_security_encrypt(sec, plain, plain_size, &cipher, &cipher_size);
1155  * vlink_security_free_buffer(cipher);
1156  *
1157  * vlink_security_destroy(sec);
1158  * @endcode
1159  *
1160  * @param cfg Configuration aggregate. A zero-initialised aggregate uses the
1161  * built-in default symmetric slot with replay protection disabled;
1162  * otherwise provide a callback pair, symmetric key/passphrase, or
1163  * RSA PEM.
1164  * @return New @c vlink_security_handle_t handle; @c NULL on @c NULL @p cfg,
1165  * on a configuration with no usable cryptographic slot after
1166  * validation, on allocation failure, or on a C++ construction
1167  * exception.
1168  *
1169  * @note Caller owns the handle and must release it via @c vlink_security_destroy().
1170  */
1172 
1173 /**
1174  * @brief Destroys a standalone @c Security instance.
1175  *
1176  * @details
1177  * Safe to call with @c NULL @p sec (no-op). Symmetric key material is zeroised
1178  * in place inside the @c vlink::Security destructor before the buffer is freed.
1179  *
1180  * @param sec Handle returned by @c vlink_security_create(), or @c NULL.
1181  */
1183 
1184 /**
1185  * @brief Encrypts a plaintext buffer using the active mode configured on @p sec.
1186  *
1187  * @details
1188  * The ciphertext lands in a freshly allocated buffer that the caller owns;
1189  * release it with @c vlink_security_free_buffer(). Following the underlying
1190  * @c Security::encrypt() contract, empty inputs (@c in == @c NULL or
1191  * @c in_size == @c 0) are rejected with @c VLINK_RET_INVALID_ERROR.
1192  *
1193  * @param sec Security handle.
1194  * @param in Plaintext input bytes.
1195  * @param in_size Number of bytes available at @p in.
1196  * @param out Output pointer receiving the allocated ciphertext buffer.
1197  * Must not be @c NULL.
1198  * @param out_size Output pointer receiving the ciphertext byte count. Must
1199  * not be @c NULL.
1200  * @return @c VLINK_RET_NO_ERROR on success;
1201  * @c VLINK_RET_INVALID_ERROR on bad arguments;
1202  * @c VLINK_RET_MEMORY_ERROR if output allocation fails;
1203  * @c VLINK_RET_TRANSFER_ERROR if @c Security::encrypt() fails.
1204  *
1205  * @note Caller owns @c *out and must release it via @c vlink_security_free_buffer().
1206  */
1207 VLINK_C_API_EXPORT int vlink_security_encrypt(vlink_security_handle_t sec, const uint8_t* in, const size_t in_size,
1208  uint8_t** out, size_t* out_size);
1209 
1210 /**
1211  * @brief Decrypts a ciphertext buffer using the active mode configured on @p sec.
1212  *
1213  * @details
1214  * The plaintext lands in a freshly allocated buffer that the caller owns;
1215  * release it with @c vlink_security_free_buffer(). Empty inputs are rejected
1216  * with @c VLINK_RET_INVALID_ERROR (a valid built-in ciphertext carries an
1217  * envelope, tag, and at least one ciphertext byte). Authentication failures --
1218  * tampered ciphertext, wrong key, invalid signature, or replay -- are reported
1219  * as @c VLINK_RET_TRANSFER_ERROR.
1220  *
1221  * @param sec Security handle.
1222  * @param in Ciphertext input bytes.
1223  * @param in_size Number of bytes available at @p in.
1224  * @param out Output pointer receiving the allocated plaintext buffer.
1225  * Must not be @c NULL.
1226  * @param out_size Output pointer receiving the plaintext byte count. Must not
1227  * be @c NULL.
1228  * @return @c VLINK_RET_NO_ERROR on success;
1229  * @c VLINK_RET_INVALID_ERROR on bad arguments;
1230  * @c VLINK_RET_MEMORY_ERROR if output allocation fails;
1231  * @c VLINK_RET_TRANSFER_ERROR if @c Security::decrypt() fails.
1232  *
1233  * @note Caller owns @c *out and must release it via @c vlink_security_free_buffer().
1234  */
1235 VLINK_C_API_EXPORT int vlink_security_decrypt(vlink_security_handle_t sec, const uint8_t* in, const size_t in_size,
1236  uint8_t** out, size_t* out_size);
1237 
1238 /**
1239  * @brief Releases a buffer returned by @c vlink_security_encrypt() or
1240  * @c vlink_security_decrypt().
1241  *
1242  * @details
1243  * Safe to call with @c NULL @p buf (no-op). Buffers obtained from any other
1244  * source must not be freed through this function.
1245  *
1246  * @param buf Buffer pointer previously written by an encrypt/decrypt call.
1247  */
1249 
1250 /**
1251  * @brief Atomically creates a Publisher and installs @c Security.
1252  *
1253  * @details
1254  * Builds the @c vlink::Security from @p security_cfg @b before @c init() returns,
1255  * so the encrypt path is wired the first time @c vlink_publish() is called.
1256  * Security configuration is one-shot at creation -- no separate
1257  * @c enable_security() entry point exists.
1258  *
1259  * @param url VLink topic URL. Must not be @c NULL.
1260  * @param schema_info Optional bundled @c ser + @c schema metadata.
1261  * @param handle Output handle. Must not be @c NULL.
1262  * @param security_cfg Security configuration. Must not be @c NULL. A
1263  * zero-initialised configuration uses the built-in default
1264  * symmetric slot with replay protection disabled;
1265  * otherwise an encrypt-capable slot is required.
1266  * @return @c VLINK_RET_NO_ERROR on success;
1267  * @c VLINK_RET_INVALID_ERROR on bad arguments (including a
1268  * non-encrypt-capable @p security_cfg);
1269  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
1270  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
1271  *
1272  * @note Caller owns the handle and must release it with @c vlink_destroy_publisher().
1273  */
1275  vlink_publisher_handle_t* handle,
1276  const vlink_security_config_t* security_cfg);
1277 
1278 /**
1279  * @brief Atomically creates a Client and installs @c Security.
1280  *
1281  * @details
1282  * Builds the @c vlink::Security from @p security_cfg @b before @c init() returns,
1283  * so outbound requests through @c vlink_invoke() are encrypted from the very
1284  * first call and inbound responses are decrypted before @c vlink_resp_callback_t
1285  * fires.
1286  *
1287  * @param url VLink service URL. Must not be @c NULL.
1288  * @param schema_info Optional bundled @c ser + @c schema metadata.
1289  * @param handle Output handle. Must not be @c NULL.
1290  * @param security_cfg Security configuration. Must not be @c NULL. A
1291  * zero-initialised configuration uses the built-in default
1292  * symmetric slot with replay protection disabled;
1293  * otherwise both encrypt- and decrypt-capable slots are
1294  * required.
1295  * @return @c VLINK_RET_NO_ERROR on success;
1296  * @c VLINK_RET_INVALID_ERROR on bad arguments;
1297  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
1298  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
1299  *
1300  * @note Caller owns the handle and must release it with @c vlink_destroy_client().
1301  */
1303  vlink_client_handle_t* handle,
1304  const vlink_security_config_t* security_cfg);
1305 
1306 /**
1307  * @brief Atomically creates a Setter and installs @c Security.
1308  *
1309  * @details
1310  * Builds the @c vlink::Security from @p security_cfg @b before @c init() returns,
1311  * so the encrypt path is wired the first time @c vlink_set() is called. The
1312  * Setter's normal latest-value cache owns the encrypted @c Bytes payload, so
1313  * late-joining Getters receive the current value without depending on the
1314  * caller's input buffer.
1315  *
1316  * @param url VLink field URL. Must not be @c NULL.
1317  * @param schema_info Optional bundled @c ser + @c schema metadata.
1318  * @param handle Output handle. Must not be @c NULL.
1319  * @param security_cfg Security configuration. Must not be @c NULL. A
1320  * zero-initialised configuration uses the built-in default
1321  * symmetric slot with replay protection disabled;
1322  * otherwise an encrypt-capable slot is required.
1323  * @return @c VLINK_RET_NO_ERROR on success;
1324  * @c VLINK_RET_INVALID_ERROR on bad arguments;
1325  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
1326  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
1327  *
1328  * @note Caller owns the handle and must release it with @c vlink_destroy_setter().
1329  */
1331  vlink_setter_handle_t* handle,
1332  const vlink_security_config_t* security_cfg);
1333 
1334 /** @} */
1335 
1336 /**
1337  * @name Transport-layer TLS (SSL options)
1338  * @{
1339  */
1340 
1341 /**
1342  * @brief Transport-layer TLS configuration aggregate.
1343  *
1344  * @details
1345  * Mirrors @c vlink::SslOptions. Populated by the caller and passed to the
1346  * @c vlink_create_*_with_ssl_options() entry points. String fields are
1347  * null-terminated; @c NULL or empty strings disable the matching slot.
1348  * @c verify_peer uses C semantics -- non-zero enables peer-certificate
1349  * verification; @c 0 disables it where supported. RTI Connext DDS logs a warning
1350  * and retains verification. Transport backends consider TLS enabled once at least
1351  * @c ca_file or @c cert_file is non-empty.
1352  *
1353  * @note This is the transport-layer (channel) TLS configuration. For
1354  * application-layer per-message AEAD encryption see
1355  * @c vlink_security_config_t.
1356  */
1357 typedef struct {
1358  int verify_peer; /**< Non-zero = verify (default); @c 0 = skip where supported. */
1359  const char* ca_file; /**< CA certificate file path (PEM), or @c NULL. */
1360  const char* cert_file; /**< Client certificate file path (PEM), or @c NULL. */
1361  const char* key_file; /**< Client private key file path (PEM), or @c NULL. */
1362  const char* key_password; /**< Passphrase for the encrypted private key, or @c NULL. */
1363  const char* server_name; /**< SNI server name override, or @c NULL. */
1364  const char* ciphers; /**< Cipher suite string (OpenSSL format), or @c NULL. */
1366 
1367 /**
1368  * @brief Zero-initialises @p opt and applies the canonical TLS defaults.
1369  *
1370  * @details
1371  * After the call every string pointer is @c NULL and @c verify_peer equals @c 1
1372  * (matching @c vlink::SslOptions defaults). Safe to call on a stack variable
1373  * before populating the fields you actually need.
1374  *
1375  * @par Example
1376  * @code
1377  * vlink_ssl_options_t opt;
1378  * vlink_ssl_options_init(&opt);
1379  * opt.ca_file = "/etc/certs/ca.pem";
1380  * opt.cert_file = "/etc/certs/client.pem";
1381  * opt.key_file = "/etc/certs/client-key.pem";
1382  * vlink_create_publisher_with_ssl_options("mqtt://sensor/data", &schema, &pub, &opt);
1383  * @endcode
1384  *
1385  * @param opt Options aggregate to initialise. No-op when @p opt is @c NULL.
1386  */
1388 
1389 /**
1390  * @brief Creates a Publisher and applies TLS options before transport initialisation.
1391  *
1392  * @param url VLink topic URL. Must not be @c NULL.
1393  * @param schema_info Optional bundled @c ser + @c schema metadata.
1394  * @param handle Output handle. Must not be @c NULL.
1395  * @param opt TLS options. Must not be @c NULL.
1396  * @return @c VLINK_RET_NO_ERROR on success;
1397  * @c VLINK_RET_INVALID_ERROR on bad arguments including
1398  * @p opt == @c NULL;
1399  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
1400  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
1401  *
1402  * @note Caller owns the handle and must release it with @c vlink_destroy_publisher().
1403  */
1405  vlink_publisher_handle_t* handle,
1406  const vlink_ssl_options_t* opt);
1407 
1408 /**
1409  * @brief Creates a Subscriber and applies TLS options before transport initialisation.
1410  *
1411  * @param url VLink topic URL. Must not be @c NULL.
1412  * @param schema_info Optional bundled @c ser + @c schema metadata.
1413  * @param handle Output handle. Must not be @c NULL.
1414  * @param msg_callback Message handler. Must not be @c NULL.
1415  * @param user_data Opaque pointer forwarded to @p msg_callback.
1416  * @param opt TLS options. Must not be @c NULL.
1417  * @return @c VLINK_RET_NO_ERROR on success;
1418  * @c VLINK_RET_INVALID_ERROR on bad arguments including
1419  * @p opt == @c NULL;
1420  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
1421  * @c VLINK_RET_TRANSFER_ERROR if @c listen() fails;
1422  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
1423  *
1424  * @note Caller owns the handle and must release it with @c vlink_destroy_subscriber().
1425  */
1427  vlink_subscriber_handle_t* handle,
1428  const vlink_msg_callback_t msg_callback,
1429  void* user_data, const vlink_ssl_options_t* opt);
1430 
1431 /**
1432  * @brief Creates a Server and applies TLS options before transport initialisation.
1433  *
1434  * @param url VLink service URL. Must not be @c NULL.
1435  * @param schema_info Optional bundled @c ser + @c schema metadata.
1436  * @param handle Output handle. Must not be @c NULL.
1437  * @param req_callback Request handler. Must not be @c NULL.
1438  * @param user_data Opaque pointer forwarded to @p req_callback.
1439  * @param opt TLS options. Must not be @c NULL.
1440  * @return @c VLINK_RET_NO_ERROR on success;
1441  * @c VLINK_RET_INVALID_ERROR on bad arguments including
1442  * @p opt == @c NULL;
1443  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
1444  * @c VLINK_RET_TRANSFER_ERROR if @c listen() fails;
1445  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
1446  *
1447  * @note Caller owns the handle and must release it with @c vlink_destroy_server().
1448  */
1450  vlink_server_handle_t* handle,
1451  const vlink_req_callback_t req_callback, void* user_data,
1452  const vlink_ssl_options_t* opt);
1453 
1454 /**
1455  * @brief Creates a Client and applies TLS options before transport initialisation.
1456  *
1457  * @param url VLink service URL. Must not be @c NULL.
1458  * @param schema_info Optional bundled @c ser + @c schema metadata.
1459  * @param handle Output handle. Must not be @c NULL.
1460  * @param opt TLS options. Must not be @c NULL.
1461  * @return @c VLINK_RET_NO_ERROR on success;
1462  * @c VLINK_RET_INVALID_ERROR on bad arguments including
1463  * @p opt == @c NULL;
1464  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
1465  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
1466  *
1467  * @note Caller owns the handle and must release it with @c vlink_destroy_client().
1468  */
1470  vlink_client_handle_t* handle,
1471  const vlink_ssl_options_t* opt);
1472 
1473 /**
1474  * @brief Creates a Setter and applies TLS options before transport initialisation.
1475  *
1476  * @param url VLink field URL. Must not be @c NULL.
1477  * @param schema_info Optional bundled @c ser + @c schema metadata.
1478  * @param handle Output handle. Must not be @c NULL.
1479  * @param opt TLS options. Must not be @c NULL.
1480  * @return @c VLINK_RET_NO_ERROR on success;
1481  * @c VLINK_RET_INVALID_ERROR on bad arguments including
1482  * @p opt == @c NULL;
1483  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
1484  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
1485  *
1486  * @note Caller owns the handle and must release it with @c vlink_destroy_setter().
1487  */
1489  vlink_setter_handle_t* handle,
1490  const vlink_ssl_options_t* opt);
1491 
1492 /**
1493  * @brief Creates a Getter and applies TLS options before transport initialisation.
1494  *
1495  * @param url VLink field URL. Must not be @c NULL.
1496  * @param schema_info Optional bundled @c ser + @c schema metadata.
1497  * @param handle Output handle. Must not be @c NULL.
1498  * @param msg_callback Push-mode callback, or @c NULL for poll mode.
1499  * @param user_data Opaque pointer forwarded to @p msg_callback.
1500  * @param opt TLS options. Must not be @c NULL.
1501  * @return @c VLINK_RET_NO_ERROR on success;
1502  * @c VLINK_RET_INVALID_ERROR on bad arguments including
1503  * @p opt == @c NULL;
1504  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
1505  * @c VLINK_RET_TRANSFER_ERROR if @c listen() fails;
1506  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
1507  *
1508  * @note Caller owns the handle and must release it with @c vlink_destroy_getter().
1509  */
1511  vlink_getter_handle_t* handle,
1512  const vlink_msg_callback_t msg_callback, void* user_data,
1513  const vlink_ssl_options_t* opt);
1514 
1515 /**
1516  * @brief Creates a secure Publisher and applies TLS options before transport initialisation.
1517  *
1518  * @param url VLink topic URL. Must not be @c NULL.
1519  * @param schema_info Optional bundled @c ser + @c schema metadata.
1520  * @param handle Output handle. Must not be @c NULL.
1521  * @param security_cfg Security configuration. Must not be @c NULL.
1522  * @param opt TLS options. Must not be @c NULL.
1523  * @return @c VLINK_RET_NO_ERROR on success;
1524  * @c VLINK_RET_INVALID_ERROR on bad arguments including
1525  * @p security_cfg == @c NULL or @p opt == @c NULL;
1526  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
1527  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
1528  *
1529  * @note Caller owns the handle and must release it with @c vlink_destroy_publisher().
1530  */
1532  const vlink_schema_info_t* schema_info,
1533  vlink_publisher_handle_t* handle,
1534  const vlink_security_config_t* security_cfg,
1535  const vlink_ssl_options_t* opt);
1536 
1537 /**
1538  * @brief Creates a secure Subscriber and applies TLS options before transport initialisation.
1539  *
1540  * @param url VLink subscriber URL. Must not be @c NULL.
1541  * @param schema_info Optional bundled @c ser + @c schema metadata.
1542  * @param handle Output handle. Must not be @c NULL.
1543  * @param msg_callback Message handler. Must not be @c NULL.
1544  * @param user_data Opaque pointer forwarded to @p msg_callback.
1545  * @param security_cfg Security configuration. Must not be @c NULL.
1546  * @param opt TLS options. Must not be @c NULL.
1547  * @return @c VLINK_RET_NO_ERROR on success;
1548  * @c VLINK_RET_INVALID_ERROR on bad arguments including
1549  * @p security_cfg == @c NULL or @p opt == @c NULL;
1550  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
1551  * @c VLINK_RET_TRANSFER_ERROR if @c listen() fails;
1552  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
1553  *
1554  * @note Caller owns the handle and must release it with @c vlink_destroy_subscriber().
1555  */
1557  const char* url, const vlink_schema_info_t* schema_info, vlink_subscriber_handle_t* handle,
1558  const vlink_msg_callback_t msg_callback, void* user_data, const vlink_security_config_t* security_cfg,
1559  const vlink_ssl_options_t* opt);
1560 
1561 /**
1562  * @brief Creates a secure Server and applies TLS options before transport initialisation.
1563  *
1564  * @param url VLink service URL. Must not be @c NULL.
1565  * @param schema_info Optional bundled @c ser + @c schema metadata.
1566  * @param handle Output handle. Must not be @c NULL.
1567  * @param req_callback Request handler. Must not be @c NULL.
1568  * @param user_data Opaque pointer forwarded to @p req_callback.
1569  * @param security_cfg Security configuration. Must not be @c NULL.
1570  * @param opt TLS options. Must not be @c NULL.
1571  * @return @c VLINK_RET_NO_ERROR on success;
1572  * @c VLINK_RET_INVALID_ERROR on bad arguments including
1573  * @p security_cfg == @c NULL or @p opt == @c NULL;
1574  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
1575  * @c VLINK_RET_TRANSFER_ERROR if @c listen() fails;
1576  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
1577  *
1578  * @note Caller owns the handle and must release it with @c vlink_destroy_server().
1579  */
1581  const char* url, const vlink_schema_info_t* schema_info, vlink_server_handle_t* handle,
1582  const vlink_req_callback_t req_callback, void* user_data, const vlink_security_config_t* security_cfg,
1583  const vlink_ssl_options_t* opt);
1584 
1585 /**
1586  * @brief Creates a secure Client and applies TLS options before transport initialisation.
1587  *
1588  * @param url VLink service URL. Must not be @c NULL.
1589  * @param schema_info Optional bundled @c ser + @c schema metadata.
1590  * @param handle Output handle. Must not be @c NULL.
1591  * @param security_cfg Security configuration. Must not be @c NULL.
1592  * @param opt TLS options. Must not be @c NULL.
1593  * @return @c VLINK_RET_NO_ERROR on success;
1594  * @c VLINK_RET_INVALID_ERROR on bad arguments including
1595  * @p security_cfg == @c NULL or @p opt == @c NULL;
1596  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
1597  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
1598  *
1599  * @note Caller owns the handle and must release it with @c vlink_destroy_client().
1600  */
1602  const vlink_schema_info_t* schema_info,
1603  vlink_client_handle_t* handle,
1604  const vlink_security_config_t* security_cfg,
1605  const vlink_ssl_options_t* opt);
1606 
1607 /**
1608  * @brief Creates a secure Setter and applies TLS options before transport initialisation.
1609  *
1610  * @param url VLink field URL. Must not be @c NULL.
1611  * @param schema_info Optional bundled @c ser + @c schema metadata.
1612  * @param handle Output handle. Must not be @c NULL.
1613  * @param security_cfg Security configuration. Must not be @c NULL.
1614  * @param opt TLS options. Must not be @c NULL.
1615  * @return @c VLINK_RET_NO_ERROR on success;
1616  * @c VLINK_RET_INVALID_ERROR on bad arguments including
1617  * @p security_cfg == @c NULL or @p opt == @c NULL;
1618  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
1619  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
1620  *
1621  * @note Caller owns the handle and must release it with @c vlink_destroy_setter().
1622  */
1624  const vlink_schema_info_t* schema_info,
1625  vlink_setter_handle_t* handle,
1626  const vlink_security_config_t* security_cfg,
1627  const vlink_ssl_options_t* opt);
1628 
1629 /**
1630  * @brief Creates a secure Getter and applies TLS options before transport initialisation.
1631  *
1632  * @param url VLink field URL. Must not be @c NULL.
1633  * @param schema_info Optional bundled @c ser + @c schema metadata.
1634  * @param handle Output handle. Must not be @c NULL.
1635  * @param msg_callback Push-mode callback, or @c NULL for poll mode.
1636  * @param user_data Opaque pointer forwarded to @p msg_callback.
1637  * @param security_cfg Security configuration. Must not be @c NULL.
1638  * @param opt TLS options. Must not be @c NULL.
1639  * @return @c VLINK_RET_NO_ERROR on success;
1640  * @c VLINK_RET_INVALID_ERROR on bad arguments including
1641  * @p security_cfg == @c NULL or @p opt == @c NULL;
1642  * @c VLINK_RET_MEMORY_ERROR on pool allocation failure;
1643  * @c VLINK_RET_TRANSFER_ERROR if @c listen() fails;
1644  * @c VLINK_RET_RUNTIME_ERROR on construction exception.
1645  *
1646  * @note Caller owns the handle and must release it with @c vlink_destroy_getter().
1647  */
1649  const char* url, const vlink_schema_info_t* schema_info, vlink_getter_handle_t* handle,
1650  const vlink_msg_callback_t msg_callback, void* user_data, const vlink_security_config_t* security_cfg,
1651  const vlink_ssl_options_t* opt);
1652 
1653 /**
1654  * @brief Applies TLS options to a Publisher handle.
1655  *
1656  * @details
1657  * Forwards @p opt to @c Node::set_ssl_options() on the underlying transport,
1658  * which writes the corresponding @c ssl.* property entries. The transport
1659  * backend reads those entries during connection setup. Handles returned by
1660  * this C API are already initialised, so this setter returns
1661  * @c VLINK_RET_RUNTIME_ERROR for normal C handles. Use the matching
1662  * @c vlink_create_*_with_ssl_options() function when TLS must affect the
1663  * initial transport connection.
1664  *
1665  * @param handle Publisher handle. Must not be @c NULL.
1666  * @param opt Options aggregate. Must not be @c NULL.
1667  * @return @c VLINK_RET_NO_ERROR on success for an uninitialised internal
1668  * handle;
1669  * @c VLINK_RET_INVALID_ERROR on bad arguments;
1670  * @c VLINK_RET_RUNTIME_ERROR once the handle has been initialised.
1671  */
1673  const vlink_ssl_options_t* opt);
1674 
1675 /**
1676  * @brief Applies TLS options to a Subscriber handle.
1677  *
1678  * @param handle Subscriber handle. Must not be @c NULL.
1679  * @param opt Options aggregate. Must not be @c NULL.
1680  * @return Same status codes as @c vlink_publisher_set_ssl_options().
1681  */
1683  const vlink_ssl_options_t* opt);
1684 
1685 /**
1686  * @brief Applies TLS options to a Server handle.
1687  *
1688  * @param handle Server handle. Must not be @c NULL.
1689  * @param opt Options aggregate. Must not be @c NULL.
1690  * @return Same status codes as @c vlink_publisher_set_ssl_options().
1691  */
1693 
1694 /**
1695  * @brief Applies TLS options to a Client handle.
1696  *
1697  * @param handle Client handle. Must not be @c NULL.
1698  * @param opt Options aggregate. Must not be @c NULL.
1699  * @return Same status codes as @c vlink_publisher_set_ssl_options().
1700  */
1702 
1703 /**
1704  * @brief Applies TLS options to a Setter handle.
1705  *
1706  * @param handle Setter handle. Must not be @c NULL.
1707  * @param opt Options aggregate. Must not be @c NULL.
1708  * @return Same status codes as @c vlink_publisher_set_ssl_options().
1709  */
1711 
1712 /**
1713  * @brief Applies TLS options to a Getter handle.
1714  *
1715  * @param handle Getter handle. Must not be @c NULL.
1716  * @param opt Options aggregate. Must not be @c NULL.
1717  * @return Same status codes as @c vlink_publisher_set_ssl_options().
1718  */
1720 
1721 /** @} */
1722 
1723 #ifdef __cplusplus
1724 }
1725 #endif
1726 
1727 // NOLINTEND
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.
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.
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.
void(* vlink_connect_callback_t)(const bool is_connected, void *user_data)
Callback fired when the connection state of a Publisher or Client changes.
Definition: c_api.h:326
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.
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().
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.
vlink_ret_t
Return code for VLink C API functions that report vlink_ret_t.
Definition: c_api.h:173
@ VLINK_RET_UNKNOWN_ERROR
Definition: c_api.h:174
@ VLINK_RET_NO_ERROR
Definition: c_api.h:175
@ VLINK_RET_RUNTIME_ERROR
Definition: c_api.h:179
@ VLINK_RET_INVALID_ERROR
Definition: c_api.h:177
@ VLINK_RET_MEMORY_ERROR
Definition: c_api.h:178
@ VLINK_RET_TRANSFER_ERROR
Definition: c_api.h:180
@ VLINK_RET_UNEXPECTED_ERROR
Definition: c_api.h:176
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.
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.
vlink_schema_t
Coarse runtime schema family used for raw C API nodes.
Definition: c_api.h:192
@ VLINK_SCHEMA_ZEROCOPY
Definition: c_api.h:195
@ VLINK_SCHEMA_RAW
Definition: c_api.h:194
@ VLINK_SCHEMA_CDR
Definition: c_api.h:198
@ VLINK_SCHEMA_FLATBUFFERS
Definition: c_api.h:197
@ VLINK_SCHEMA_PROTOBUF
Definition: c_api.h:196
@ VLINK_SCHEMA_UNKNOWN
Definition: c_api.h:193
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().
struct vlink_security * vlink_security_handle_t
Opaque handle for a standalone Security instance.
Definition: c_api.h:1017
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_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.
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.
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.
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.
Definition: c_api.h:356
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.
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.
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.
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.
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.
#define VLINK_C_API_EXPORT
Definition: c_api.h:148
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.
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.
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.
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_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_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.
VLINK_C_API_EXPORT void vlink_ssl_options_init(vlink_ssl_options_t *opt)
Zero-initialises opt and applies the canonical TLS defaults.
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.
VLINK_C_API_EXPORT vlink_security_handle_t vlink_security_create(const vlink_security_config_t *cfg)
Creates a standalone Security instance from cfg.
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.
Definition: c_api.h:1048
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().
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.
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.
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.
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.
VLINK_C_API_EXPORT int vlink_destroy_publisher(vlink_publisher_handle_t *handle)
Destroys a Publisher node and releases every associated resource.
VLINK_C_API_EXPORT void vlink_security_destroy(vlink_security_handle_t sec)
Destroys a standalone Security instance.
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.
Definition: c_api.h:366
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.
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.
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.
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.
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.
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_get(const vlink_getter_handle_t handle, uint8_t *data, size_t *size)
Retrieves the latest field value into a caller-provided buffer.
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.
Definition: c_api.h:339
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.
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.
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.
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 st...
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.
VLINK_C_API_EXPORT int vlink_destroy_client(vlink_client_handle_t *handle)
Destroys a Client node and releases every associated resource.
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.
VLINK_C_API_EXPORT void vlink_security_free_buffer(uint8_t *buf)
Releases a buffer returned by vlink_security_encrypt() or vlink_security_decrypt().
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.
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_destroy_subscriber(vlink_subscriber_handle_t *handle)
Destroys a Subscriber node and releases every associated resource.
VLINK_C_API_EXPORT int vlink_destroy_setter(vlink_setter_handle_t *handle)
Destroys a Setter node and releases every associated resource.
VLINK_C_API_EXPORT int vlink_destroy_getter(vlink_getter_handle_t *handle)
Destroys a Getter node and releases every associated resource.
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.