libivon 0.1.0
Voice-over-IP library
Loading...
Searching...
No Matches
Macros | Functions
ivon_client.h File Reference
#include "libivon/public/export.h"
#include "libivon/public/ivon_client_types.h"

Macros

#define IVON_CLIENT_API_VERSION_MAJOR   1
 C ABI for the libivon client.
 
#define IVON_CLIENT_API_VERSION_MINOR   0
 Minor version of the C ABI (bump on additive changes).
 
Log level constants (same values across all ivon subsystems).
#define IVON_LOG_LEVEL_TRACE   0
 
#define IVON_LOG_LEVEL_DEBUG   1
 
#define IVON_LOG_LEVEL_INFO   2
 
#define IVON_LOG_LEVEL_WARN   3
 
#define IVON_LOG_LEVEL_ERROR   4
 
#define IVON_LOG_LEVEL_CRITICAL   5
 
#define IVON_LOG_LEVEL_OFF   6
 

Functions

int ivon_client_api_version_major (void)
 Get the major version of the client C ABI at runtime.
 
int ivon_client_api_version_minor (void)
 Get the minor version of the client C ABI at runtime.
 
ivon_client_config_t ivon_client_config_create (void)
 Create a new client configuration with sane defaults.
 
void ivon_client_config_destroy (ivon_client_config_t config)
 Destroy a client configuration handle. NULL is a safe no-op.
 
void ivon_client_config_set_server_address (ivon_client_config_t config, const char *address)
 Set the server address (e.g. "127.0.0.1"). The string is copied.
 
void ivon_client_config_set_port (ivon_client_config_t config, uint16_t port)
 Set the server port (default 9129).
 
void ivon_client_config_set_client_id (ivon_client_config_t config, const char *client_id)
 Set the client identifier. The string is copied.
 
void ivon_client_config_set_key_store_path (ivon_client_config_t config, const char *path)
 Set the TOFU key store file path (NULL for in-memory). Copied.
 
void ivon_client_config_set_sync_timeout (ivon_client_config_t config, uint32_t seconds)
 Set the sync timeout in seconds (0 = infinite).
 
ivon_client_t ivon_client_create (ivon_client_config_t config)
 Create a new client instance.
 
void ivon_client_destroy (ivon_client_t client)
 Destroy a client instance and free all associated resources.
 
ivon_connect_result_t ivon_client_connect (ivon_client_t client)
 Connect to the server (blocking).
 
void ivon_client_disconnect (ivon_client_t client)
 Disconnect from the server.
 
ivon_connection_state_t ivon_client_connection_state (ivon_client_t client)
 Get the current connection state.
 
int ivon_client_is_connected (ivon_client_t client)
 Check if the client is connected.
 
int ivon_client_is_synchronized (ivon_client_t client)
 Check if initial synchronization is complete.
 
size_t ivon_client_session_id (ivon_client_t client, char *buf, size_t buf_len)
 Get the session ID assigned by the server.
 
int ivon_client_send_client_message (ivon_client_t client, const char *target_client_id, const char *type, const uint8_t *data, size_t data_len)
 Send a direct message to a specific remote client.
 
int ivon_client_send_broadcast_message (ivon_client_t client, const char *type, const uint8_t *data, size_t data_len)
 Broadcast a message to all connected clients.
 
int ivon_client_send_group_message (ivon_client_t client, const char *group_id, const char *type, const uint8_t *data, size_t data_len)
 Send a message to all members of a group via TCP.
 
size_t ivon_client_get_remote_client_count (ivon_client_t client)
 Get the number of remote clients.
 
int ivon_client_has_remote_client (ivon_client_t client, const char *client_id)
 Check if a remote client exists.
 
void ivon_client_for_each_remote_client (ivon_client_t client, ivon_string_iterator_fn callback, void *user_data)
 Iterate over all remote client IDs.
 
int ivon_client_join_group (ivon_client_t client, const char *group_id)
 Request to join a group.
 
int ivon_client_leave_group (ivon_client_t client, const char *group_id)
 Request to leave a group.
 
int ivon_client_request_group_list (ivon_client_t client)
 Request the list of available groups.
 
int ivon_client_set_mute (ivon_client_t client, const char *group_id, const char *target_client_id, int muted)
 Set the mute state of a target client in a group.
 
int ivon_client_is_group_member (ivon_client_t client, const char *group_id)
 Check if we are a member of a group.
 
void ivon_client_for_each_group (ivon_client_t client, ivon_string_iterator_fn callback, void *user_data)
 Iterate over all group IDs we are a member of.
 
int ivon_client_send_group_data (ivon_client_t client, const char *group_id, const unsigned char *data, size_t data_len)
 Send data to a group via fanout.
 
int ivon_client_set_fanout_sender_id (ivon_client_t client, uint64_t sender_id)
 Set the client's sender ID for fanout.
 
void ivon_client_set_on_tofu_verify (ivon_client_t client, ivon_tofu_verify_fn callback, void *user_data)
 Set the TOFU key verification callback.
 
void ivon_client_set_on_password_required (ivon_client_t client, ivon_password_fn callback, void *user_data)
 Set the password prompt callback.
 
void ivon_client_set_on_client_message (ivon_client_t client, ivon_client_message_fn callback, void *user_data)
 Set the callback for incoming direct client messages.
 
void ivon_client_set_on_client_joined (ivon_client_t client, ivon_client_joined_fn callback, void *user_data)
 Set the callback fired when a remote client joins the session.
 
void ivon_client_set_on_client_left (ivon_client_t client, ivon_client_left_fn callback, void *user_data)
 Set the callback fired when a remote client leaves the session.
 
void ivon_client_set_on_kicked (ivon_client_t client, ivon_kicked_fn callback, void *user_data)
 Set the callback fired when this client is kicked from the server.
 
void ivon_client_set_on_disconnected (ivon_client_t client, ivon_disconnected_fn callback, void *user_data)
 Set the callback fired when the connection is lost or closed.
 
void ivon_client_set_on_connection_state_changed (ivon_client_t client, ivon_connection_state_fn callback, void *user_data)
 Set the callback fired on connection state transitions.
 
void ivon_client_set_on_group_joined (ivon_client_t client, ivon_group_join_fn callback, void *user_data)
 Set the callback for group join results.
 
void ivon_client_set_on_group_left (ivon_client_t client, ivon_group_leave_fn callback, void *user_data)
 Set the callback for group leave results.
 
void ivon_client_set_on_group_key_update (ivon_client_t client, ivon_group_key_update_fn callback, void *user_data)
 Set the callback fired when a group's encryption key is rotated.
 
void ivon_client_set_on_group_member_joined (ivon_client_t client, ivon_group_member_joined_fn callback, void *user_data)
 Set the callback fired when another client joins a group.
 
void ivon_client_set_on_group_member_left (ivon_client_t client, ivon_group_member_left_fn callback, void *user_data)
 Set the callback fired when another client leaves a group.
 
void ivon_client_set_on_group_kicked (ivon_client_t client, ivon_group_kicked_fn callback, void *user_data)
 Set the callback fired when this client is kicked from a group.
 
void ivon_client_set_on_group_list (ivon_client_t client, ivon_group_list_fn callback, void *user_data)
 Set the callback for group list responses.
 
void ivon_client_set_on_group_mute (ivon_client_t client, ivon_group_mute_fn callback, void *user_data)
 Set the callback for group mute operation results.
 
void ivon_client_set_on_fanout_data (ivon_client_t client, ivon_fanout_data_fn callback, void *user_data)
 Set the callback for incoming fanout data.
 
void ivon_client_set_on_fanout_error (ivon_client_t client, ivon_fanout_error_fn callback, void *user_data)
 Set the callback for fanout channel errors.
 
void ivon_client_set_on_server_properties (ivon_client_t client, ivon_server_properties_fn callback, void *user_data)
 Set the callback for initial server properties received during sync.
 
void ivon_client_set_on_server_property_update (ivon_client_t client, ivon_server_property_update_fn callback, void *user_data)
 Set the callback for server property updates.
 
void ivon_client_set_on_group_property_update (ivon_client_t client, ivon_group_property_update_fn callback, void *user_data)
 Set the callback for group property updates.
 
void ivon_client_set_log_level (ivon_client_t client, int level)
 Set the client's log level at runtime.
 
int ivon_client_get_log_level (ivon_client_t client)
 Get the client's current log level.
 

Macro Definition Documentation

◆ IVON_CLIENT_API_VERSION_MAJOR

#define IVON_CLIENT_API_VERSION_MAJOR   1

C ABI for the libivon client.

Author
Cliff Foster (Nou) cliff.nosp@m.@idi.nosp@m.-syst.nosp@m.ems..nosp@m.com
Copyright
Copyright (c) 2025 International Development & Integration Systems LLC

All functions use the opaque ivon_client_t handle and plain C types. Symbols are exported via IDI_IVON_EXPORT when building the shared library.

See also
ivon_client_types.h for type definitions.

Major version of the C ABI (bump on breaking changes).

◆ IVON_CLIENT_API_VERSION_MINOR

#define IVON_CLIENT_API_VERSION_MINOR   0

Minor version of the C ABI (bump on additive changes).

◆ IVON_LOG_LEVEL_CRITICAL

#define IVON_LOG_LEVEL_CRITICAL   5

◆ IVON_LOG_LEVEL_DEBUG

#define IVON_LOG_LEVEL_DEBUG   1

◆ IVON_LOG_LEVEL_ERROR

#define IVON_LOG_LEVEL_ERROR   4

◆ IVON_LOG_LEVEL_INFO

#define IVON_LOG_LEVEL_INFO   2

◆ IVON_LOG_LEVEL_OFF

#define IVON_LOG_LEVEL_OFF   6

◆ IVON_LOG_LEVEL_TRACE

#define IVON_LOG_LEVEL_TRACE   0

◆ IVON_LOG_LEVEL_WARN

#define IVON_LOG_LEVEL_WARN   3

Function Documentation

◆ ivon_client_api_version_major()

int ivon_client_api_version_major ( void  )

Get the major version of the client C ABI at runtime.

◆ ivon_client_api_version_minor()

int ivon_client_api_version_minor ( void  )

Get the minor version of the client C ABI at runtime.

◆ ivon_client_config_create()

ivon_client_config_t ivon_client_config_create ( void  )

Create a new client configuration with sane defaults.

Defaults: port 9129, sync timeout 30 s, no key store. Call ivon_client_config_set_*() to customise, then pass to ivon_client_create(). Destroy with ivon_client_config_destroy() after creation (the client copies what it needs).

Returns
A new config handle, or NULL on allocation failure.

◆ ivon_client_config_destroy()

void ivon_client_config_destroy ( ivon_client_config_t  config)

Destroy a client configuration handle. NULL is a safe no-op.

◆ ivon_client_config_set_client_id()

void ivon_client_config_set_client_id ( ivon_client_config_t  config,
const char *  client_id 
)

Set the client identifier. The string is copied.

◆ ivon_client_config_set_key_store_path()

void ivon_client_config_set_key_store_path ( ivon_client_config_t  config,
const char *  path 
)

Set the TOFU key store file path (NULL for in-memory). Copied.

◆ ivon_client_config_set_port()

void ivon_client_config_set_port ( ivon_client_config_t  config,
uint16_t  port 
)

Set the server port (default 9129).

◆ ivon_client_config_set_server_address()

void ivon_client_config_set_server_address ( ivon_client_config_t  config,
const char *  address 
)

Set the server address (e.g. "127.0.0.1"). The string is copied.

◆ ivon_client_config_set_sync_timeout()

void ivon_client_config_set_sync_timeout ( ivon_client_config_t  config,
uint32_t  seconds 
)

Set the sync timeout in seconds (0 = infinite).

◆ ivon_client_connect()

ivon_connect_result_t ivon_client_connect ( ivon_client_t  client)

Connect to the server (blocking).

On success, result.success is non-zero and the connection is established.

Parameters
clientThe client handle.
Returns
Connection result with error details on failure.

◆ ivon_client_connection_state()

ivon_connection_state_t ivon_client_connection_state ( ivon_client_t  client)

Get the current connection state.

Parameters
clientThe client handle.

◆ ivon_client_create()

ivon_client_t ivon_client_create ( ivon_client_config_t  config)

Create a new client instance.

Parameters
configClient configuration handle from ivon_client_config_create(). The handle may be destroyed after this call returns.
Returns
A new client handle, or NULL on failure.

◆ ivon_client_destroy()

void ivon_client_destroy ( ivon_client_t  client)

Destroy a client instance and free all associated resources.

Disconnects the client if still connected, then frees all resources. Passing NULL is a safe no-op.

Parameters
clientThe client handle to destroy.

◆ ivon_client_disconnect()

void ivon_client_disconnect ( ivon_client_t  client)

Disconnect from the server.

Blocks until the connection is closed or a timeout is reached.

Parameters
clientThe client handle.

◆ ivon_client_for_each_group()

void ivon_client_for_each_group ( ivon_client_t  client,
ivon_string_iterator_fn  callback,
void *  user_data 
)

Iterate over all group IDs we are a member of.

Parameters
clientThe client handle.
callbackFunction called for each group.
user_dataPassed through to the callback.

◆ ivon_client_for_each_remote_client()

void ivon_client_for_each_remote_client ( ivon_client_t  client,
ivon_string_iterator_fn  callback,
void *  user_data 
)

Iterate over all remote client IDs.

Calls callback once per remote client with the client ID. The string passed to the callback is valid only for the duration of that callback invocation.

Parameters
clientThe client handle.
callbackFunction called for each remote client.
user_dataPassed through to the callback.

◆ ivon_client_get_log_level()

int ivon_client_get_log_level ( ivon_client_t  client)

Get the client's current log level.

Parameters
clientThe client handle.
Returns
The current log level (IVON_LOG_LEVEL_*), or IVON_LOG_LEVEL_OFF if the handle is NULL.

◆ ivon_client_get_remote_client_count()

size_t ivon_client_get_remote_client_count ( ivon_client_t  client)

Get the number of remote clients.

◆ ivon_client_has_remote_client()

int ivon_client_has_remote_client ( ivon_client_t  client,
const char *  client_id 
)

Check if a remote client exists.

Returns
Non-zero if the client exists, zero otherwise.

◆ ivon_client_is_connected()

int ivon_client_is_connected ( ivon_client_t  client)

Check if the client is connected.

Returns
Non-zero if connected, zero otherwise.

◆ ivon_client_is_group_member()

int ivon_client_is_group_member ( ivon_client_t  client,
const char *  group_id 
)

Check if we are a member of a group.

Returns
Non-zero if member, zero otherwise.

◆ ivon_client_is_synchronized()

int ivon_client_is_synchronized ( ivon_client_t  client)

Check if initial synchronization is complete.

Returns
Non-zero if synchronized, zero otherwise.

◆ ivon_client_join_group()

int ivon_client_join_group ( ivon_client_t  client,
const char *  group_id 
)

Request to join a group.

Returns
Non-zero if request sent, zero if not connected.

◆ ivon_client_leave_group()

int ivon_client_leave_group ( ivon_client_t  client,
const char *  group_id 
)

Request to leave a group.

Returns
Non-zero if request sent, zero if not connected.

◆ ivon_client_request_group_list()

int ivon_client_request_group_list ( ivon_client_t  client)

Request the list of available groups.

Returns
Non-zero if request sent, zero if not connected.

◆ ivon_client_send_broadcast_message()

int ivon_client_send_broadcast_message ( ivon_client_t  client,
const char *  type,
const uint8_t *  data,
size_t  data_len 
)

Broadcast a message to all connected clients.

Returns
Non-zero if queued, zero if not connected.

◆ ivon_client_send_client_message()

int ivon_client_send_client_message ( ivon_client_t  client,
const char *  target_client_id,
const char *  type,
const uint8_t *  data,
size_t  data_len 
)

Send a direct message to a specific remote client.

Returns
Non-zero if queued, zero if not connected or client unknown.

◆ ivon_client_send_group_data()

int ivon_client_send_group_data ( ivon_client_t  client,
const char *  group_id,
const unsigned char *  data,
size_t  data_len 
)

Send data to a group via fanout.

Returns
Non-zero if sent, zero if not connected or not a member.

◆ ivon_client_send_group_message()

int ivon_client_send_group_message ( ivon_client_t  client,
const char *  group_id,
const char *  type,
const uint8_t *  data,
size_t  data_len 
)

Send a message to all members of a group via TCP.

Returns
Non-zero if queued, zero if not connected or not a group member.

◆ ivon_client_session_id()

size_t ivon_client_session_id ( ivon_client_t  client,
char *  buf,
size_t  buf_len 
)

Get the session ID assigned by the server.

If buf is NULL or buf_len is too small, returns the required buffer size (including the null terminator) without writing.

Parameters
clientThe client handle.
bufDestination buffer, or NULL to query size.
buf_lenSize of the destination buffer in bytes.
Returns
Number of bytes required (including null terminator).

◆ ivon_client_set_fanout_sender_id()

int ivon_client_set_fanout_sender_id ( ivon_client_t  client,
uint64_t  sender_id 
)

Set the client's sender ID for fanout.

Returns
Non-zero if set, zero if not connected.

◆ ivon_client_set_log_level()

void ivon_client_set_log_level ( ivon_client_t  client,
int  level 
)

Set the client's log level at runtime.

Parameters
clientThe client handle.
levelOne of the IVON_LOG_LEVEL_* constants (0–6).

◆ ivon_client_set_mute()

int ivon_client_set_mute ( ivon_client_t  client,
const char *  group_id,
const char *  target_client_id,
int  muted 
)

Set the mute state of a target client in a group.

Returns
Non-zero if request sent, zero if not connected.

◆ ivon_client_set_on_client_joined()

void ivon_client_set_on_client_joined ( ivon_client_t  client,
ivon_client_joined_fn  callback,
void *  user_data 
)

Set the callback fired when a remote client joins the session.

◆ ivon_client_set_on_client_left()

void ivon_client_set_on_client_left ( ivon_client_t  client,
ivon_client_left_fn  callback,
void *  user_data 
)

Set the callback fired when a remote client leaves the session.

◆ ivon_client_set_on_client_message()

void ivon_client_set_on_client_message ( ivon_client_t  client,
ivon_client_message_fn  callback,
void *  user_data 
)

Set the callback for incoming direct client messages.

◆ ivon_client_set_on_connection_state_changed()

void ivon_client_set_on_connection_state_changed ( ivon_client_t  client,
ivon_connection_state_fn  callback,
void *  user_data 
)

Set the callback fired on connection state transitions.

◆ ivon_client_set_on_disconnected()

void ivon_client_set_on_disconnected ( ivon_client_t  client,
ivon_disconnected_fn  callback,
void *  user_data 
)

Set the callback fired when the connection is lost or closed.

◆ ivon_client_set_on_fanout_data()

void ivon_client_set_on_fanout_data ( ivon_client_t  client,
ivon_fanout_data_fn  callback,
void *  user_data 
)

Set the callback for incoming fanout data.

Called from the IO thread when audio or other group data arrives via the fanout channel. The voice session wires this internally; only set it for standalone client + audio usage.

◆ ivon_client_set_on_fanout_error()

void ivon_client_set_on_fanout_error ( ivon_client_t  client,
ivon_fanout_error_fn  callback,
void *  user_data 
)

Set the callback for fanout channel errors.

◆ ivon_client_set_on_group_joined()

void ivon_client_set_on_group_joined ( ivon_client_t  client,
ivon_group_join_fn  callback,
void *  user_data 
)

Set the callback for group join results.

◆ ivon_client_set_on_group_key_update()

void ivon_client_set_on_group_key_update ( ivon_client_t  client,
ivon_group_key_update_fn  callback,
void *  user_data 
)

Set the callback fired when a group's encryption key is rotated.

◆ ivon_client_set_on_group_kicked()

void ivon_client_set_on_group_kicked ( ivon_client_t  client,
ivon_group_kicked_fn  callback,
void *  user_data 
)

Set the callback fired when this client is kicked from a group.

◆ ivon_client_set_on_group_left()

void ivon_client_set_on_group_left ( ivon_client_t  client,
ivon_group_leave_fn  callback,
void *  user_data 
)

Set the callback for group leave results.

◆ ivon_client_set_on_group_list()

void ivon_client_set_on_group_list ( ivon_client_t  client,
ivon_group_list_fn  callback,
void *  user_data 
)

Set the callback for group list responses.

Called with the full list of groups after ivon_client_request_group_list().

◆ ivon_client_set_on_group_member_joined()

void ivon_client_set_on_group_member_joined ( ivon_client_t  client,
ivon_group_member_joined_fn  callback,
void *  user_data 
)

Set the callback fired when another client joins a group.

◆ ivon_client_set_on_group_member_left()

void ivon_client_set_on_group_member_left ( ivon_client_t  client,
ivon_group_member_left_fn  callback,
void *  user_data 
)

Set the callback fired when another client leaves a group.

◆ ivon_client_set_on_group_mute()

void ivon_client_set_on_group_mute ( ivon_client_t  client,
ivon_group_mute_fn  callback,
void *  user_data 
)

Set the callback for group mute operation results.

◆ ivon_client_set_on_group_property_update()

void ivon_client_set_on_group_property_update ( ivon_client_t  client,
ivon_group_property_update_fn  callback,
void *  user_data 
)

Set the callback for group property updates.

◆ ivon_client_set_on_kicked()

void ivon_client_set_on_kicked ( ivon_client_t  client,
ivon_kicked_fn  callback,
void *  user_data 
)

Set the callback fired when this client is kicked from the server.

◆ ivon_client_set_on_password_required()

void ivon_client_set_on_password_required ( ivon_client_t  client,
ivon_password_fn  callback,
void *  user_data 
)

Set the password prompt callback.

Called when the server requires password authentication. Write the password into the provided buffer and return non-zero to submit, or return zero to cancel.

See also
ivon_password_fn

◆ ivon_client_set_on_server_properties()

void ivon_client_set_on_server_properties ( ivon_client_t  client,
ivon_server_properties_fn  callback,
void *  user_data 
)

Set the callback for initial server properties received during sync.

◆ ivon_client_set_on_server_property_update()

void ivon_client_set_on_server_property_update ( ivon_client_t  client,
ivon_server_property_update_fn  callback,
void *  user_data 
)

Set the callback for server property updates.

◆ ivon_client_set_on_tofu_verify()

void ivon_client_set_on_tofu_verify ( ivon_client_t  client,
ivon_tofu_verify_fn  callback,
void *  user_data 
)

Set the TOFU key verification callback.

Called during connection negotiation. Return non-zero from the callback to accept the server's key, zero to reject and abort.

See also
ivon_tofu_verify_fn