ivon_server.h File Reference

#include "libivon/public/export.h"
#include "libivon/public/ivon_server_types.h"

Macros
#define	IVON_SERVER_API_VERSION_MAJOR   1
	C ABI for the libivon server.
#define	IVON_SERVER_API_VERSION_MINOR   0
	Minor version of the server C ABI (bump on additive changes).

Functions
int	ivon_server_api_version_major (void)
	Get the major version of the server C ABI at runtime.
int	ivon_server_api_version_minor (void)
	Get the minor version of the server C ABI at runtime.
ivon_server_config_t	ivon_server_config_create (void)
	Create a new server configuration handle.
void	ivon_server_config_destroy (ivon_server_config_t config)
	Destroy a server configuration handle.
void	ivon_server_config_set_address (ivon_server_config_t config, const char *address)
	Set the listening address (default "0.0.0.0").
void	ivon_server_config_set_port (ivon_server_config_t config, uint16_t port)
	Set the listening port (default 9129).
void	ivon_server_config_set_network_interface (ivon_server_config_t config, const char *iface)
	Bind to a specific network interface (Linux only, e.g. "eth0").
void	ivon_server_config_set_num_threads (ivon_server_config_t config, size_t num_threads)
	Set the number of IO threads (default 1).
int	ivon_server_config_set_keys (ivon_server_config_t config, const uint8_t *public_key, size_t public_key_len, const uint8_t *private_key, size_t private_key_len)
	Set raw key material for server identity.
int	ivon_server_config_load_key_pair (ivon_server_config_t config, const char *public_key_file, const char *private_key_file)
	Load a key pair from files.
int	ivon_server_config_generate_key_pair (ivon_server_config_t config, const char *public_key_file, const char *private_key_file)
	Generate a new key pair, save to files, and load into config.
void	ivon_server_config_set_require_password (ivon_server_config_t config, int require)
	Require clients to authenticate with a password (default false).
void	ivon_server_config_set_password (ivon_server_config_t config, const char *password)
	Set the expected password.
void	ivon_server_config_set_max_password_attempts (ivon_server_config_t config, uint32_t max_attempts)
	Set the maximum password attempts before rejection (default 3).
void	ivon_server_config_add_group (ivon_server_config_t config, const char *group_id)
	Add a group to be created at server startup.
void	ivon_server_config_set_fanout_base_port (ivon_server_config_t config, uint16_t port)
	Set the base UDP port for fanout workers (default 10300).
void	ivon_server_config_set_property (ivon_server_config_t config, const char *key, const void *value, size_t value_len)
	Set a server-level property on the config (before server creation).
void	ivon_server_config_set_fanout_advertise_address (ivon_server_config_t config, const char *address)
	Set the address advertised to clients for fanout (default "127.0.0.1").
void	ivon_server_config_set_key_rotation_on_leave (ivon_server_config_t config, int enabled)
	Rotate group keys when a member leaves (default true).
void	ivon_server_config_set_key_rotation_debounce_ms (ivon_server_config_t config, uint64_t ms)
	Set key rotation debounce interval in milliseconds (default 1000).
void	ivon_server_config_set_key_rotation_interval_ms (ivon_server_config_t config, uint64_t ms)
	Set periodic key rotation interval in milliseconds (0 = disabled).
void	ivon_server_config_set_on_connection_admission (ivon_server_config_t config, ivon_server_connection_admission_fn callback, void *user_data)
	Set the connection admission gate callback.
void	ivon_server_config_set_on_client_id_check (ivon_server_config_t config, ivon_server_client_id_check_fn callback, void *user_data)
	Set the client ID validation callback.
void	ivon_server_config_set_on_password_validate (ivon_server_config_t config, ivon_server_password_validate_fn callback, void *user_data)
	Set the password validation callback.
void	ivon_server_config_set_on_client_approve (ivon_server_config_t config, ivon_server_client_approve_fn callback, void *user_data)
	Set the client approval callback.
void	ivon_server_config_set_on_client_connected (ivon_server_config_t config, ivon_server_client_connected_fn callback, void *user_data)
	Set the client connected event callback.
void	ivon_server_config_set_on_client_disconnected (ivon_server_config_t config, ivon_server_client_disconnected_fn callback, void *user_data)
	Set the client disconnected event callback.
void	ivon_server_config_set_on_group_join_authorize (ivon_server_config_t config, ivon_server_group_join_authorize_fn callback, void *user_data)
	Set the group join authorization callback.
ivon_server_t	ivon_server_create (ivon_server_config_t config)
	Create a new server instance from a populated config.
void	ivon_server_destroy (ivon_server_t server)
	Destroy a server instance and free all resources.
void	ivon_server_run (ivon_server_t server)
	Run the server (blocks until stop() is called).
void	ivon_server_stop (ivon_server_t server)
	Stop the server (thread-safe, causes run() to return).
void	ivon_server_set_on_connection_admission (ivon_server_t server, ivon_server_connection_admission_fn callback, void *user_data)
	Set or replace the connection admission gate on a live server.
void	ivon_server_set_on_client_id_check (ivon_server_t server, ivon_server_client_id_check_fn callback, void *user_data)
	Set or replace the client ID validation callback on a live server.
void	ivon_server_set_on_password_validate (ivon_server_t server, ivon_server_password_validate_fn callback, void *user_data)
	Set or replace the password validation callback on a live server.
void	ivon_server_set_on_client_approve (ivon_server_t server, ivon_server_client_approve_fn callback, void *user_data)
	Set or replace the client approval callback on a live server.
void	ivon_server_set_on_client_connected (ivon_server_t server, ivon_server_client_connected_fn callback, void *user_data)
	Set or replace the client connected event callback on a live server.
void	ivon_server_set_on_client_disconnected (ivon_server_t server, ivon_server_client_disconnected_fn callback, void *user_data)
	Set or replace the client disconnected event callback on a live server.
void	ivon_server_set_on_group_join_authorize (ivon_server_t server, ivon_server_group_join_authorize_fn callback, void *user_data)
	Set or replace the group join authorization callback on a live server.
int	ivon_server_create_group (ivon_server_t server, const char *group_id)
	Create a new group.
void	ivon_server_delete_group (ivon_server_t server, const char *group_id, ivon_server_bool_callback_fn callback, void *user_data)
	Delete a group (asynchronous).
int	ivon_server_has_group (ivon_server_t server, const char *group_id)
	Check if a group exists.
void	ivon_server_for_each_group (ivon_server_t server, ivon_string_iterator_fn callback, void *user_data)
	Iterate over all group IDs.
int32_t	ivon_server_rotate_group_key (ivon_server_t server, const char *group_id)
	Rotate the encryption key for a group.
void	ivon_server_kick_client (ivon_server_t server, const char *client_id, const char *reason)
	Kick a client from the server.
void	ivon_server_kick_client_from_group (ivon_server_t server, const char *group_id, const char *client_id, const char *reason, ivon_server_bool_callback_fn callback, void *user_data)
	Kick a client from a specific group (asynchronous).
void	ivon_server_send_message_to_client (ivon_server_t server, const char *client_id, const char *data_type, const void *data, size_t data_len)
	Send a message from the server to a specific client.
void	ivon_server_send_message_to_group (ivon_server_t server, const char *group_id, const char *data_type, const void *data, size_t data_len)
	Send a message from the server to all members of a group.
void	ivon_server_send_message_to_all (ivon_server_t server, const char *data_type, const void *data, size_t data_len)
	Broadcast a message from the server to all connected clients.
void	ivon_server_set_property (ivon_server_t server, const char *key, const void *value, size_t value_len)
	Set a server-level property.
void	ivon_server_set_group_property (ivon_server_t server, const char *group_id, const char *key, const void *value, size_t value_len)
	Set a group-level property.

Macro Definition Documentation

IVON_SERVER_API_VERSION_MAJOR

#define IVON_SERVER_API_VERSION_MAJOR   1

C ABI for the libivon server.

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_server_t handle and plain C types. Symbols are exported via IDI_IVON_EXPORT when building the shared library.

The server uses a builder-style configuration: create a config handle with ivon_server_config_create(), populate it with setter functions, then pass it to ivon_server_create(). Callbacks are set on the config before server creation and cannot be changed afterwards.

See also

ivon_server_types.h for type definitions.

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

IVON_SERVER_API_VERSION_MINOR

#define IVON_SERVER_API_VERSION_MINOR   0

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

Function Documentation

ivon_server_api_version_major()

int ivon_server_api_version_major

(

void

)

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

ivon_server_api_version_minor()

int ivon_server_api_version_minor

(

void

)

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

ivon_server_config_add_group()

void ivon_server_config_add_group	(	ivon_server_config_t	config,
		const char *	group_id
	)

Add a group to be created at server startup.

ivon_server_config_create()

ivon_server_config_t ivon_server_config_create

(

void

)

Create a new server configuration handle.

The config is populated via setter functions and then consumed by ivon_server_create(). Must be freed with ivon_server_config_destroy() after the server is created (or on error).

Returns

A new config handle, or NULL on allocation failure.

ivon_server_config_destroy()

void ivon_server_config_destroy

(

ivon_server_config_t

config

)

Destroy a server configuration handle.

Safe to call after ivon_server_create() has consumed the config. Passing NULL is a safe no-op.

ivon_server_config_generate_key_pair()

int ivon_server_config_generate_key_pair	(	ivon_server_config_t	config,
		const char *	public_key_file,
		const char *	private_key_file
	)

Generate a new key pair, save to files, and load into config.

Creates the directory if it does not exist. Writes the public and private key files, then sets the generated keys on the config.

Parameters

config	Server config handle.
public_key_file	Path to write the public key.
private_key_file	Path to write the private key.

Returns

Non-zero on success, zero on failure.

ivon_server_config_load_key_pair()

int ivon_server_config_load_key_pair	(	ivon_server_config_t	config,
		const char *	public_key_file,
		const char *	private_key_file
	)

Load a key pair from files.

Returns

Non-zero on success, zero if the files could not be read.

ivon_server_config_set_address()

void ivon_server_config_set_address	(	ivon_server_config_t	config,
		const char *	address
	)

Set the listening address (default "0.0.0.0").

ivon_server_config_set_fanout_advertise_address()

void ivon_server_config_set_fanout_advertise_address	(	ivon_server_config_t	config,
		const char *	address
	)

Set the address advertised to clients for fanout (default "127.0.0.1").

ivon_server_config_set_fanout_base_port()

void ivon_server_config_set_fanout_base_port	(	ivon_server_config_t	config,
		uint16_t	port
	)

Set the base UDP port for fanout workers (default 10300).

ivon_server_config_set_key_rotation_debounce_ms()

void ivon_server_config_set_key_rotation_debounce_ms	(	ivon_server_config_t	config,
		uint64_t	ms
	)

Set key rotation debounce interval in milliseconds (default 1000).

ivon_server_config_set_key_rotation_interval_ms()

void ivon_server_config_set_key_rotation_interval_ms	(	ivon_server_config_t	config,
		uint64_t	ms
	)

Set periodic key rotation interval in milliseconds (0 = disabled).

ivon_server_config_set_key_rotation_on_leave()

void ivon_server_config_set_key_rotation_on_leave	(	ivon_server_config_t	config,
		int	enabled
	)

Rotate group keys when a member leaves (default true).

ivon_server_config_set_keys()

int ivon_server_config_set_keys	(	ivon_server_config_t	config,
		const uint8_t *	public_key,
		size_t	public_key_len,
		const uint8_t *	private_key,
		size_t	private_key_len
	)

Set raw key material for server identity.

Parameters

public_key	Public key bytes.
public_key_len	Must be IVON_SERVER_PUBLIC_KEY_SIZE.
private_key	Private key bytes.
private_key_len	Must be IVON_SERVER_PRIVATE_KEY_SIZE.

Returns

Non-zero on success, zero on invalid key size.

ivon_server_config_set_max_password_attempts()

void ivon_server_config_set_max_password_attempts	(	ivon_server_config_t	config,
		uint32_t	max_attempts
	)

Set the maximum password attempts before rejection (default 3).

ivon_server_config_set_network_interface()

void ivon_server_config_set_network_interface	(	ivon_server_config_t	config,
		const char *	iface
	)

Bind to a specific network interface (Linux only, e.g. "eth0").

ivon_server_config_set_num_threads()

void ivon_server_config_set_num_threads	(	ivon_server_config_t	config,
		size_t	num_threads
	)

Set the number of IO threads (default 1).

ivon_server_config_set_on_client_approve()

void ivon_server_config_set_on_client_approve	(	ivon_server_config_t	config,
		ivon_server_client_approve_fn	callback,
		void *	user_data
	)

Set the client approval callback.

See also

ivon_server_client_approve_fn

ivon_server_config_set_on_client_connected()

void ivon_server_config_set_on_client_connected	(	ivon_server_config_t	config,
		ivon_server_client_connected_fn	callback,
		void *	user_data
	)

Set the client connected event callback.

See also

ivon_server_client_connected_fn

ivon_server_config_set_on_client_disconnected()

void ivon_server_config_set_on_client_disconnected	(	ivon_server_config_t	config,
		ivon_server_client_disconnected_fn	callback,
		void *	user_data
	)

Set the client disconnected event callback.

See also

ivon_server_client_disconnected_fn

ivon_server_config_set_on_client_id_check()

void ivon_server_config_set_on_client_id_check	(	ivon_server_config_t	config,
		ivon_server_client_id_check_fn	callback,
		void *	user_data
	)

Set the client ID validation callback.

See also

ivon_server_client_id_check_fn

ivon_server_config_set_on_connection_admission()

void ivon_server_config_set_on_connection_admission	(	ivon_server_config_t	config,
		ivon_server_connection_admission_fn	callback,
		void *	user_data
	)

Set the connection admission gate callback.

See also

ivon_server_connection_admission_fn

ivon_server_config_set_on_group_join_authorize()

void ivon_server_config_set_on_group_join_authorize	(	ivon_server_config_t	config,
		ivon_server_group_join_authorize_fn	callback,
		void *	user_data
	)

Set the group join authorization callback.

See also

ivon_server_group_join_authorize_fn

ivon_server_config_set_on_password_validate()

void ivon_server_config_set_on_password_validate	(	ivon_server_config_t	config,
		ivon_server_password_validate_fn	callback,
		void *	user_data
	)

Set the password validation callback.

See also

ivon_server_password_validate_fn

ivon_server_config_set_password()

void ivon_server_config_set_password	(	ivon_server_config_t	config,
		const char *	password
	)

Set the expected password.

ivon_server_config_set_port()

void ivon_server_config_set_port	(	ivon_server_config_t	config,
		uint16_t	port
	)

Set the listening port (default 9129).

ivon_server_config_set_property()

void ivon_server_config_set_property	(	ivon_server_config_t	config,
		const char *	key,
		const void *	value,
		size_t	value_len
	)

Set a server-level property on the config (before server creation).

Properties set here will be delivered to clients during initial sync.

Parameters

config	The config handle.
key	Null-terminated property key.
value	Property value bytes.
value_len	Length of the value in bytes.

ivon_server_config_set_require_password()

void ivon_server_config_set_require_password	(	ivon_server_config_t	config,
		int	require
	)

Require clients to authenticate with a password (default false).

ivon_server_create()

ivon_server_t ivon_server_create

(

ivon_server_config_t

config

)

Create a new server instance from a populated config.

Moves configuration data out of the config handle. The config handle should be destroyed with ivon_server_config_destroy() after this call regardless of success or failure.

Parameters

config

A populated config handle.

Returns

A new server handle, or NULL on failure.

ivon_server_create_group()

int ivon_server_create_group	(	ivon_server_t	server,
		const char *	group_id
	)

Create a new group.

Returns

Non-zero on success, zero if the group already exists.

ivon_server_delete_group()

void ivon_server_delete_group	(	ivon_server_t	server,
		const char *	group_id,
		ivon_server_bool_callback_fn	callback,
		void *	user_data
	)

Delete a group (asynchronous).

Parameters

callback	Optional completion callback (may be NULL).
user_data	Passed through to the callback.

ivon_server_destroy()

void ivon_server_destroy

(

ivon_server_t

server

)

Destroy a server instance and free all resources.

Stops the server if still running, then frees all resources. Passing NULL is a safe no-op.

ivon_server_for_each_group()

void ivon_server_for_each_group	(	ivon_server_t	server,
		ivon_string_iterator_fn	callback,
		void *	user_data
	)

Iterate over all group IDs.

Calls callback once per group with the group ID string. The string is valid only for the duration of the callback.

Parameters

callback	Visitor function called for each group.
user_data	Passed through to the callback.

ivon_server_has_group()

int ivon_server_has_group	(	ivon_server_t	server,
		const char *	group_id
	)

Check if a group exists.

Returns

Non-zero if the group exists, zero otherwise.

ivon_server_kick_client()

void ivon_server_kick_client	(	ivon_server_t	server,
		const char *	client_id,
		const char *	reason
	)

Kick a client from the server.

Parameters

reason

Human-readable reason (may be empty).

ivon_server_kick_client_from_group()

void ivon_server_kick_client_from_group	(	ivon_server_t	server,
		const char *	group_id,
		const char *	client_id,
		const char *	reason,
		ivon_server_bool_callback_fn	callback,
		void *	user_data
	)

Kick a client from a specific group (asynchronous).

Parameters

callback	Optional completion callback (may be NULL).
user_data	Passed through to the callback.

ivon_server_rotate_group_key()

int32_t ivon_server_rotate_group_key	(	ivon_server_t	server,
		const char *	group_id
	)

Rotate the encryption key for a group.

Returns

The new epoch on success, -1 on failure.

ivon_server_run()

void ivon_server_run

(

ivon_server_t

server

)

Run the server (blocks until stop() is called).

Parameters

server

The server handle.

ivon_server_send_message_to_all()

void ivon_server_send_message_to_all	(	ivon_server_t	server,
		const char *	data_type,
		const void *	data,
		size_t	data_len
	)

Broadcast a message from the server to all connected clients.

Parameters

server	The server handle.
data_type	Application-level type tag (e.g. "chat.message").
data	Payload bytes.
data_len	Length of the payload in bytes.

ivon_server_send_message_to_client()

void ivon_server_send_message_to_client	(	ivon_server_t	server,
		const char *	client_id,
		const char *	data_type,
		const void *	data,
		size_t	data_len
	)

Send a message from the server to a specific client.

Parameters

server	The server handle.
client_id	The recipient client ID.
data_type	Application-level type tag (e.g. "chat.message").
data	Payload bytes.
data_len	Length of the payload in bytes.

ivon_server_send_message_to_group()

void ivon_server_send_message_to_group	(	ivon_server_t	server,
		const char *	group_id,
		const char *	data_type,
		const void *	data,
		size_t	data_len
	)

Send a message from the server to all members of a group.

Parameters

server	The server handle.
group_id	The target group ID.
data_type	Application-level type tag (e.g. "chat.message").
data	Payload bytes.
data_len	Length of the payload in bytes.

ivon_server_set_group_property()

void ivon_server_set_group_property	(	ivon_server_t	server,
		const char *	group_id,
		const char *	key,
		const void *	value,
		size_t	value_len
	)

Set a group-level property.

Stores the property on the group and pushes a GROUP_PROPERTY_UPDATE to all current group members. Clients joining later receive the current properties in the GROUP_JOIN_RESPONSE.

Parameters

server	The server handle.
group_id	The target group ID.
key	Null-terminated property key.
value	Property value bytes.
value_len	Length of the value in bytes.

ivon_server_set_on_client_approve()

void ivon_server_set_on_client_approve	(	ivon_server_t	server,
		ivon_server_client_approve_fn	callback,
		void *	user_data
	)

Set or replace the client approval callback on a live server.

See also

ivon_server_client_approve_fn

ivon_server_set_on_client_connected()

void ivon_server_set_on_client_connected	(	ivon_server_t	server,
		ivon_server_client_connected_fn	callback,
		void *	user_data
	)

Set or replace the client connected event callback on a live server.

See also

ivon_server_client_connected_fn

ivon_server_set_on_client_disconnected()

void ivon_server_set_on_client_disconnected	(	ivon_server_t	server,
		ivon_server_client_disconnected_fn	callback,
		void *	user_data
	)

Set or replace the client disconnected event callback on a live server.

See also

ivon_server_client_disconnected_fn

ivon_server_set_on_client_id_check()

void ivon_server_set_on_client_id_check	(	ivon_server_t	server,
		ivon_server_client_id_check_fn	callback,
		void *	user_data
	)

Set or replace the client ID validation callback on a live server.

See also

ivon_server_client_id_check_fn

ivon_server_set_on_connection_admission()

void ivon_server_set_on_connection_admission	(	ivon_server_t	server,
		ivon_server_connection_admission_fn	callback,
		void *	user_data
	)

Set or replace the connection admission gate on a live server.

See also

ivon_server_connection_admission_fn

ivon_server_set_on_group_join_authorize()

void ivon_server_set_on_group_join_authorize	(	ivon_server_t	server,
		ivon_server_group_join_authorize_fn	callback,
		void *	user_data
	)

Set or replace the group join authorization callback on a live server.

See also

ivon_server_group_join_authorize_fn

ivon_server_set_on_password_validate()

void ivon_server_set_on_password_validate	(	ivon_server_t	server,
		ivon_server_password_validate_fn	callback,
		void *	user_data
	)

Set or replace the password validation callback on a live server.

See also

ivon_server_password_validate_fn

ivon_server_set_property()

void ivon_server_set_property	(	ivon_server_t	server,
		const char *	key,
		const void *	value,
		size_t	value_len
	)

Set a server-level property.

Stores the property and pushes a SERVER_PROPERTY_UPDATE to all currently connected clients. New clients receive all current server properties during sync.

Parameters

server	The server handle.
key	Null-terminated property key.
value	Property value bytes.
value_len	Length of the value in bytes.

ivon_server_stop()

void ivon_server_stop

(

ivon_server_t

server

)

Stop the server (thread-safe, causes run() to return).

Parameters

server

The server handle.