Unified interface for all protocol client implementations. More...

#include <i_protocol_client.h>

Inheritance diagram for kcenon::network::interfaces::i_protocol_client:

Collaboration diagram for kcenon::network::interfaces::i_protocol_client:

Public Types
using	receive_callback_t = std::function<void(const std::vector<uint8_t>&)>
	Callback type for received data.

using	connected_callback_t = std::function<void()>
	Callback type for connection established.

using	disconnected_callback_t = std::function<void()>
	Callback type for disconnection.

using	error_callback_t = std::function<void(std::error_code)>
	Callback type for errors.

Public Member Functions
virtual auto	start (std::string_view host, uint16_t port) -> VoidResult=0
	Starts the client and connects to the specified server.

virtual auto	stop () -> VoidResult=0
	Stops the client and closes the connection.

virtual auto	send (std::vector< uint8_t > &&data) -> VoidResult=0
	Sends data to the connected server.

virtual auto	is_connected () const -> bool=0
	Checks if the client is connected to the server.

virtual auto	set_observer (std::shared_ptr< connection_observer > observer) -> void=0
	Sets the connection observer for unified event handling.

virtual auto	set_receive_callback (receive_callback_t callback) -> void=0
	Sets the callback for received data.

virtual auto	set_connected_callback (connected_callback_t callback) -> void=0
	Sets the callback for connection established.

virtual auto	set_disconnected_callback (disconnected_callback_t callback) -> void=0
	Sets the callback for disconnection.

virtual auto	set_error_callback (error_callback_t callback) -> void=0
	Sets the callback for errors.

Public Member Functions inherited from kcenon::network::interfaces::i_network_component
virtual	~i_network_component ()=default
	Virtual destructor for proper cleanup of derived classes.

	i_network_component (const i_network_component &)=delete

i_network_component &	operator= (const i_network_component &)=delete

	i_network_component (i_network_component &&)=delete

i_network_component &	operator= (i_network_component &&)=delete

Additional Inherited Members
Protected Member Functions inherited from kcenon::network::interfaces::i_network_component
	i_network_component ()=default
	Default constructor (only for derived classes)

virtual auto	is_running () const -> bool=0
	Checks if the component is currently running.

virtual auto	wait_for_stop () -> void=0
	Blocks until the component has stopped.

Detailed Description

Unified interface for all protocol client implementations.

This interface establishes a common contract for all protocol clients (TCP, UDP, HTTP, WebSocket, QUIC, etc.) in the network system. It provides a consistent API for client lifecycle management, connection handling, and data transmission across different protocol implementations.

Design Rationale

This interface was created to:

Eliminate code duplication across protocol-specific client implementations
Provide a single, uniform API for all client types
Enable protocol-agnostic facade and adapter patterns
Simplify testing through consistent interface contracts

Protocol Coverage

Implementations include:

TCP clients (messaging_client, secure_messaging_client)
UDP clients (messaging_udp_client, reliable_udp_client)
HTTP clients (http_client)
WebSocket clients (messaging_ws_client)
QUIC clients (messaging_quic_client)

Observer Pattern (Recommended)

Use set_observer() with a connection_observer implementation for unified event handling across all protocol types.

Callback Support

Individual callback setters are provided as an alternative to the observer pattern for simpler use cases.

Thread Safety

All public methods must be thread-safe
Callbacks and observer methods may be invoked from I/O threads

Usage Example

// Create client instance (protocol-specific)
std::shared_ptr<i_protocol_client> client = std::make_shared<messaging_client>();
 
// Set observer for events
auto observer = std::make_shared<my_connection_observer>();
client->set_observer(observer);
 
// Start and connect
if (auto result = client->start("127.0.0.1", 8080); !result) {
    // Handle connection error
}
 
// Send data
std::vector<uint8_t> data = { 0x01, 0x02, 0x03 };
client->send(std::move(data));
 
// Stop when done
client->stop();

See also: i_protocol_server; connection_observer; i_network_component

Definition at line 99 of file i_protocol_client.h.

Member Typedef Documentation

◆ connected_callback_t

using kcenon::network::interfaces::i_protocol_client::connected_callback_t = std::function<void()>

Callback type for connection established.

Definition at line 105 of file i_protocol_client.h.

◆ disconnected_callback_t

using kcenon::network::interfaces::i_protocol_client::disconnected_callback_t = std::function<void()>

Callback type for disconnection.

Definition at line 107 of file i_protocol_client.h.

◆ error_callback_t

using kcenon::network::interfaces::i_protocol_client::error_callback_t = std::function<void(std::error_code)>

Callback type for errors.

Definition at line 109 of file i_protocol_client.h.

◆ receive_callback_t

using kcenon::network::interfaces::i_protocol_client::receive_callback_t = std::function<void(const std::vector<uint8_t>&)>

Callback type for received data.

Definition at line 103 of file i_protocol_client.h.

Member Function Documentation

◆ is_connected()

virtual auto kcenon::network::interfaces::i_protocol_client::is_connected ( ) const -> bool

nodiscardpure virtual

Checks if the client is connected to the server.

Returns: true if connected, false otherwise.

Connection States

Not started: is_running() == false, is_connected() == false
Starting/Connecting: is_running() == true, is_connected() == false
Connected: is_running() == true, is_connected() == true
Disconnected: is_running() == true, is_connected() == false
Stopped: is_running() == false, is_connected() == false

Protocol-Specific Notes

TCP/WebSocket/QUIC: Returns true only when connection is established
UDP: Returns true when target endpoint is set (no actual "connection")
HTTP: Returns true if connection pool has active connections

Thread Safety

Thread-safe. Uses atomic operations for state checking.

Implemented in kcenon::network::core::messaging_client, kcenon::network::core::messaging_client, kcenon::network::internal::adapters::http_client_adapter, kcenon::network::internal::adapters::quic_client_adapter, kcenon::network::internal::adapters::udp_client_adapter, and kcenon::network::internal::adapters::ws_client_adapter.

◆ send()

virtual auto kcenon::network::interfaces::i_protocol_client::send ( std::vector< uint8_t > && data ) -> VoidResult

nodiscardpure virtual

Sends data to the connected server.

Parameters

data	The data to send.

Returns: VoidResult indicating success or failure.

Behavior

Queues data for transmission
May block if send queue is full (protocol-dependent)
Data is moved, not copied

Error Conditions

Returns error if not connected
Returns error if send buffer is full
Returns error if underlying protocol send fails

Protocol-Specific Notes

TCP: Stream-based, may fragment data
UDP: Datagram-based, preserves message boundaries
WebSocket: Frame-based, preserves message boundaries
HTTP: Typically request/response, may queue

Thread Safety

Thread-safe. Multiple sends may be queued concurrently. Send operations are serialized internally.

Implemented in kcenon::network::core::messaging_client, kcenon::network::internal::adapters::http_client_adapter, kcenon::network::internal::adapters::quic_client_adapter, kcenon::network::internal::adapters::udp_client_adapter, and kcenon::network::internal::adapters::ws_client_adapter.

◆ set_connected_callback()

virtual auto kcenon::network::interfaces::i_protocol_client::set_connected_callback ( connected_callback_t callback ) -> void

pure virtual

Sets the callback for connection established.

Parameters

callback The callback function.

Implemented in kcenon::network::core::messaging_client, kcenon::network::internal::adapters::http_client_adapter, kcenon::network::internal::adapters::quic_client_adapter, kcenon::network::internal::adapters::udp_client_adapter, and kcenon::network::internal::adapters::ws_client_adapter.

◆ set_disconnected_callback()

virtual auto kcenon::network::interfaces::i_protocol_client::set_disconnected_callback ( disconnected_callback_t callback ) -> void

pure virtual

Sets the callback for disconnection.

Parameters

callback The callback function.

Implemented in kcenon::network::core::messaging_client, kcenon::network::internal::adapters::http_client_adapter, kcenon::network::internal::adapters::quic_client_adapter, kcenon::network::internal::adapters::udp_client_adapter, and kcenon::network::internal::adapters::ws_client_adapter.

◆ set_error_callback()

virtual auto kcenon::network::interfaces::i_protocol_client::set_error_callback ( error_callback_t callback ) -> void

pure virtual

Sets the callback for errors.

Parameters

callback The callback function.

Implemented in kcenon::network::core::messaging_client, kcenon::network::internal::adapters::http_client_adapter, kcenon::network::internal::adapters::quic_client_adapter, kcenon::network::internal::adapters::udp_client_adapter, and kcenon::network::internal::adapters::ws_client_adapter.

◆ set_observer()

virtual auto kcenon::network::interfaces::i_protocol_client::set_observer ( std::shared_ptr< connection_observer > observer ) -> void

pure virtual

Sets the connection observer for unified event handling.

Parameters

observer The observer instance (shared ownership).

The observer receives all connection events through a single interface:

on_connected(): Connection established
on_disconnected(): Connection lost or closed
on_receive(data): Data received from server
on_error(error_code): Error occurred

Recommended Pattern

This is the preferred method for event handling as it:

Centralizes all event handling in one place
Provides consistent interface across all protocols
Enables easier testing through mock observers

Usage

class my_observer : public connection_observer {
    void on_connected() override { // handle connect
    }
    void on_receive(const std::vector<uint8_t>& data) override {
        // handle data
    }
    // ... implement other methods
};
 
client->set_observer(std::make_shared<my_observer>());

Thread Safety

Thread-safe. Observer methods may be invoked from I/O threads. Observer must be thread-safe if shared across multiple clients.

See also: connection_observer; callback_adapter

Implemented in kcenon::network::core::messaging_client, kcenon::network::internal::adapters::http_client_adapter, kcenon::network::internal::adapters::quic_client_adapter, kcenon::network::internal::adapters::udp_client_adapter, and kcenon::network::internal::adapters::ws_client_adapter.

◆ set_receive_callback()

virtual auto kcenon::network::interfaces::i_protocol_client::set_receive_callback ( receive_callback_t callback ) -> void

pure virtual

Sets the callback for received data.

Parameters

callback The callback function.

Thread Safety

Thread-safe. The callback may be invoked from I/O threads. Callback must be thread-safe if it accesses shared state.

Implemented in kcenon::network::core::messaging_client, kcenon::network::internal::adapters::http_client_adapter, kcenon::network::internal::adapters::quic_client_adapter, kcenon::network::internal::adapters::udp_client_adapter, and kcenon::network::internal::adapters::ws_client_adapter.

◆ start()

virtual auto kcenon::network::interfaces::i_protocol_client::start	(	std::string_view	host,
		uint16_t	port ) -> VoidResult

nodiscardpure virtual

Starts the client and connects to the specified server.

Parameters

host	The server hostname or IP address.
port	The server port number.

Returns: VoidResult indicating success or failure.

Behavior

Creates the underlying protocol-specific connection
Resolves hostname to IP address if needed
Establishes connection with the server
Begins receiving data (for connection-oriented protocols)
Invokes connected callback/observer on success

Error Conditions

Returns error if already running
Returns error if host resolution fails
Returns error if connection establishment fails
Returns error if underlying protocol initialization fails

Protocol-Specific Notes

TCP/WebSocket/QUIC: Establishes stateful connection
UDP: Sets default target endpoint, does not "connect" in traditional sense
HTTP: May establish connection pool or persistent connection

Thread Safety

Thread-safe. Only one start operation can succeed at a time. Subsequent calls while running will return an error.

Implemented in kcenon::network::core::messaging_client, kcenon::network::internal::adapters::http_client_adapter, kcenon::network::internal::adapters::quic_client_adapter, kcenon::network::internal::adapters::udp_client_adapter, and kcenon::network::internal::adapters::ws_client_adapter.

◆ stop()

virtual auto kcenon::network::interfaces::i_protocol_client::stop ( ) -> VoidResult

nodiscardpure virtual

Stops the client and closes the connection.

Returns: VoidResult indicating success or failure.

Behavior

Cancels all pending operations
Closes the connection gracefully if possible
Invokes disconnected callback/observer
Releases protocol-specific resources

Error Conditions

Returns error if not running

Protocol-Specific Notes

TCP: Sends FIN, waits for graceful close
WebSocket: Sends close frame with status code
UDP: Stops receiving, no "close" required
QUIC: Sends CONNECTION_CLOSE frame

Thread Safety

Thread-safe. Safe to call from any thread including callbacks. Pending operations will be cancelled and cleaned up.

Implemented in kcenon::network::core::messaging_client, kcenon::network::internal::adapters::http_client_adapter, kcenon::network::internal::adapters::quic_client_adapter, kcenon::network::internal::adapters::udp_client_adapter, and kcenon::network::internal::adapters::ws_client_adapter.

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

include/kcenon/network/interfaces/i_protocol_client.h

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Design Rationale

Protocol Coverage

Observer Pattern (Recommended)

Callback Support

Thread Safety

Usage Example

Member Typedef Documentation

◆ connected_callback_t

◆ disconnected_callback_t

◆ error_callback_t

◆ receive_callback_t

Member Function Documentation

◆ is_connected()

Connection States

Protocol-Specific Notes

Thread Safety

◆ send()

Behavior

Error Conditions

Protocol-Specific Notes

Thread Safety

◆ set_connected_callback()

◆ set_disconnected_callback()

◆ set_error_callback()

◆ set_observer()

Recommended Pattern

Usage

Thread Safety

◆ set_receive_callback()

Thread Safety

◆ start()

Behavior

Error Conditions

Protocol-Specific Notes

Thread Safety

◆ stop()

Behavior

Error Conditions

Protocol-Specific Notes

Thread Safety