MoQ Session endpoint supporting connection-explicit operations. More...

#include <session.h>

Inheritance diagram for quicr::Session:

Classes
struct	Callbacks
	Callback interface for session events common to both client and server mode. More...

struct	ClientCallbacks
	Callback interface for session events specific to client mode. More...

struct	ConnectionRemoteInfo
	Connection remote information. More...

struct	ServerCallbacks
	Callback interface for session events specific to server mode. More...

struct	SubscribeContext

Public Types
enum class	Status : uint8_t { kReady = 0 , kNotReady , kInternalError , kInvalidParams , kConnecting , kDisconnecting , kNotConnected , kFailedToConnect , kPendingPeerSetup }
	Status of the transport. More...

enum class	ControlMessageStatus : uint8_t { kMessageIncomplete , kMessageComplete , kStreamBufferCannotBeZero , kStreamBufferMissingType , kUnsupportedMessageType }
	Control message status codes. More...

enum class	StreamDataMessageStatus : uint8_t
	Reserved status type for stream-data parsing. More...

enum class	ConnectionStatus : uint8_t { kNotConnected = 0 , kConnecting , kConnected , kIdleTimeout , kClosedByRemote }
	Connection status codes. More...

Public Member Functions
virtual	~Session ()
	Destroy the session after detaching and releasing its owned state. More...

std::shared_ptr< Connection >	GetDefaultConnection () const noexcept
	Return shared ownership of the session's default connection. More...

const std::shared_ptr< Clock > &	GetTickService () const noexcept
	Return shared ownership of the tick service used by the session. More...

const std::shared_ptr< Logger > &	GetLogger () const noexcept
	Return the optional logger used by the session. More...

Status	GetStatus () const noexcept
	Return the current session status. More...

void	Disconnect ()
	Close the underlying transport connection and detach this session as delegate. More...

void	SubscribeTrack (std::shared_ptr< SubscribeTrackHandler > track_handler)
	Subscribe to a track. More...

void	UnsubscribeTrack (const std::shared_ptr< SubscribeTrackHandler > &track_handler)
	Unsubscribe track. More...

void	UpdateTrackSubscription (std::shared_ptr< SubscribeTrackHandler > track_handler)
	Update Subscription to a track. More...

void	PublishTrack (std::shared_ptr< PublishTrackHandler > track_handler)
	Publish to a track. More...

void	UnpublishTrack (const std::shared_ptr< PublishTrackHandler > &track_handler)
	Unpublish track. More...

void	PublishNamespace (std::shared_ptr< PublishNamespaceHandler > ns_handler, bool passive=false)
	Publish a track namespace. More...

void	PublishNamespaceDone (const std::shared_ptr< PublishNamespaceHandler > &track_handler)
	Unpublish track namespace. More...

void	SubscribeNamespace (std::shared_ptr< SubscribeNamespaceHandler > handler)
	Subscribe to a prefix namespace on a specific connection. More...

void	UnsubscribeNamespace (const std::shared_ptr< SubscribeNamespaceHandler > &handler)
	Unsubscribe from a prefix namespace on a specific connection. More...

void	SendNamespace (const TrackNamespace &track_namespace)
	Tell subscribe-namespace subscribers on this connection that a namespace is active. More...

void	SendNamespaceDone (const TrackNamespace &track_namespace)
	Tell subscribe-namespace subscribers on this connection that a namespace is no longer active. More...

void	FetchTrack (std::shared_ptr< FetchTrackHandler > track_handler)
	Fetch track. More...

void	CancelFetchTrack (std::shared_ptr< FetchTrackHandler > track_handler)
	Cancel Fetch track. More...

void	RequestTrackStatus (std::shared_ptr< TrackStatusHandler > handler)
	Request track status. More...

void	GoAway (const std::string &new_session_uri, std::chrono::milliseconds timeout, std::optional< std::uint64_t > first_unprocessed_request_id=std::nullopt)
	Send GOAWAY on this session's control stream. More...

void	GoAway (const std::string &new_session_uri, std::chrono::milliseconds timeout, const std::shared_ptr< TrackHandler > &handler)
	Send GOAWAY on one request stream. More...

Server Relay Methods
Methods for relaying published content to subscribers. Server mode only.
void	BindPublisherTrack (std::uint64_t src_id, uint64_t request_id, const std::shared_ptr< PublishTrackHandler > &track_handler, bool ephemeral=false)
	Bind a server publish track handler based on a subscribe. More...

void	UnbindPublisherTrack (std::uint64_t src_id, const std::shared_ptr< PublishTrackHandler > &track_handler, bool send_publish_done=false)
	Unbind a server publish track handler. More...

void	BindFetchTrack (std::shared_ptr< PublishFetchHandler > track_handler)
	Bind a server fetch publisher track handler. More...

void	UnbindFetchTrack (const std::shared_ptr< PublishFetchHandler > &track_handler)
	Unbind a server fetch publisher track handler. More...

Static Public Member Functions
static std::shared_ptr< Session >	Create (const ClientConfig &cfg, std::shared_ptr< Transport > transport, std::shared_ptr< Connection > connection, std::shared_ptr< ClientCallbacks > callbacks, std::shared_ptr< Clock > clock, std::shared_ptr< Logger > logger=nullptr)
	Create a client-mode endpoint. More...

static std::shared_ptr< Session >	Create (const ServerConfig &cfg, std::shared_ptr< Transport > transport, std::shared_ptr< Connection > connection, std::shared_ptr< ServerCallbacks > callbacks, std::shared_ptr< Clock > clock, std::shared_ptr< Logger > logger=nullptr)
	Create a server-mode endpoint. More...

Protected Member Functions
	Session ()=delete
	Default construction is disabled; use a mode-specific constructor. More...

	Session (const ClientConfig &cfg, std::shared_ptr< Transport > transport, std::shared_ptr< Connection > connection, std::shared_ptr< ClientCallbacks > callbacks, std::shared_ptr< Logger > logger)
	Client mode constructor. More...

	Session (const ServerConfig &cfg, std::shared_ptr< Transport > transport, std::shared_ptr< Connection > connection, std::shared_ptr< ServerCallbacks > callbacks, std::shared_ptr< Logger > logger)
	Server mode constructor. More...

	Session (const ClientConfig &cfg, std::shared_ptr< Transport > transport, std::shared_ptr< Connection > connection, std::shared_ptr< ClientCallbacks > callbacks, std::shared_ptr< Clock > clock, std::shared_ptr< Logger > logger)
	Client mode constructor with explicit tick service. More...

	Session (const ServerConfig &cfg, std::shared_ptr< Transport > transport, std::shared_ptr< Connection > connection, std::shared_ptr< ServerCallbacks > callbacks, std::shared_ptr< Clock > clock, std::shared_ptr< Logger > logger)
	Server mode constructor with explicit tick service. More...

void	OnStreamClosed (const std::shared_ptr< Stream > &stream, StreamClosedFlag flag) override
	Handle closure of a stream delegated by the connection. More...

Detailed Description

MoQ Session endpoint supporting connection-explicit operations.

Unified MoQ transport endpoint that operates in either client or server mode depending on configuration. Client provides the single-connection convenience API for outbound clients.

Member Enumeration Documentation

◆ ConnectionStatus

enum quicr::Session::ConnectionStatus : uint8_t

strong

Connection status codes.

Enumerator
kNotConnected	No active connection.
kConnecting	Connection establishment is in progress.
kConnected	Connection is active.
kIdleTimeout	Connection closed after an idle timeout.
kClosedByRemote	Connection was closed by the peer.

◆ ControlMessageStatus

enum quicr::Session::ControlMessageStatus : uint8_t

strong

Control message status codes.

Enumerator
kMessageIncomplete	control message is incomplete and more data is needed
kMessageComplete	control message is complete and stream buffer get any has complete message
kStreamBufferCannotBeZero	stream buffer cannot be zero when parsing message type
kStreamBufferMissingType	connection context is missing message type
kUnsupportedMessageType	Unsupported MOQT message type.

◆ Status

enum quicr::Session::Status : uint8_t

strong

Status of the transport.

Enumerator
kReady	Setup is complete and the session is ready.
kNotReady	Session is not ready for protocol operations.
kInternalError	Session encountered an internal failure.
kInvalidParams	Session configuration or peer parameters are invalid.
kConnecting	Underlying connection establishment is in progress.
kDisconnecting	Session teardown is in progress.
kNotConnected	No active underlying connection exists.
kFailedToConnect	Underlying connection establishment failed.
kPendingPeerSetup	Local setup was sent and peer setup is still pending.

◆ StreamDataMessageStatus

enum quicr::Session::StreamDataMessageStatus : uint8_t

strong

Reserved status type for stream-data parsing.

Constructor & Destructor Documentation

◆ ~Session()

virtual quicr::Session::~Session ( )

virtual

Destroy the session after detaching and releasing its owned state.

◆ Session() [1/5]

quicr::Session::Session ( )

protecteddelete

Default construction is disabled; use a mode-specific constructor.

◆ Session() [2/5]

quicr::Session::Session	(	const ClientConfig &	cfg,
		std::shared_ptr< Transport >	transport,
		std::shared_ptr< Connection >	connection,
		std::shared_ptr< ClientCallbacks >	callbacks,
		std::shared_ptr< Logger >	logger
	)

protected

Client mode constructor.

Parameters

cfg	MoQ Client Configuration
transport	Transport retained by the session.
connection	Connection retained by the session.
callbacks	Client callbacks retained by the session; may be null.
logger	Optional logger retained by the session.

◆ Session() [3/5]

quicr::Session::Session	(	const ServerConfig &	cfg,
		std::shared_ptr< Transport >	transport,
		std::shared_ptr< Connection >	connection,
		std::shared_ptr< ServerCallbacks >	callbacks,
		std::shared_ptr< Logger >	logger
	)

protected

Server mode constructor.

Parameters

cfg	MoQ Server Configuration
transport	Transport retained by the session.
connection	Connection retained by the session.
callbacks	Server callbacks retained by the session; may be null.
logger	Optional logger retained by the session.

◆ Session() [4/5]

quicr::Session::Session	(	const ClientConfig &	cfg,
		std::shared_ptr< Transport >	transport,
		std::shared_ptr< Connection >	connection,
		std::shared_ptr< ClientCallbacks >	callbacks,
		std::shared_ptr< Clock >	clock,
		std::shared_ptr< Logger >	logger
	)

protected

Client mode constructor with explicit tick service.

Parameters

cfg	MoQ Instance Client Configuration
transport	Transport retained by the session.
connection	Connection retained by the session.
callbacks	Client callbacks retained by the session; may be null.
clock	Shared pointer to the tick service to use
logger	Optional logger retained by the session.

◆ Session() [5/5]

quicr::Session::Session	(	const ServerConfig &	cfg,
		std::shared_ptr< Transport >	transport,
		std::shared_ptr< Connection >	connection,
		std::shared_ptr< ServerCallbacks >	callbacks,
		std::shared_ptr< Clock >	clock,
		std::shared_ptr< Logger >	logger
	)

protected

Server mode constructor with explicit tick service.

Parameters

cfg	MoQ Server Configuration
transport	Transport retained by the session.
connection	Connection retained by the session.
callbacks	Server callbacks retained by the session; may be null.
clock	Shared pointer to the tick service to use
logger	Optional logger retained by the session.

Member Function Documentation

◆ BindFetchTrack()

void quicr::Session::BindFetchTrack ( std::shared_ptr< PublishFetchHandler > track_handler )

Bind a server fetch publisher track handler.

Parameters

track_handler The fetch publisher

Precondition: track_handler must not be null.; track_handler must already carry the inbound fetch request identifier.

◆ BindPublisherTrack()

void quicr::Session::BindPublisherTrack	(	std::uint64_t	src_id,
		uint64_t	request_id,
		const std::shared_ptr< PublishTrackHandler > &	track_handler,
		bool	ephemeral = `false`
	)

Bind a server publish track handler based on a subscribe.

The server will create a server publish track handler based on a received subscribe. It will use this handler to send objects to the subscriber.

Parameters

src_id	Connection or peering ID for publisher origin
request_id	Request ID from the received subscribe
track_handler	Server publish track handler
ephemeral	Indicates if persistent state tracking is needed

Precondition: track_handler must not be null.

◆ CancelFetchTrack()

void quicr::Session::CancelFetchTrack ( std::shared_ptr< FetchTrackHandler > track_handler )

Cancel Fetch track.

Parameters

track_handler Fetch Track handler to cancel.

Precondition: track_handler must not be null.

◆ Create() [1/2]

static std::shared_ptr<Session> quicr::Session::Create	(	const ClientConfig &	cfg,
		std::shared_ptr< Transport >	transport,
		std::shared_ptr< Connection >	connection,
		std::shared_ptr< ClientCallbacks >	callbacks,
		std::shared_ptr< Clock >	clock,
		std::shared_ptr< Logger >	logger = `nullptr`
	)

inlinestatic

Create a client-mode endpoint.

Parameters

cfg	MoQ Client Configuration
transport	Transport retained by the session.
connection	Connection retained by the session.
callbacks	Client callbacks retained by the session; may be null.
clock	Clock retained by the session; must not be null.
logger	Optional logger retained by the session.

Returns: Shared ownership of the new session.

Examples: simple_publish/main.cpp, and simple_subscribe/main.cpp.

◆ Create() [2/2]

static std::shared_ptr<Session> quicr::Session::Create	(	const ServerConfig &	cfg,
		std::shared_ptr< Transport >	transport,
		std::shared_ptr< Connection >	connection,
		std::shared_ptr< ServerCallbacks >	callbacks,
		std::shared_ptr< Clock >	clock,
		std::shared_ptr< Logger >	logger = `nullptr`
	)

inlinestatic

Create a server-mode endpoint.

Parameters

cfg	MoQ Server Configuration
transport	Transport retained by the session.
connection	Connection retained by the session.
callbacks	Server callbacks retained by the session; may be null.
clock	Clock retained by the session; must not be null.
logger	Optional logger retained by the session.

Returns: Shared ownership of the new session.

◆ Disconnect()

void quicr::Session::Disconnect ( )

Close the underlying transport connection and detach this session as delegate.

Note: The session object and connection handle may remain alive, but no further connection callbacks are delivered to this session.

◆ FetchTrack()

void quicr::Session::FetchTrack ( std::shared_ptr< FetchTrackHandler > track_handler )

Fetch track.

Parameters

track_handler Track handler used for fetching

Precondition: track_handler must not be null.

◆ GetDefaultConnection()

std::shared_ptr<Connection> quicr::Session::GetDefaultConnection ( ) const

noexcept

Return shared ownership of the session's default connection.

Returns: Reference to the default connection handle currently retained for the session.

◆ GetLogger()

const std::shared_ptr<Logger>& quicr::Session::GetLogger ( ) const

inlinenoexcept

Return the optional logger used by the session.

Returns: Reference to the logger handle, which may be null.

◆ GetStatus()

Status quicr::Session::GetStatus ( ) const

inlinenoexcept

Return the current session status.

Returns: Atomically loaded lifecycle state.

◆ GetTickService()

const std::shared_ptr<Clock>& quicr::Session::GetTickService ( ) const

inlinenoexcept

Return shared ownership of the tick service used by the session.

Returns: Reference to the tick-service handle retained for the session's lifetime.

◆ GoAway() [1/2]

void quicr::Session::GoAway	(	const std::string &	new_session_uri,
		std::chrono::milliseconds	timeout,
		const std::shared_ptr< TrackHandler > &	handler
	)

Send GOAWAY on one request stream.

Parameters

new_session_uri	URI the peer should migrate to, or empty to reuse the current URI.
timeout	How long the peer has to migrate before the session may be closed.
handler	The handler for the request we are sending away.

◆ GoAway() [2/2]

void quicr::Session::GoAway	(	const std::string &	new_session_uri,
		std::chrono::milliseconds	timeout,
		std::optional< std::uint64_t >	first_unprocessed_request_id = `std::nullopt`
	)

Send GOAWAY on this session's control stream.

Parameters

new_session_uri	URI the peer should migrate to, or empty to reuse the current URI.
timeout	How long the peer has to migrate before the session may be closed.
first_unprocessed_request_id	Smallest peer request ID that may not have been processed.

◆ OnStreamClosed()

void quicr::Session::OnStreamClosed	(	const std::shared_ptr< Stream > &	stream,
		StreamClosedFlag	flag
	)

overrideprotectedvirtual

Handle closure of a stream delegated by the connection.

Parameters

stream	Closed stream and its associated request state.
flag	Event that closed the stream direction.

Implements quicr::Connection::Delegate.

◆ PublishNamespace()

void quicr::Session::PublishNamespace	(	std::shared_ptr< PublishNamespaceHandler >	ns_handler,
		bool	passive = `false`
	)

Publish a track namespace.

Parameters

ns_handler	Namespace handler to use for track related functions and callbacks
passive	True indicates that PUBLISH_NAMESPACE will not be sent

Precondition: ns_handler must not be null.

◆ PublishNamespaceDone()

void quicr::Session::PublishNamespaceDone ( const std::shared_ptr< PublishNamespaceHandler > & track_handler )

Unpublish track namespace.

Parameters

track_handler Published namespace handler to finish.

Precondition: track_handler must not be null.; track_handler must retain the request stream and request identifier assigned by PublishNamespace.

◆ PublishTrack()

void quicr::Session::PublishTrack ( std::shared_ptr< PublishTrackHandler > track_handler )

Publish to a track.

Parameters

track_handler Track handler to use for track related functions and callbacks

Precondition: track_handler must not be null.

◆ RequestTrackStatus()

void quicr::Session::RequestTrackStatus ( std::shared_ptr< TrackStatusHandler > handler )

Request track status.

Parameters

handler Handler for this query's status and response.

Exceptions

std::invalid_argument	if handler is null.
std::logic_error	if the handler has a pending request.

◆ SendNamespace()

void quicr::Session::SendNamespace ( const TrackNamespace & track_namespace )

Tell subscribe-namespace subscribers on this connection that a namespace is active.

Sends NAMESPACE on each SUBSCRIBE_NAMESPACE request stream whose prefix matches. The value on the wire is the namespace suffix relative to that prefix.

Parameters

track_namespace Fully qualified namespace that became active

◆ SendNamespaceDone()

void quicr::Session::SendNamespaceDone ( const TrackNamespace & track_namespace )

Tell subscribe-namespace subscribers on this connection that a namespace is no longer active.

Parameters

track_namespace Fully qualified namespace that ended

◆ SubscribeNamespace()

void quicr::Session::SubscribeNamespace ( std::shared_ptr< SubscribeNamespaceHandler > handler )

Subscribe to a prefix namespace on a specific connection.

Parameters

handler Namespace handler to subscribe with

Precondition: handler must not be null.

◆ SubscribeTrack()

void quicr::Session::SubscribeTrack ( std::shared_ptr< SubscribeTrackHandler > track_handler )

Subscribe to a track.

Parameters

track_handler Track handler to use for track related functions and callbacks

Precondition: track_handler must not be null.

Exceptions

std::runtime_error if a publisher-initiated subscription lacks required request metadata.

◆ UnbindFetchTrack()

void quicr::Session::UnbindFetchTrack ( const std::shared_ptr< PublishFetchHandler > & track_handler )

Unbind a server fetch publisher track handler.

Parameters

track_handler The fetch publisher

Precondition: track_handler must not be null.; track_handler must have a request identifier assigned by BindFetchTrack.

◆ UnbindPublisherTrack()

void quicr::Session::UnbindPublisherTrack	(	std::uint64_t	src_id,
		const std::shared_ptr< PublishTrackHandler > &	track_handler,
		bool	send_publish_done = `false`
	)

Unbind a server publish track handler.

Removes a server publish track handler state.

Parameters

src_id	Connection or peering ID of the receiving publisher
track_handler	Server publish track handler
send_publish_done	Indicates to send publish done or not

Precondition: track_handler must not be null.; track_handler must have a request identifier assigned by BindPublisherTrack.

◆ UnpublishTrack()

void quicr::Session::UnpublishTrack ( const std::shared_ptr< PublishTrackHandler > & track_handler )

Unpublish track.

Parameters

track_handler Track handler used when published track

Precondition: track_handler must not be null.

◆ UnsubscribeNamespace()

void quicr::Session::UnsubscribeNamespace ( const std::shared_ptr< SubscribeNamespaceHandler > & handler )

Unsubscribe from a prefix namespace on a specific connection.

Parameters

handler Namespace handler to unsubscribe

Precondition: handler must not be null.

◆ UnsubscribeTrack()

void quicr::Session::UnsubscribeTrack ( const std::shared_ptr< SubscribeTrackHandler > & track_handler )

Unsubscribe track.

Parameters

track_handler Track handler to use for track related functions and callbacks

Precondition: track_handler must not be null.

◆ UpdateTrackSubscription()

void quicr::Session::UpdateTrackSubscription ( std::shared_ptr< SubscribeTrackHandler > track_handler )

Update Subscription to a track.

Parameters

track_handler Track handler to use for track related functions and callbacks

Precondition: track_handler must not be null.

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

include/quicr/session.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ ConnectionStatus

◆ ControlMessageStatus

◆ Status

◆ StreamDataMessageStatus

Constructor & Destructor Documentation

◆ ~Session()

◆ Session() [1/5]

◆ Session() [2/5]

◆ Session() [3/5]

◆ Session() [4/5]

◆ Session() [5/5]

Member Function Documentation

◆ BindFetchTrack()

◆ BindPublisherTrack()

◆ CancelFetchTrack()

◆ Create() [1/2]

◆ Create() [2/2]

◆ Disconnect()

◆ FetchTrack()

◆ GetDefaultConnection()

◆ GetLogger()

◆ GetStatus()

◆ GetTickService()

◆ GoAway() [1/2]

◆ GoAway() [2/2]

◆ OnStreamClosed()

◆ PublishNamespace()

◆ PublishNamespaceDone()

◆ PublishTrack()

◆ RequestTrackStatus()

◆ SendNamespace()

◆ SendNamespaceDone()

◆ SubscribeNamespace()

◆ SubscribeTrack()

◆ UnbindFetchTrack()

◆ UnbindPublisherTrack()

◆ UnpublishTrack()

◆ UnsubscribeNamespace()

◆ UnsubscribeTrack()

◆ UpdateTrackSubscription()