ivon Namespace Reference

Public C++ type definitions shared across libivon interfaces and consumer-side wrappers. More...

Classes
struct	AudioOutputFrame
	Structured output frame info returned by audio read operations. More...
class	AudioWrapper
	Consumer-facing C++ wrapper around the libivon audio C ABI. More...
class	ClientWrapper
	Consumer-facing C++ wrapper around the libivon C ABI. More...
class	expected_void
	Lightweight C++20-compatible replacement for std::expected<void, E>. More...
struct	GroupInfo
	Information about a group available on the server. More...
struct	GroupJoinResult
	Result of a group join operation. More...
struct	GroupLeaveResult
	Result of a group leave operation. More...
struct	GroupMuteResult
	Result of a mute operation. More...
class	IAudio
	Pure virtual interface for the libivon audio processor. More...
class	IClient
	Pure virtual interface for the libivon client. More...
class	IServer
	Pure virtual interface for the libivon server. More...
class	NegotiationError
	Composite error type for key negotiation failures. More...
class	ServerWrapper
	RAII wrapper around the libivon server C ABI. More...
class	VoiceSessionWrapper
	Consumer-facing C++ wrapper around the voice session C ABI. More...

Typedefs
using	TofuVerifyCallback = std::function< bool(const std::string &server_id, TofuVerifyResult result, const std::array< uint8_t, PUBLIC_KEY_SIZE > &server_public_key, const std::optional< std::array< uint8_t, PUBLIC_KEY_SIZE > > &stored_key)>
	Called when a new or changed server key is encountered (TOFU).
using	PasswordCallback = std::function< std::optional< std::string >(uint32_t remaining_attempts)>
	Called when the server requires password authentication.
using	ConnectionStateCallback = std::function< void(ConnectionState new_state)>
	Called when the connection lifecycle state changes.
using	ClientMessageCallback = std::function< void(const std::string &sender_id, const std::string &data_type, std::span< const uint8_t > data)>
	Called when a direct or broadcast message arrives from another client.
using	ClientJoinedCallback = std::function< void(const std::string &client_id)>
	Called when a remote client joins the server session.
using	ClientLeftCallback = std::function< void(const std::string &client_id, bool was_kicked)>
	Called when a remote client leaves the server session.
using	KickedCallback = std::function< void(const std::string &reason)>
	Called when THIS client is kicked from the server.
using	DisconnectedCallback = std::function< void(const std::string &reason)>
	Called when the connection to the server is lost or closed.
using	GroupJoinCallback = std::function< void(const GroupJoinResult &result)>
	Called when a join_group() request completes.
using	GroupLeaveCallback = std::function< void(const GroupLeaveResult &result)>
	Called when a leave_group() request completes.
using	GroupKeyUpdateCallback = std::function< void(const std::string &group_id, uint64_t new_epoch)>
	Called when a group's encryption key is rotated.
using	GroupMemberJoinedCallback = std::function< void(const std::string &group_id, const std::string &client_id, uint64_t fanout_sender_id)>
	Called when another client joins a group we are a member of.
using	GroupMemberLeftCallback = std::function< void(const std::string &group_id, const std::string &client_id, uint64_t fanout_sender_id, bool was_kicked)>
	Called when another client leaves a group we are a member of.
using	GroupKickedCallback = std::function< void(const std::string &group_id, const std::string &reason)>
	Called when THIS client is kicked from a group by the server.
using	GroupListCallback = std::function< void(const std::vector< GroupInfo > &groups)>
	Called when the server responds to a request_group_list() call.
using	GroupMuteCallback = std::function< void(const GroupMuteResult &result)>
	Called when a set_mute() request completes.
using	FanoutDataCallback = std::function< void(const std::string &group_id, uint64_t sender_id, uint64_t seq, const unsigned char *data, size_t len)>
	Called when decrypted fanout data arrives from a group member.
using	FanoutErrorCallback = std::function< void(const std::string &group_id, const std::string &error_message)>
	Called when a fanout client encounters a fatal error.
using	PcmSourceCallback = std::function< bool(std::span< float > pcm_out)>
	Callback type for pulling PCM audio during transmission.
using	ServerPropertiesCallback = std::function< void(const std::unordered_map< std::string, std::vector< uint8_t > > &properties)>
	Called when all server-level properties are received during sync.
using	ServerPropertyUpdateCallback = std::function< void(const std::string &key, const std::vector< uint8_t > &value)>
	Called when a single server-level property changes.
using	GroupPropertyUpdateCallback = std::function< void(const std::string &group_id, const std::string &key, const std::vector< uint8_t > &value)>
	Called when a single group-level property changes.

Enumerations
enum class	ConnectionState : uint8_t {   disconnected = 0 , connecting = 1 , negotiating = 2 , synchronizing = 3 ,   connected = 4 , disconnecting = 5 }
	Lifecycle states of a Client connection. More...
enum class	ConnectionErrorCode : uint8_t {   success = 0 , connection_closed = 1 , connection_timeout = 2 , connection_reset = 3 ,   network_error = 4 , connection_canceled = 5 , invalid_message_format = 20 , unexpected_message = 21 ,   message_too_large = 22 , message_too_small = 23 , encryption_failed = 40 , decryption_failed = 41 ,   signature_invalid = 42 , mac_verification_failed = 43 , internal_error = 60 , out_of_memory = 61 ,   state_error = 62 , unknown = 255 }
	Error codes for general connection/communication failures. More...
enum class	NegotiationErrorCode : uint8_t {   success = 0 , protocol_version_mismatch = 1 , invalid_public_key = 20 , key_generation_failed = 21 ,   key_derivation_failed = 22 , invalid_key_size = 23 , nonce_reuse_detected = 24 , authentication_failed = 40 ,   unknown_peer = 41 , peer_rejected = 42 , certificate_expired = 43 , certificate_revoked = 44 ,   client_id_rejected = 50 , client_not_approved = 51 , unknown = 255 }
	Error codes specific to the key negotiation/handshake phase. More...
enum class	TofuVerifyResult { trusted , new_key , key_changed , verification_error }
	Result of TOFU (Trust-On-First-Use) key verification. More...
enum class	GroupOperationStatus : uint8_t {   Success , GroupNotFound , GroupFull , PermissionDenied ,   AlreadyMember , NotMember , InvalidGroupId , ConnectionError ,   InternalError , Kicked }
	Status codes for group operations. More...

Functions
constexpr const char *	connection_error_message (ConnectionErrorCode code) noexcept
	Get a human-readable description of a connection error code.
constexpr const char *	negotiation_error_message (NegotiationErrorCode code) noexcept
	Get a human-readable description of a negotiation error code.

Variables
constexpr size_t	PUBLIC_KEY_SIZE = 32
	Size of a public key in bytes.

Detailed Description

Public C++ type definitions shared across libivon interfaces and consumer-side wrappers.

Consumer-side C++ wrapper over the libivon voice session C ABI.

Consumer-side C++ wrapper over the libivon server C ABI.

Public pure-virtual interface for the libivon server.

Consumer-side C++ wrapper over the libivon C ABI.

Public pure-virtual interface for the libivon client.

Consumer-side C++ wrapper over the libivon audio C ABI.

Public pure-virtual interface for the libivon audio processor.

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

This header defines the canonical C++ types for the libivon public API surface: enumerations, result structures, error types, and callback type aliases. Both the internal implementations and the consumer-side wrappers use these types, ensuring compile-time parity.

Uses only the C++ standard library — no internal libivon headers.

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

IAudio defines every public operation that the audio C ABI must mirror. The consumer-side C++ wrapper (AudioWrapper) derives from this interface, giving compile-time enforcement that the C ABI surface stays in sync with the C++ API.

The internal AudioProcessor does NOT derive from IAudio — it uses a richer zero-copy API with pool-allocated buffers. The C ABI layer adapts between the internal and public interfaces.

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

This header-only class provides a convenient C++ API for consumers of the libivon shared library. It depends only on the C ABI header (ivon_audio.h) and the C++ standard library — no Opus, no internal headers, no pool types cross the ABI boundary.

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

IClient defines every public operation that the C ABI must mirror. Both the real Client implementation and the consumer-side C++ wrapper derive from this interface, giving compile-time enforcement that the C ABI surface stays in sync with the C++ API.

Methods that are purely internal (send_message with protobuf types, send_message_raw) are intentionally excluded — they are not part of the public ABI contract.

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

This header-only class provides a convenient C++ API for consumers of the libivon shared library. It depends only on the C ABI header (ivon_client.h) and the C++ standard library — no asio, no protobuf, no internal headers cross the ABI boundary.

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

IServer defines every public operation that the server C ABI must mirror. Both the real Server implementation and the consumer-side C++ wrapper derive from this interface, giving compile-time enforcement that the C ABI surface stays in sync with the C++ API.

Internal methods (accept_connections, handle_connection) are not part of the public ABI contract and are intentionally excluded.

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

Header-only. Depends only on the C ABI headers (ivon_server.h / ivon_server_types.h) — no internal libivon headers required.

Provides ServerWrapper (RAII, non-moveable) and ServerWrapper::Config (builder-style) that mirror the internal Server / ServerConfig classes but communicate exclusively through the C ABI.

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

This header-only class provides a convenient C++ API for consumers of the libivon shared library. It depends only on the C ABI headers (ivon_voice_session.h, ivon_client.h) and the C++ standard library.

The voice session bundles a client connection and audio processor:

• Zero-copy fanout → audio decoder routing (internal)
• Automatic sender registration/unregistration
• Internal encoder drain worker thread

The consumer provides PCM via a callback, reads mixed output via try_read_output(), and accesses the client handle for chat/presence callbacks via client_handle().

Typedef Documentation

ClientJoinedCallback

using ivon::ClientJoinedCallback = typedef std::function<void(const std::string &client_id)>

Called when a remote client joins the server session.

ClientLeftCallback

using ivon::ClientLeftCallback = typedef std::function<void(const std::string &client_id, bool was_kicked)>

Called when a remote client leaves the server session.

ClientMessageCallback

using ivon::ClientMessageCallback = typedef std::function<void(const std::string &sender_id, const std::string &data_type, std::span<const uint8_t> data)>

Called when a direct or broadcast message arrives from another client.

ConnectionStateCallback

using ivon::ConnectionStateCallback = typedef std::function<void(ConnectionState new_state)>

Called when the connection lifecycle state changes.

DisconnectedCallback

using ivon::DisconnectedCallback = typedef std::function<void(const std::string &reason)>

Called when the connection to the server is lost or closed.

FanoutDataCallback

using ivon::FanoutDataCallback = typedef std::function<void(const std::string &group_id, uint64_t sender_id, uint64_t seq, const unsigned char *data, size_t len)>

Called when decrypted fanout data arrives from a group member.

Warning

This callback fires on the fanout receive thread.

FanoutErrorCallback

using ivon::FanoutErrorCallback = typedef std::function<void(const std::string &group_id, const std::string &error_message)>

Called when a fanout client encounters a fatal error.

GroupJoinCallback

using ivon::GroupJoinCallback = typedef std::function<void(const GroupJoinResult &result)>

Called when a join_group() request completes.

GroupKeyUpdateCallback

using ivon::GroupKeyUpdateCallback = typedef std::function<void(const std::string &group_id, uint64_t new_epoch)>

Called when a group's encryption key is rotated.

GroupKickedCallback

using ivon::GroupKickedCallback = typedef std::function<void(const std::string &group_id, const std::string &reason)>

Called when THIS client is kicked from a group by the server.

GroupLeaveCallback

using ivon::GroupLeaveCallback = typedef std::function<void(const GroupLeaveResult &result)>

Called when a leave_group() request completes.

GroupListCallback

using ivon::GroupListCallback = typedef std::function<void(const std::vector<GroupInfo> &groups)>

Called when the server responds to a request_group_list() call.

GroupMemberJoinedCallback

using ivon::GroupMemberJoinedCallback = typedef std::function<void(const std::string &group_id, const std::string &client_id, uint64_t fanout_sender_id)>

Called when another client joins a group we are a member of.

GroupMemberLeftCallback

using ivon::GroupMemberLeftCallback = typedef std::function<void(const std::string &group_id, const std::string &client_id, uint64_t fanout_sender_id, bool was_kicked)>

Called when another client leaves a group we are a member of.

GroupMuteCallback

using ivon::GroupMuteCallback = typedef std::function<void(const GroupMuteResult &result)>

Called when a set_mute() request completes.

GroupPropertyUpdateCallback

using ivon::GroupPropertyUpdateCallback = typedef std::function<void(const std::string &group_id, const std::string &key, const std::vector<uint8_t> &value)>

Called when a single group-level property changes.

KickedCallback

using ivon::KickedCallback = typedef std::function<void(const std::string &reason)>

Called when THIS client is kicked from the server.

PasswordCallback

using ivon::PasswordCallback = typedef std::function<std::optional<std::string>(uint32_t remaining_attempts)>

Called when the server requires password authentication.

Parameters

remaining_attempts

How many more tries the server will allow.

Returns

The password string to submit, or std::nullopt to give up.

PcmSourceCallback

using ivon::PcmSourceCallback = typedef std::function<bool(std::span<float> pcm_out)>

Callback type for pulling PCM audio during transmission.

Called every 20 ms while speaking. Fill the provided buffer with mono float PCM samples. Return true if audio was provided, false for silence.

ServerPropertiesCallback

using ivon::ServerPropertiesCallback = typedef std::function<void(const std::unordered_map<std::string, std::vector<uint8_t> > &properties)>

Called when all server-level properties are received during sync.

ServerPropertyUpdateCallback

using ivon::ServerPropertyUpdateCallback = typedef std::function<void(const std::string &key, const std::vector<uint8_t> &value)>

Called when a single server-level property changes.

TofuVerifyCallback

using ivon::TofuVerifyCallback = typedef std::function<bool(const std::string &server_id, TofuVerifyResult result, const std::array<uint8_t, PUBLIC_KEY_SIZE> &server_public_key, const std::optional<std::array<uint8_t, PUBLIC_KEY_SIZE> > &stored_key)>

Called when a new or changed server key is encountered (TOFU).

Parameters

server_id	Server identifier (typically host:port).
result	Verification result.
server_public_key	The server's public key (32 bytes).
stored_key	Previously stored key (nullopt if first contact).

Returns

true to accept the key, false to reject.

Enumeration Type Documentation

ConnectionErrorCode

enum class ivon::ConnectionErrorCode : uint8_t

strong

Error codes for general connection/communication failures.

Enumerator
success
connection_closed
connection_timeout
connection_reset
network_error
connection_canceled
invalid_message_format
unexpected_message
message_too_large
message_too_small
encryption_failed
decryption_failed
signature_invalid
mac_verification_failed
internal_error
out_of_memory
state_error
unknown

ConnectionState

enum class ivon::ConnectionState : uint8_t

strong

Lifecycle states of a Client connection.

Transitions: disconnected -> connecting -> negotiating -> synchronizing -> connected connected -> disconnecting -> disconnected (user-initiated) connected -> disconnected (server/network) any-early -> disconnected (failure during connect)

Enumerator
disconnected	Not connected (initial / final state)
connecting	TCP connection in progress.
negotiating	Key exchange and authentication in progress.
synchronizing	Connected, waiting for initial client-list sync.
connected	Fully connected and synchronized.
disconnecting	Graceful shutdown in progress.

GroupOperationStatus

enum class ivon::GroupOperationStatus : uint8_t

strong

Status codes for group operations.

Enumerator
Success
GroupNotFound
GroupFull
PermissionDenied
AlreadyMember
NotMember
InvalidGroupId
ConnectionError
InternalError
Kicked

NegotiationErrorCode

enum class ivon::NegotiationErrorCode : uint8_t

strong

Error codes specific to the key negotiation/handshake phase.

Enumerator
success
protocol_version_mismatch
invalid_public_key
key_generation_failed
key_derivation_failed
invalid_key_size
nonce_reuse_detected
authentication_failed
unknown_peer
peer_rejected
certificate_expired
certificate_revoked
client_id_rejected
client_not_approved
unknown

TofuVerifyResult

enum class ivon::TofuVerifyResult

strong

Result of TOFU (Trust-On-First-Use) key verification.

Enumerator
trusted	Key matches a previously stored key.
new_key	Server not seen before, key is new.
key_changed	Server seen before but key has changed.
verification_error	Error during verification.

Function Documentation

connection_error_message()

constexpr const char * ivon::connection_error_message ( ConnectionErrorCode  code )

constexprnoexcept

Get a human-readable description of a connection error code.

negotiation_error_message()

constexpr const char * ivon::negotiation_error_message ( NegotiationErrorCode  code )

constexprnoexcept

Get a human-readable description of a negotiation error code.

Variable Documentation

PUBLIC_KEY_SIZE

constexpr size_t ivon::PUBLIC_KEY_SIZE = 32

constexpr

Size of a public key in bytes.