ombrac-client 0.7.1

Safe, fast, small TCP over QUIC tunnel using Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

/* Generated by cbindgen */

#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>

/**
 * A type alias for the C-style callback function pointer.
 * Changed to pass (buf, len) instead of a null-terminated string for better performance.
 */
typedef void (*LogCallback)(const char *buf, uintptr_t len);

/**
 * Initializes the logging system to use a C-style callback for log messages.
 *
 * This function must be called before `ombrac_client_service_startup` if you wish to
 * receive logs in a C-compatible way. It sets up a global logger that will
 * forward all log records to the provided callback function.
 *
 * # Arguments
 *
 * * `callback` - A function pointer of type `LogCallback`. See the definition of
 *   `LogCallback` for the expected signature and log level mappings.
 *
 * # Safety
 *
 * The provided `callback` function pointer must be valid and remain valid for
 * the lifetime of the program. If a null pointer is passed, logging will be
 * disabled.
 */
void ombrac_client_set_log_callback(const LogCallback *callback);

/**
 * Initializes and starts the service with a given JSON configuration.
 *
 * This function sets up the asynchronous runtime, parses the configuration,
 * and launches the main service. It must be called before any other service
 * operations. The service must be shut down via `ombrac_client_service_shutdown` to ensure
 * a clean exit.
 *
 * # Arguments
 *
 * * `config_json` - A pointer to a null-terminated UTF-8 string containing the
 *   service configuration in JSON format.
 *
 * # Returns
 *
 * * `0` on success.
 * * `-1` on failure (e.g., invalid configuration, service already running, or
 *   runtime initialization failed).
 *
 * # Safety
 *
 * The caller must ensure that `config_json` is a valid pointer to a
 * null-terminated C string. This function is not thread-safe and should not be
 * called concurrently with `ombrac_client_service_shutdown`.
 */
int32_t ombrac_client_service_startup(const char *config_json);

/**
 * Triggers a network rebind on the underlying transport.
 *
 * This is useful in scenarios where the network environment changes,
 * to ensure the client can re-establish its connection through a new socket.
 *
 * # Returns
 *
 * * `0` on success.
 * * `-1` if the service is not running or the rebind operation fails.
 *
 * # Safety
 *
 * This function is not thread-safe and should not be called concurrently with
 * other service management functions.
 */
int32_t ombrac_client_service_rebind(void);

/**
 * Shuts down the running service and releases all associated resources.
 *
 * This function will gracefully stop the service and terminate the asynchronous
 * runtime. It is safe to call even if the service was not started or has
 * already been stopped.
 *
 * # Returns
 *
 * * `0` on completion.
 *
 * # Safety
 *
 * This function is not thread-safe and should not be called concurrently with
 * `ombrac_client_service_startup`.
 */
int32_t ombrac_client_service_shutdown(void);

/**
 * Returns the version of the ombrac-client library.
 *
 * The returned string is a null-terminated UTF-8 string. The memory for this
 * string is managed by the library and should not be freed by the caller.
 */
const char *ombrac_client_get_version(void);