kcenon::network::unified::i_connection Interface Reference

Core interface for active network connections. More...

#include <i_connection.h>

Inheritance diagram for kcenon::network::unified::i_connection:

Collaboration diagram for kcenon::network::unified::i_connection:

Public Member Functions
	~i_connection () override=default
	Virtual destructor.
	i_connection (const i_connection &)=delete
i_connection &	operator= (const i_connection &)=delete
	i_connection (i_connection &&)=default
i_connection &	operator= (i_connection &&)=default
virtual auto	connect (const endpoint_info &endpoint) -> VoidResult=0
	Connects to a remote endpoint using host/port.
virtual auto	connect (std::string_view url) -> VoidResult=0
	Connects to a remote endpoint using URL.
virtual auto	close () noexcept -> void=0
	Closes the connection gracefully.
virtual auto	set_callbacks (connection_callbacks callbacks) -> void=0
	Sets all connection callbacks at once.
virtual auto	set_options (connection_options options) -> void=0
	Sets connection options.
virtual auto	set_timeout (std::chrono::milliseconds timeout) -> void=0
	Sets the connection timeout.
virtual auto	is_connecting () const noexcept -> bool=0
	Checks if the connection is in the process of connecting.
virtual auto	wait_for_stop () -> void=0
	Blocks until the component has stopped.
Public Member Functions inherited from kcenon::network::unified::i_transport
virtual	~i_transport ()=default
	Virtual destructor for proper cleanup of derived classes.
	i_transport (const i_transport &)=delete
i_transport &	operator= (const i_transport &)=delete
	i_transport (i_transport &&)=default
i_transport &	operator= (i_transport &&)=default
virtual auto	send (std::span< const std::byte > data) -> VoidResult=0
	Sends raw data to the remote endpoint.
virtual auto	send (std::vector< uint8_t > &&data) -> VoidResult=0
	Sends data from a uint8_t vector.
virtual auto	is_connected () const noexcept -> bool=0
	Checks if the transport is currently connected.
virtual auto	id () const noexcept -> std::string_view=0
	Gets the unique identifier for this transport/connection.
virtual auto	remote_endpoint () const noexcept -> endpoint_info=0
	Gets the remote endpoint information.
virtual auto	local_endpoint () const noexcept -> endpoint_info=0
	Gets the local endpoint information.

Protected Member Functions
	i_connection ()=default
	Default constructor (only for derived classes)
Protected Member Functions inherited from kcenon::network::unified::i_transport
	i_transport ()=default
	Default constructor (only for derived classes)

Detailed Description

Core interface for active network connections.

This interface extends i_transport with connection lifecycle operations. It represents:

• Client-side connections (initiated by connect())
• Accepted connections (from i_listener::accept())

Design Philosophy

By inheriting from i_transport, i_connection provides a unified interface for data transfer while adding connection-specific operations. This allows code that only needs to send/receive data to work with just i_transport, while connection management code uses i_connection.

Lifecycle

1. Create connection via protocol factory (or accept from listener)
2. Optionally configure callbacks and options
3. Connect to remote endpoint (if not already accepted)
4. Send/receive data via inherited i_transport methods
5. Close connection when done

Thread Safety

All public methods must be thread-safe.

Usage Example

// Create connection via protocol factory
auto conn = protocol::tcp::connect({"localhost", 8080});
 
// Set callbacks
conn->set_callbacks({
    .on_connected = []() { std::cout << "Connected!\n"; },
    .on_data = [](std::span<const std::byte> data) {
        // Process received data
    },
    .on_disconnected = []() { std::cout << "Disconnected\n"; },
    .on_error = [](std::error_code ec) {
        std::cerr << "Error: " << ec.message() << "\n";
    }
});
 
// Connect (may be async depending on implementation)
if (auto result = conn->connect({"remote.host.com", 9000}); !result) {
    std::cerr << "Connect failed\n";
    return;
}
 
// Send data (inherited from i_transport)
std::vector<std::byte> data = ...;
conn->send(data);
 
// Close when done
conn->close();

See also

i_transport - Base data transport interface

i_listener - Server-side connection acceptor

Definition at line 88 of file i_connection.h.

Constructor & Destructor Documentation

~i_connection()

kcenon::network::unified::i_connection::~i_connection ( )

overridedefault

Virtual destructor.

Closing the connection is implicit when the i_connection is destroyed.

i_connection() [1/3]

kcenon::network::unified::i_connection::i_connection ( const i_connection & )

delete

i_connection() [2/3]

kcenon::network::unified::i_connection::i_connection ( i_connection && )

default

i_connection() [3/3]

kcenon::network::unified::i_connection::i_connection ( )

protecteddefault

Default constructor (only for derived classes)

Member Function Documentation

close()

virtual auto kcenon::network::unified::i_connection::close ( ) -> void

pure virtualnoexcept

Closes the connection gracefully.

Behavior

• Initiates graceful shutdown
• Pending sends may be completed before close
• Triggers on_disconnected callback when fully closed

Thread Safety

Thread-safe. Safe to call multiple times.

Note

After close(), is_connected() returns false and send() returns error.

Implemented in kcenon::network::unified::adapters::quic_connection_adapter, kcenon::network::unified::adapters::tcp_connection_adapter, kcenon::network::unified::adapters::udp_connection_adapter, and kcenon::network::unified::adapters::ws_connection_adapter.

connect() [1/2]

virtual auto kcenon::network::unified::i_connection::connect ( const endpoint_info & endpoint ) -> VoidResult

nodiscardpure virtual

Connects to a remote endpoint using host/port.

Parameters

endpoint

The remote endpoint to connect to

Returns

VoidResult indicating success or failure

Behavior

• Initiates connection to the specified endpoint
• May block until connection is established (sync mode)
• May return immediately and notify via callback (async mode)

Error Conditions

• Returns error if already connected
• Returns error if connection fails
• Returns error if host resolution fails
• Returns error if connection timeout expires

Thread Safety

Thread-safe. Only one connect operation can succeed at a time.

Implemented in kcenon::network::unified::adapters::quic_connection_adapter, kcenon::network::unified::adapters::tcp_connection_adapter, kcenon::network::unified::adapters::udp_connection_adapter, and kcenon::network::unified::adapters::ws_connection_adapter.

connect() [2/2]

virtual auto kcenon::network::unified::i_connection::connect ( std::string_view url ) -> VoidResult

nodiscardpure virtual

Connects to a remote endpoint using URL.

Parameters

url	The URL to connect to (e.g., "wss://example.com/ws")

Returns

VoidResult indicating success or failure

This overload is primarily for URL-based protocols like WebSocket and HTTP. For socket-based protocols, use the endpoint_info overload.

Error Conditions

Same as connect(endpoint_info) plus:

• Returns error if URL is malformed
• Returns error if protocol is not supported

Implemented in kcenon::network::unified::adapters::quic_connection_adapter, kcenon::network::unified::adapters::tcp_connection_adapter, kcenon::network::unified::adapters::udp_connection_adapter, and kcenon::network::unified::adapters::ws_connection_adapter.

is_connecting()

virtual auto kcenon::network::unified::i_connection::is_connecting ( ) const -> bool

nodiscardpure virtualnoexcept

Checks if the connection is in the process of connecting.

Returns

true if connect() was called but not yet completed

Implemented in kcenon::network::unified::adapters::quic_connection_adapter, kcenon::network::unified::adapters::tcp_connection_adapter, kcenon::network::unified::adapters::udp_connection_adapter, and kcenon::network::unified::adapters::ws_connection_adapter.

operator=() [1/2]

i_connection & kcenon::network::unified::i_connection::operator= ( const i_connection & )

delete

operator=() [2/2]

i_connection & kcenon::network::unified::i_connection::operator= ( i_connection && )

default

set_callbacks()

virtual auto kcenon::network::unified::i_connection::set_callbacks ( connection_callbacks callbacks ) -> void

pure virtual

Sets all connection callbacks at once.

Parameters

callbacks

The callback structure with handlers

Replaces all previously set callbacks. Empty callback functions in the structure will clear the corresponding handler.

Thread Safety

Thread-safe, but callbacks may be invoked from I/O threads.

Implemented in kcenon::network::unified::adapters::quic_connection_adapter, kcenon::network::unified::adapters::tcp_connection_adapter, kcenon::network::unified::adapters::udp_connection_adapter, and kcenon::network::unified::adapters::ws_connection_adapter.

set_options()

virtual auto kcenon::network::unified::i_connection::set_options ( connection_options options ) -> void

pure virtual

Sets connection options.

Parameters

options

The configuration options

Some options may only be effective before connect() is called.

Thread Safety

Thread-safe. Changes may not affect in-flight operations.

Implemented in kcenon::network::unified::adapters::quic_connection_adapter, kcenon::network::unified::adapters::tcp_connection_adapter, kcenon::network::unified::adapters::udp_connection_adapter, and kcenon::network::unified::adapters::ws_connection_adapter.

set_timeout()

virtual auto kcenon::network::unified::i_connection::set_timeout ( std::chrono::milliseconds timeout ) -> void

pure virtual

Sets the connection timeout.

Parameters

timeout

Timeout duration (0 = no timeout)

Shorthand for setting just the connect_timeout option.

Implemented in kcenon::network::unified::adapters::quic_connection_adapter, kcenon::network::unified::adapters::tcp_connection_adapter, kcenon::network::unified::adapters::udp_connection_adapter, and kcenon::network::unified::adapters::ws_connection_adapter.

wait_for_stop()

virtual auto kcenon::network::unified::i_connection::wait_for_stop ( ) -> void

pure virtual

Blocks until the component has stopped.

Waits for all pending operations to complete and the connection to be fully closed.

Thread Safety

Safe to call from any thread. Uses internal synchronization.

Implemented in kcenon::network::unified::adapters::quic_connection_adapter, kcenon::network::unified::adapters::tcp_connection_adapter, kcenon::network::unified::adapters::udp_connection_adapter, and kcenon::network::unified::adapters::ws_connection_adapter.

---

The documentation for this interface was generated from the following file:

• include/kcenon/network/detail/unified/i_connection.h