EntropyEngine::Networking::WebRTCConnection

WebRTC-based network connection using data channels. More…

#include <WebRTCConnection.h>

Inherits from EntropyEngine::Networking::NetworkConnection, EntropyEngine::Core::EntropyObject

Public Functions

	Name
	~WebRTCConnection() override
virtual Result< void >	trySend(const std::vector< uint8_t > & data) override Non-blocking send with backpressure detection.
virtual bool	supportsMultipleChannels() const override Checks if this backend supports multiple channels.
Result< void >	setRemoteDescription(const std::string & type, const std::string & sdp) Set remote description received from signaling.
virtual Result< void >	sendUnreliable(const std::vector< uint8_t > & data) override Sends data over the unreliable channel (if available).
virtual Result< void >	sendOnChannel(const std::string & channel, const std::vector< uint8_t > & data) override Sends data on a named channel.
virtual Result< void >	send(const std::vector< uint8_t > & data) override Sends data over the reliable channel.
Result< void >	reconnect() Reconnect using ICE restart without destroying peer connection.
virtual Result< void >	openChannel(const std::string & channel) override Opens a named channel (creates if needed).
bool	isReady() const Check if peer connection is created and ready for signaling.
virtual bool	isConnected() const override Checks if connection is established.
virtual bool	isChannelOpen(const std::string & channel) const override Checks if a named channel is open and ready for data.
virtual ConnectionType	getType() const override Gets connection type (Local or Remote).
virtual ConnectionStats	getStats() const override Gets connection statistics.
virtual ConnectionState	getState() const override Gets current connection state.
virtual Result< void >	disconnect() override Gracefully close the connection without destroying peer connection.
virtual Result< void >	connect() override Initiates connection to endpoint.
Result< void >	addRemoteCandidate(const std::string & candidate, const std::string & mid) Add remote ICE candidate received from signaling.
	WebRTCConnection(WebRTCConfig config, SignalingCallbacks signalingCallbacks, std::string signalingUrl ="", std::string dataChannelLabel =“entropy-data”) Construct a new WebRTC connection.

Additional inherited members

Public Types inherited from EntropyEngine::Networking::NetworkConnection

	Name
using std::function< void(ConnectionState)>	StateCallback Callback for state changes.
using std::function< void(const std::vector< uint8_t > &)>	MessageCallback Callback for received messages.
using std::function< void(const std::string &channel, const std::vector< uint8_t > &)>	ChannelMessageCallback

Public Functions inherited from EntropyEngine::Networking::NetworkConnection

	Name
virtual	~NetworkConnection() =default
virtual void	startReceiving() Starts the receive thread for adopted connections.
void	setStateCallback(StateCallback callback) Sets callback for state changes.
void	setMessageCallback(MessageCallback callback) Sets callback for incoming messages.
virtual void	setChannelMessageCallback(const std::string & channel, MessageCallback callback) Sets callback for messages received on a specific channel.
bool	isShuttingDown() const Check if callbacks are being shut down (safe for use in static callbacks).

Protected Functions inherited from EntropyEngine::Networking::NetworkConnection

	Name
void	shutdownCallbacks() Shuts down callbacks and waits for in-flight invocations.
void	onStateChanged(ConnectionState state) Invokes state callback with lifetime guards.
void	onMessageReceived(const std::vector< uint8_t > & data) Invokes message callback with lifetime guards.
void	onChannelMessageReceived(const std::string & channel, const std::vector< uint8_t > & data) Invokes channel-specific message callback with lifetime guards.
	NetworkConnection() =default

Public Attributes inherited from EntropyEngine::Networking::NetworkConnection

	Name
const char *	CHANNEL_CONTROL Well-known channel names.
const char *	CHANNEL_ASSET_UPLOAD Bulk asset uploads.
const char *	CHANNEL_ASSET_DOWNLOAD Bulk asset downloads.

Protected Classes inherited from EntropyEngine::Core::EntropyObject

	Name
struct	HandleCore Optional handle identity stamped by an owner/registry.

Public Functions inherited from EntropyEngine::Core::EntropyObject

	Name
virtual	~EntropyObject() =default
virtual const TypeSystem::TypeInfo *	typeInfo() const Optional richer type information; may be null.
bool	tryRetain() const Attempts to retain only if the object is still alive.
virtual std::string	toString() const Human-readable short string (class@ptr by default).
void	retain() const Increments the reference count.
void	release() const Decrements the reference count and deletes when it reaches zero.
uint32_t	refCount() const Current reference count (approximate under contention).
EntropyObject &	operator=(const EntropyObject & ) =delete
EntropyObject &	operator=(EntropyObject && ) =delete
bool	hasHandle() const
template <class OwnerT > OwnerT *	handleOwnerAs() const Returns the stamped owner pointer cast to the requested type.
const void *	handleOwner() const
uint32_t	handleIndex() const
uint64_t	handleId() const
uint32_t	handleGeneration() const
WeakControlBlock *	getWeakControlBlock() const Lazily retrieves or creates the weak control block.
virtual std::string	description() const Long-form description; defaults to toString().
virtual std::string	debugString() const Debug-oriented string including refcount and handle when present.
virtual const char *	className() const Runtime class name for diagnostics and reflection.
virtual uint64_t	classHash() const Stable type hash for cross-language identification.
	EntropyObject() =default
	EntropyObject(EntropyObject && ) =delete
	EntropyObject(const EntropyObject & ) =delete

Protected Functions inherited from EntropyEngine::Core::EntropyObject

	Name
void	_setHandleIdentity(void * owner, uint32_t index, uint32_t generation)
void	_clearHandleIdentity()

Protected Attributes inherited from EntropyEngine::Core::EntropyObject

	Name
std::atomic< WeakControlBlock * >	_weakBlock Lazily allocated control block for weak refs.
std::atomic< uint32_t >	_refCount Thread-safe retain/release counter.
struct EntropyEngine::Core::EntropyObject::HandleCore	_handle

Friends inherited from EntropyEngine::Core::EntropyObject

	Name
struct	HandleAccess

Detailed Description

class EntropyEngine::Networking::WebRTCConnection;

WebRTC-based network connection using data channels.

Implements NetworkConnection interface using libdatachannel for WebRTC data channels. Supports reliable and unreliable data transfer over WebRTC.

Supports two modes:

Server mode: SignalingCallbacks provided (used by WebRTCServer)
Client mode: Signaling URL provided, WebSocket managed internally

Public Functions Documentation

function ~WebRTCConnection

~WebRTCConnection() override

function trySend

virtual Result< void > trySend(
    const std::vector< uint8_t > & data
) override

Non-blocking send with backpressure detection.

Parameters:

data Bytes to send

Return: Result with WouldBlock error if backpressured, or InvalidParameter if not supported

Reimplements: EntropyEngine::Networking::NetworkConnection::trySend

function supportsMultipleChannels

inline virtual bool supportsMultipleChannels() const override

Checks if this backend supports multiple channels.

Return: true if sendOnChannel uses separate channels

Reimplements: EntropyEngine::Networking::NetworkConnection::supportsMultipleChannels

function setRemoteDescription

Result< void > setRemoteDescription(
    const std::string & type,
    const std::string & sdp
)

Set remote description received from signaling.

Parameters:

type SDP type (“offer” or “answer”)
sdp SDP string

function sendUnreliable

virtual Result< void > sendUnreliable(
    const std::vector< uint8_t > & data
) override

Sends data over the unreliable channel (if available).

Parameters:

data Bytes to send

Return: Result indicating success or failure reason

Reimplements: EntropyEngine::Networking::NetworkConnection::sendUnreliable

Falls back to reliable channel if unreliable is not supported. Thread-Safety: Same mutex contention considerations as send().

function sendOnChannel

virtual Result< void > sendOnChannel(
    const std::string & channel,
    const std::vector< uint8_t > & data
) override

Sends data on a named channel.

Parameters:

channel Channel name (use CHANNEL_* constants)
data Bytes to send

Return: Result indicating success or failure

Reimplements: EntropyEngine::Networking::NetworkConnection::sendOnChannel

For backends that support multiple channels (WebRTC), this sends on the specified channel. For single-channel backends (Unix socket, named pipe), this falls back to the default channel.

function send

virtual Result< void > send(
    const std::vector< uint8_t > & data
) override

Sends data over the reliable channel.

Parameters:

data Bytes to send

Return: Result indicating success or failure reason

Reimplements: EntropyEngine::Networking::NetworkConnection::send

Thread-Safety: All send operations are serialized through a per-connection mutex. For high-throughput scenarios with large messages, this can become a bottleneck. Consider:

Using sendUnreliable for non-critical data
Batching multiple small messages into larger payloads
Using multiple connections for parallel sends

function reconnect

Result< void > reconnect()

Reconnect using ICE restart without destroying peer connection.

Return: [Result](/api/EntropyEngine/Networking/Result< void >/) Success or error

This method triggers ICE restart by generating a new offer with fresh ICE credentials. The peer connection remains alive, which is faster and more reliable than destroying and recreating the connection.

ICE restart in libdatachannel is performed by calling rtcSetLocalDescription(pc, “offer”) on an existing connection. The library automatically generates new ICE credentials (ice-ufrag and ice-pwd) and triggers a new offer/answer exchange through signaling.

function openChannel

virtual Result< void > openChannel(
    const std::string & channel
) override

Opens a named channel (creates if needed).

Parameters:

channel Channel name

Return: Result indicating success or failure

Reimplements: EntropyEngine::Networking::NetworkConnection::openChannel

For WebRTC, this creates a new data channel. For other backends, this is a no-op since they use a single channel.

function isReady

bool isReady() const

Check if peer connection is created and ready for signaling.

function isConnected

virtual bool isConnected() const override

Checks if connection is established.

Return: true if state is Connected

Reimplements: EntropyEngine::Networking::NetworkConnection::isConnected

function isChannelOpen

virtual bool isChannelOpen(
    const std::string & channel
) const override

Checks if a named channel is open and ready for data.

Parameters:

channel Channel name

Return: true if channel is open (or backend doesn’t support channels)

Reimplements: EntropyEngine::Networking::NetworkConnection::isChannelOpen

function getType

inline virtual ConnectionType getType() const override

Gets connection type (Local or Remote).

Return: Connection type determined at creation

Reimplements: EntropyEngine::Networking::NetworkConnection::getType

function getStats

virtual ConnectionStats getStats() const override

Gets connection statistics.

Return: Stats with bytes/messages sent/received

Reimplements: EntropyEngine::Networking::NetworkConnection::getStats

function getState

virtual ConnectionState getState() const override

Gets current connection state.

Return: Connection state (Disconnected, Connecting, Connected, etc.)

Reimplements: EntropyEngine::Networking::NetworkConnection::getState

function disconnect

virtual Result< void > disconnect() override

Gracefully close the connection without destroying peer connection.

Reimplements: EntropyEngine::Networking::NetworkConnection::disconnect

This allows subsequent reconnection via reconnect() using ICE restart. The peer connection remains alive for faster reconnection.

function connect

virtual Result< void > connect() override

Initiates connection to endpoint.

Return: Result indicating success or failure

Reimplements: EntropyEngine::Networking::NetworkConnection::connect

function addRemoteCandidate

Result< void > addRemoteCandidate(
    const std::string & candidate,
    const std::string & mid
)

Add remote ICE candidate received from signaling.

Parameters:

candidate ICE candidate string
mid Media stream identification tag

function WebRTCConnection

WebRTCConnection(
    WebRTCConfig config,
    SignalingCallbacks signalingCallbacks,
    std::string signalingUrl ="",
    std::string dataChannelLabel ="entropy-data"
)

Construct a new WebRTC connection.

Parameters:

config WebRTC configuration (ICE servers, etc.)
signalingCallbacks Callbacks for sending signaling messages (server mode)
signalingUrl WebSocket URL for signaling (client mode, empty if using callbacks)
dataChannelLabel Label for the data channel (default: “entropy-data”)

Updated on 2026-01-26 at 16:50:32 -0500