ivon_client_types.h File Reference

#include "libivon/public/ivon_common_types.h"
#include <stddef.h>
#include <stdint.h>

Classes
struct	ivon_connect_result
	Result of a connect() call. More...
struct	ivon_property
	A single key-value property pair for iteration. More...
struct	ivon_group_join_result
	Result of a group join operation. More...
struct	ivon_group_leave_result
	Result of a group leave operation. More...
struct	ivon_group_mute_result
	Result of a mute operation. More...
struct	ivon_group_info
	Information about a group (used in group list callback). More...

Macros
#define	IVON_PUBLIC_KEY_SIZE   32
	PUBLIC_KEY_SIZE from the C++ side.

Typedefs
typedef struct ivon_client *	ivon_client_t
	C ABI types for the libivon client.
typedef enum ivon_connection_state	ivon_connection_state_t
	Connection lifecycle states (mirrors ConnectionState).
typedef enum ivon_tofu_verify_result	ivon_tofu_verify_result_t
	TOFU verification results (mirrors TofuVerifyResult).
typedef enum ivon_negotiation_error_code	ivon_negotiation_error_code_t
	Negotiation error codes (mirrors NegotiationErrorCode).
typedef enum ivon_connection_error_code	ivon_connection_error_code_t
	Connection error codes (mirrors ConnectionErrorCode).
typedef enum ivon_group_operation_status	ivon_group_operation_status_t
	Group operation status codes (mirrors GroupOperationStatus).
typedef struct ivon_client_config *	ivon_client_config_t
	Opaque client configuration handle.
typedef struct ivon_connect_result	ivon_connect_result_t
	Result of a connect() call.
typedef struct ivon_property	ivon_property_t
	A single key-value property pair for iteration.
typedef struct ivon_group_join_result	ivon_group_join_result_t
	Result of a group join operation.
typedef struct ivon_group_leave_result	ivon_group_leave_result_t
	Result of a group leave operation.
typedef struct ivon_group_mute_result	ivon_group_mute_result_t
	Result of a mute operation.
typedef struct ivon_group_info	ivon_group_info_t
	Information about a group (used in group list callback).
typedef int(*	ivon_tofu_verify_fn) (const char *server_id, ivon_tofu_verify_result_t result, const uint8_t server_public_key[IVON_PUBLIC_KEY_SIZE], const uint8_t *stored_key, void *user_data)
	TOFU verification callback. Return non-zero to accept the key, zero to reject.
typedef int(*	ivon_password_fn) (uint32_t remaining_attempts, char *password_buf, size_t buf_len, void *user_data)
	Password callback. Write the password into password_buf (max buf_len bytes including NUL). Return non-zero to submit, zero to cancel authentication.
typedef void(*	ivon_client_message_fn) (const char *sender_id, const char *data_type, const uint8_t *data, size_t data_len, void *user_data)
	Client message callback.
typedef void(*	ivon_client_joined_fn) (const char *client_id, void *user_data)
	Client joined callback.
typedef void(*	ivon_client_left_fn) (const char *client_id, int was_kicked, void *user_data)
	Client left callback.
typedef void(*	ivon_kicked_fn) (const char *reason, void *user_data)
	Kicked callback (this client was kicked).
typedef void(*	ivon_disconnected_fn) (const char *reason, void *user_data)
	Disconnected callback.
typedef void(*	ivon_connection_state_fn) (ivon_connection_state_t new_state, void *user_data)
	Connection state changed callback.
typedef void(*	ivon_group_join_fn) (const ivon_group_join_result_t *result, void *user_data)
	Group join result callback.
typedef void(*	ivon_group_leave_fn) (const ivon_group_leave_result_t *result, void *user_data)
	Group leave result callback.
typedef void(*	ivon_group_key_update_fn) (const char *group_id, uint64_t new_epoch, void *user_data)
	Group key update callback.
typedef void(*	ivon_group_member_joined_fn) (const char *group_id, const char *client_id, uint64_t fanout_sender_id, void *user_data)
	Group member joined callback.
typedef void(*	ivon_group_member_left_fn) (const char *group_id, const char *client_id, uint64_t fanout_sender_id, int was_kicked, void *user_data)
	Group member left callback.
typedef void(*	ivon_group_kicked_fn) (const char *group_id, const char *reason, void *user_data)
	Group kicked callback (this client kicked from a group).
typedef void(*	ivon_group_list_fn) (const ivon_group_info_t *groups, size_t count, void *user_data)
	Group list callback.
typedef void(*	ivon_group_mute_fn) (const ivon_group_mute_result_t *result, void *user_data)
	Group mute result callback.
typedef void(*	ivon_fanout_data_fn) (const char *group_id, uint64_t sender_id, uint64_t seq, const unsigned char *data, size_t data_len, void *user_data)
	Fanout data received callback.
typedef void(*	ivon_fanout_error_fn) (const char *group_id, const char *error_message, void *user_data)
	Fanout error callback.
typedef void(*	ivon_server_properties_fn) (const ivon_property_t *properties, size_t count, void *user_data)
	Server properties callback (called once during sync).
typedef void(*	ivon_server_property_update_fn) (const char *key, const uint8_t *value, size_t value_len, void *user_data)
	Server property update callback (single property changed).
typedef void(*	ivon_group_property_update_fn) (const char *group_id, const char *key, const uint8_t *value, size_t value_len, void *user_data)
	Group property update callback (single group property changed).

Enumerations
enum	ivon_connection_state {   IVON_CONNECTION_STATE_DISCONNECTED = 0 , IVON_CONNECTION_STATE_CONNECTING = 1 , IVON_CONNECTION_STATE_NEGOTIATING = 2 , IVON_CONNECTION_STATE_SYNCHRONIZING = 3 ,   IVON_CONNECTION_STATE_CONNECTED = 4 , IVON_CONNECTION_STATE_DISCONNECTING = 5 }
	Connection lifecycle states (mirrors ConnectionState). More...
enum	ivon_tofu_verify_result { IVON_TOFU_TRUSTED = 0 , IVON_TOFU_NEW_KEY = 1 , IVON_TOFU_KEY_CHANGED = 2 , IVON_TOFU_VERIFICATION_ERROR = 3 }
	TOFU verification results (mirrors TofuVerifyResult). More...
enum	ivon_negotiation_error_code {   IVON_NEGOTIATION_SUCCESS = 0 , IVON_NEGOTIATION_PROTOCOL_VERSION_MISMATCH = 1 , IVON_NEGOTIATION_INVALID_PUBLIC_KEY = 20 , IVON_NEGOTIATION_KEY_GENERATION_FAILED = 21 ,   IVON_NEGOTIATION_KEY_DERIVATION_FAILED = 22 , IVON_NEGOTIATION_INVALID_KEY_SIZE = 23 , IVON_NEGOTIATION_NONCE_REUSE_DETECTED = 24 , IVON_NEGOTIATION_AUTHENTICATION_FAILED = 40 ,   IVON_NEGOTIATION_UNKNOWN_PEER = 41 , IVON_NEGOTIATION_PEER_REJECTED = 42 , IVON_NEGOTIATION_CERTIFICATE_EXPIRED = 43 , IVON_NEGOTIATION_CERTIFICATE_REVOKED = 44 ,   IVON_NEGOTIATION_CLIENT_ID_REJECTED = 50 , IVON_NEGOTIATION_CLIENT_NOT_APPROVED = 51 , IVON_NEGOTIATION_UNKNOWN = 255 }
	Negotiation error codes (mirrors NegotiationErrorCode). More...
enum	ivon_connection_error_code {   IVON_CONNECTION_SUCCESS = 0 , IVON_CONNECTION_CLOSED = 1 , IVON_CONNECTION_TIMEOUT = 2 , IVON_CONNECTION_RESET = 3 ,   IVON_CONNECTION_NETWORK_ERROR = 4 , IVON_CONNECTION_CANCELED = 5 , IVON_CONNECTION_INVALID_MSG_FORMAT = 20 , IVON_CONNECTION_UNEXPECTED_MSG = 21 ,   IVON_CONNECTION_MSG_TOO_LARGE = 22 , IVON_CONNECTION_MSG_TOO_SMALL = 23 , IVON_CONNECTION_ENCRYPTION_FAILED = 40 , IVON_CONNECTION_DECRYPTION_FAILED = 41 ,   IVON_CONNECTION_SIGNATURE_INVALID = 42 , IVON_CONNECTION_MAC_VERIFY_FAILED = 43 , IVON_CONNECTION_INTERNAL_ERROR = 60 , IVON_CONNECTION_OUT_OF_MEMORY = 61 ,   IVON_CONNECTION_STATE_ERROR = 62 , IVON_CONNECTION_UNKNOWN = 255 }
	Connection error codes (mirrors ConnectionErrorCode). More...
enum	ivon_group_operation_status {   IVON_GROUP_STATUS_SUCCESS = 0 , IVON_GROUP_STATUS_GROUP_NOT_FOUND = 1 , IVON_GROUP_STATUS_GROUP_FULL = 2 , IVON_GROUP_STATUS_PERMISSION_DENIED = 3 ,   IVON_GROUP_STATUS_ALREADY_MEMBER = 4 , IVON_GROUP_STATUS_NOT_MEMBER = 5 , IVON_GROUP_STATUS_INVALID_GROUP_ID = 6 , IVON_GROUP_STATUS_CONNECTION_ERROR = 7 ,   IVON_GROUP_STATUS_INTERNAL_ERROR = 8 , IVON_GROUP_STATUS_KICKED = 9 }
	Group operation status codes (mirrors GroupOperationStatus). More...

Macro Definition Documentation

IVON_PUBLIC_KEY_SIZE

#define IVON_PUBLIC_KEY_SIZE   32

PUBLIC_KEY_SIZE from the C++ side.

Typedef Documentation

ivon_client_config_t

typedef struct ivon_client_config* ivon_client_config_t

Opaque client configuration handle.

Create with ivon_client_config_create(), set fields with the ivon_client_config_set_*() functions, pass to ivon_client_create(), then destroy with ivon_client_config_destroy().

ivon_client_joined_fn

typedef void(* ivon_client_joined_fn) (const char *client_id, void *user_data)

Client joined callback.

ivon_client_left_fn

typedef void(* ivon_client_left_fn) (const char *client_id, int was_kicked, void *user_data)

Client left callback.

ivon_client_message_fn

typedef void(* ivon_client_message_fn) (const char *sender_id, const char *data_type, const uint8_t *data, size_t data_len, void *user_data)

Client message callback.

ivon_client_t

typedef struct ivon_client* ivon_client_t

C ABI types 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

Pure C header — no C++ dependencies. Defines the opaque handle, enumerations, result structures, and callback function-pointer typedefs used by ivon_client.h.

Opaque handle to a libivon client instance.

ivon_connect_result_t

typedef struct ivon_connect_result ivon_connect_result_t

Result of a connect() call.

If success is non-zero the connection is established. Otherwise inspect is_connection_error, negotiation_code / connection_code and the message/detail fields.

ivon_connection_error_code_t

typedef enum ivon_connection_error_code ivon_connection_error_code_t

Connection error codes (mirrors ConnectionErrorCode).

ivon_connection_state_fn

typedef void(* ivon_connection_state_fn) (ivon_connection_state_t new_state, void *user_data)

Connection state changed callback.

ivon_connection_state_t

typedef enum ivon_connection_state ivon_connection_state_t

Connection lifecycle states (mirrors ConnectionState).

ivon_disconnected_fn

typedef void(* ivon_disconnected_fn) (const char *reason, void *user_data)

Disconnected callback.

ivon_fanout_data_fn

typedef void(* ivon_fanout_data_fn) (const char *group_id, uint64_t sender_id, uint64_t seq, const unsigned char *data, size_t data_len, void *user_data)

Fanout data received callback.

ivon_fanout_error_fn

typedef void(* ivon_fanout_error_fn) (const char *group_id, const char *error_message, void *user_data)

Fanout error callback.

ivon_group_info_t

typedef struct ivon_group_info ivon_group_info_t

Information about a group (used in group list callback).

ivon_group_join_fn

typedef void(* ivon_group_join_fn) (const ivon_group_join_result_t *result, void *user_data)

Group join result callback.

ivon_group_join_result_t

typedef struct ivon_group_join_result ivon_group_join_result_t

Result of a group join operation.

ivon_group_key_update_fn

typedef void(* ivon_group_key_update_fn) (const char *group_id, uint64_t new_epoch, void *user_data)

Group key update callback.

ivon_group_kicked_fn

typedef void(* ivon_group_kicked_fn) (const char *group_id, const char *reason, void *user_data)

Group kicked callback (this client kicked from a group).

ivon_group_leave_fn

typedef void(* ivon_group_leave_fn) (const ivon_group_leave_result_t *result, void *user_data)

Group leave result callback.

ivon_group_leave_result_t

typedef struct ivon_group_leave_result ivon_group_leave_result_t

Result of a group leave operation.

ivon_group_list_fn

typedef void(* ivon_group_list_fn) (const ivon_group_info_t *groups, size_t count, void *user_data)

Group list callback.

Parameters

groups	Array of group info structs, valid for the duration of the call.
count	Number of elements in groups.

ivon_group_member_joined_fn

typedef void(* ivon_group_member_joined_fn) (const char *group_id, const char *client_id, uint64_t fanout_sender_id, void *user_data)

Group member joined callback.

ivon_group_member_left_fn

typedef void( * ivon_group_member_left_fn) (const char *group_id, const char *client_id, uint64_t fanout_sender_id, int was_kicked, void *user_data)

Group member left callback.

ivon_group_mute_fn

typedef void(* ivon_group_mute_fn) (const ivon_group_mute_result_t *result, void *user_data)

Group mute result callback.

ivon_group_mute_result_t

typedef struct ivon_group_mute_result ivon_group_mute_result_t

Result of a mute operation.

ivon_group_operation_status_t

typedef enum ivon_group_operation_status ivon_group_operation_status_t

Group operation status codes (mirrors GroupOperationStatus).

ivon_group_property_update_fn

typedef void( * ivon_group_property_update_fn) (const char *group_id, const char *key, const uint8_t *value, size_t value_len, void *user_data)

Group property update callback (single group property changed).

ivon_kicked_fn

typedef void(* ivon_kicked_fn) (const char *reason, void *user_data)

Kicked callback (this client was kicked).

ivon_negotiation_error_code_t

typedef enum ivon_negotiation_error_code ivon_negotiation_error_code_t

Negotiation error codes (mirrors NegotiationErrorCode).

ivon_password_fn

typedef int(* ivon_password_fn) (uint32_t remaining_attempts, char *password_buf, size_t buf_len, void *user_data)

Password callback. Write the password into password_buf (max buf_len bytes including NUL). Return non-zero to submit, zero to cancel authentication.

ivon_property_t

typedef struct ivon_property ivon_property_t

A single key-value property pair for iteration.

ivon_server_properties_fn

typedef void(* ivon_server_properties_fn) (const ivon_property_t *properties, size_t count, void *user_data)

Server properties callback (called once during sync).

Parameters

properties	Array of property pairs.
count	Number of properties.

ivon_server_property_update_fn

typedef void(* ivon_server_property_update_fn) (const char *key, const uint8_t *value, size_t value_len, void *user_data)

Server property update callback (single property changed).

ivon_tofu_verify_fn

typedef int(* ivon_tofu_verify_fn) (const char *server_id, ivon_tofu_verify_result_t result, const uint8_t server_public_key[IVON_PUBLIC_KEY_SIZE], const uint8_t *stored_key, void *user_data)

TOFU verification callback. Return non-zero to accept the key, zero to reject.

ivon_tofu_verify_result_t

typedef enum ivon_tofu_verify_result ivon_tofu_verify_result_t

TOFU verification results (mirrors TofuVerifyResult).

Enumeration Type Documentation

ivon_connection_error_code

enum ivon_connection_error_code

Connection error codes (mirrors ConnectionErrorCode).

Enumerator
IVON_CONNECTION_SUCCESS
IVON_CONNECTION_CLOSED
IVON_CONNECTION_TIMEOUT
IVON_CONNECTION_RESET
IVON_CONNECTION_NETWORK_ERROR
IVON_CONNECTION_CANCELED
IVON_CONNECTION_INVALID_MSG_FORMAT
IVON_CONNECTION_UNEXPECTED_MSG
IVON_CONNECTION_MSG_TOO_LARGE
IVON_CONNECTION_MSG_TOO_SMALL
IVON_CONNECTION_ENCRYPTION_FAILED
IVON_CONNECTION_DECRYPTION_FAILED
IVON_CONNECTION_SIGNATURE_INVALID
IVON_CONNECTION_MAC_VERIFY_FAILED
IVON_CONNECTION_INTERNAL_ERROR
IVON_CONNECTION_OUT_OF_MEMORY
IVON_CONNECTION_STATE_ERROR
IVON_CONNECTION_UNKNOWN

ivon_connection_state

enum ivon_connection_state

Connection lifecycle states (mirrors ConnectionState).

Enumerator
IVON_CONNECTION_STATE_DISCONNECTED
IVON_CONNECTION_STATE_CONNECTING
IVON_CONNECTION_STATE_NEGOTIATING
IVON_CONNECTION_STATE_SYNCHRONIZING
IVON_CONNECTION_STATE_CONNECTED
IVON_CONNECTION_STATE_DISCONNECTING

ivon_group_operation_status

enum ivon_group_operation_status

Group operation status codes (mirrors GroupOperationStatus).

Enumerator
IVON_GROUP_STATUS_SUCCESS
IVON_GROUP_STATUS_GROUP_NOT_FOUND
IVON_GROUP_STATUS_GROUP_FULL
IVON_GROUP_STATUS_PERMISSION_DENIED
IVON_GROUP_STATUS_ALREADY_MEMBER
IVON_GROUP_STATUS_NOT_MEMBER
IVON_GROUP_STATUS_INVALID_GROUP_ID
IVON_GROUP_STATUS_CONNECTION_ERROR
IVON_GROUP_STATUS_INTERNAL_ERROR
IVON_GROUP_STATUS_KICKED

ivon_negotiation_error_code

enum ivon_negotiation_error_code

Negotiation error codes (mirrors NegotiationErrorCode).

Enumerator
IVON_NEGOTIATION_SUCCESS
IVON_NEGOTIATION_PROTOCOL_VERSION_MISMATCH
IVON_NEGOTIATION_INVALID_PUBLIC_KEY
IVON_NEGOTIATION_KEY_GENERATION_FAILED
IVON_NEGOTIATION_KEY_DERIVATION_FAILED
IVON_NEGOTIATION_INVALID_KEY_SIZE
IVON_NEGOTIATION_NONCE_REUSE_DETECTED
IVON_NEGOTIATION_AUTHENTICATION_FAILED
IVON_NEGOTIATION_UNKNOWN_PEER
IVON_NEGOTIATION_PEER_REJECTED
IVON_NEGOTIATION_CERTIFICATE_EXPIRED
IVON_NEGOTIATION_CERTIFICATE_REVOKED
IVON_NEGOTIATION_CLIENT_ID_REJECTED
IVON_NEGOTIATION_CLIENT_NOT_APPROVED
IVON_NEGOTIATION_UNKNOWN

ivon_tofu_verify_result

enum ivon_tofu_verify_result

TOFU verification results (mirrors TofuVerifyResult).

Enumerator
IVON_TOFU_TRUSTED
IVON_TOFU_NEW_KEY
IVON_TOFU_KEY_CHANGED
IVON_TOFU_VERIFICATION_ERROR