WebRTC module

PeerSession

Manages a WebRTC peer connection lifecycle over any signalling transport that implements SignallingInterface.

PeerSession

#include <icy/webrtc/peersession.h>

Manages a WebRTC peer connection lifecycle over any signalling transport that implements SignallingInterface.

Works with SympleSignaller (Symple call protocol), WebSocketSignaller (plain JSON over WSS), or any custom implementation.

Media is optional. Set [Config::media](icy-wrtc-PeerSession-Config.html#media-2) codecs to enable tracks. Leave codec encoders empty for data-channel-only sessions.

Public Attributes

Return	Name	Description
`ThreadSignal< void(State)>`	`StateChanged`	Emitted whenever the session state changes. Parameter: new State value.
`ThreadSignal< void(const std::string &)>`	`IncomingCall`	Emitted when a remote peer initiates a call (state transitions to IncomingInit). Parameter: remote peer identifier.
`ThreadSignal< void(rtc::message_variant)>`	`DataReceived`	Emitted when a message arrives on the data channel. Parameter: rtc::message_variant (string or binary).

StateChanged

ThreadSignal< void(State)> StateChanged

Emitted whenever the session state changes. Parameter: new State value.

IncomingCall

ThreadSignal< void(const std::string &)> IncomingCall

Emitted when a remote peer initiates a call (state transitions to IncomingInit). Parameter: remote peer identifier.

DataReceived

ThreadSignal< void(rtc::message_variant)> DataReceived

Emitted when a message arrives on the data channel. Parameter: rtc::message_variant (string or binary).

Public Methods

Return	Name	Description
	`PeerSession`	Construct with any signalling implementation. The signaller must outlive this PeerSession.
	`PeerSession`	Deleted copy constructor; PeerSession owns live signalling and RTC callbacks.
`void`	`call`	Initiate an outgoing call to a remote peer. Sends a "init" control message and transitions to OutgoingInit.
`void`	`accept`	Accept an incoming call. Creates the PeerConnection, sends "accept", and transitions to Negotiating.
`void`	`reject`	Reject an incoming call. Sends a "reject" control message and transitions to Ended.
`void`	`hangup`	Terminate any non-idle call phase. Sends a "hangup" control message, closes the PeerConnection, and transitions to Ended. Safe to call from any non-Idle/Ended state.
`void`	`sendData`	Send a UTF-8 string message over the data channel. Silently dropped if the data channel is not open.
`void`	`sendData`	Send raw binary data over the data channel. Silently dropped if the data channel is not open.
`State`	`state` `const`	Current session state. Thread-safe.
`std::string`	`remotePeerId` `const`	Identifier of the remote peer for the current or most recent call. Empty when Idle.
`MediaBridge &`	`media`	Media bridge for this session. Valid for the lifetime of the PeerSession.
`const MediaBridge &`	`media` `const`	Media bridge for this session. Valid for the lifetime of the PeerSession.
`std::shared_ptr< rtc::PeerConnection >`	`peerConnection`	The underlying PeerConnection, or nullptr when Idle/Ended.
`std::shared_ptr< rtc::DataChannel >`	`dataChannel`	The data channel, or nullptr if none is open.

PeerSession

PeerSession(SignallingInterface & signaller, const Config & config)

Construct with any signalling implementation. The signaller must outlive this PeerSession.

PeerSession

PeerSession(const PeerSession &) = delete

Deleted copy constructor; PeerSession owns live signalling and RTC callbacks.

call

void call(const std::string & peerId)

Initiate an outgoing call to a remote peer. Sends a "init" control message and transitions to OutgoingInit.

Parameters

peerId Remote peer identifier passed to the signaller.

Exceptions

std::logic_error if not currently in the Idle state.

accept

void accept()

Accept an incoming call. Creates the PeerConnection, sends "accept", and transitions to Negotiating.

Exceptions

std::logic_error if not currently in the IncomingInit state.

reject

void reject(const std::string & reason)

Reject an incoming call. Sends a "reject" control message and transitions to Ended.

Parameters

reason Human-readable reason string forwarded to the remote peer.

Exceptions

std::logic_error if not currently in the IncomingInit state.

hangup

void hangup(const std::string & reason)

Terminate any non-idle call phase. Sends a "hangup" control message, closes the PeerConnection, and transitions to Ended. Safe to call from any non-Idle/Ended state.

Parameters

reason Human-readable reason string forwarded to the remote peer.

sendData

void sendData(const std::string & message)

Send a UTF-8 string message over the data channel. Silently dropped if the data channel is not open.

Parameters

message String to send.

sendData

void sendData(const std::byte * data, size_t size)

Send raw binary data over the data channel. Silently dropped if the data channel is not open.

Parameters

data Pointer to the byte buffer.
size Number of bytes to send.

state

const

State state() const

Current session state. Thread-safe.

remotePeerId

const

std::string remotePeerId() const

Identifier of the remote peer for the current or most recent call. Empty when Idle.

media

MediaBridge & media()

Media bridge for this session. Valid for the lifetime of the PeerSession.

media

const

const MediaBridge & media() const

Media bridge for this session. Valid for the lifetime of the PeerSession.

peerConnection

std::shared_ptr< rtc::PeerConnection > peerConnection()

The underlying PeerConnection, or nullptr when Idle/Ended.

dataChannel

std::shared_ptr< rtc::DataChannel > dataChannel()

The data channel, or nullptr if none is open.

Public Types

Name	Description
`State`	High-level lifecycle phases for a single peer-to-peer call session.

State

enum State

High-level lifecycle phases for a single peer-to-peer call session.

Value	Description
`Idle`	No active call.
`OutgoingInit`	Outgoing call announced, waiting for accept/reject.
`IncomingInit`	Incoming call announced, waiting for accept/reject.
`Negotiating`	PeerConnection exists and SDP/ICE negotiation is in progress.
`Active`	Media or data is flowing.
`Ending`	Local teardown is in progress.
`Ended`	Call ended (transient; auto-resets to Idle)

Private Attributes

Return	Name	Description
`SignallingInterface &`	`_signaller`
`Config`	`_config`
`MediaBridge`	`_media`
`State`	`_state`
`std::string`	`_remotePeerId`
`std::shared_ptr< rtc::PeerConnection >`	`_pc`
`std::shared_ptr< rtc::DataChannel >`	`_dc`
`std::shared_ptr< CallbackGuard >`	`_callbackGuard`
`bool`	`_remoteDescriptionSet`
`std::vector< PendingCandidate >`	`_pendingRemoteCandidates`
`Synchronizer`	`_callbackSync`
`std::deque< std::function< void()> >`	`_pendingCallbacks`
`std::mutex`	`_callbackMutex`
`std::mutex`	`_mutex`

_signaller

SignallingInterface & _signaller

_config

Config _config

_media

MediaBridge _media

_state

State _state =

_remotePeerId

std::string _remotePeerId

_pc

std::shared_ptr< rtc::PeerConnection > _pc

_dc

std::shared_ptr< rtc::DataChannel > _dc

_callbackGuard

std::shared_ptr< CallbackGuard > _callbackGuard = std::make_shared<CallbackGuard>()

_remoteDescriptionSet

bool _remoteDescriptionSet = false

_pendingRemoteCandidates

std::vector< PendingCandidate > _pendingRemoteCandidates

_callbackSync

Synchronizer _callbackSync

_pendingCallbacks

std::deque< std::function< void()> > _pendingCallbacks

_callbackMutex

std::mutex _callbackMutex

_mutex

std::mutex _mutex

Private Methods

Return	Name	Description
`void`	`onSdpReceived`
`void`	`onCandidateReceived`
`void`	`onControlReceived`
`std::shared_ptr< rtc::PeerConnection >`	`createPeerConnection`
`void`	`setupPeerConnectionCallbacks`
`void`	`beginEndCall`
`void`	`finishEndCall`
`void`	`transitionEndedToIdle`
`void`	`enqueueCallback`
`void`	`drainCallbacks`

onSdpReceived

void onSdpReceived(const std::string & peerId, const std::string & type, const std::string & sdp)

onCandidateReceived

void onCandidateReceived(const std::string & peerId, const std::string & candidate, const std::string & mid)

onControlReceived

void onControlReceived(const std::string & peerId, const std::string & type, const std::string & reason)

createPeerConnection

std::shared_ptr< rtc::PeerConnection > createPeerConnection(bool createDataChannel, const MediaBridge::Options * mediaOpts)

setupPeerConnectionCallbacks

void setupPeerConnectionCallbacks(const std::shared_ptr< rtc::PeerConnection > & pc)

beginEndCall

void beginEndCall(const std::string & reason, std::shared_ptr< rtc::PeerConnection > & pc, std::shared_ptr< rtc::DataChannel > & dc)

finishEndCall

void finishEndCall()

transitionEndedToIdle

void transitionEndedToIdle()

enqueueCallback

void enqueueCallback(std::function< void()> callback)

drainCallbacks

void drainCallbacks()

Built with