Receives namespace or track publication notifications below a prefix. More...

#include <subscribe_namespace_handler.h>

Inheritance diagram for quicr::SubscribeNamespaceHandler:

Public Types
enum class	Mode { kNamespaces , kTracks }
	Selects which notification family the peer sends for the prefix. More...

enum class	Status : uint8_t { kOk = 0 , kNotSubscribed , kError }
	Status codes for the subscribe track. More...

Public Member Functions
virtual	~SubscribeNamespaceHandler ()
	Destroys the handler; destruction currently sends no protocol message. More...

virtual void	StatusChanged (Status status)
	Notification of subscribe status. More...

const TrackNamespace &	GetPrefix () const noexcept

messages::FilterType	GetFilterType () const noexcept

constexpr const messages::Filter &	GetFilter () const noexcept

constexpr Status	GetStatus () const noexcept
	Get the status of the subscribe. More...

std::optional< Error< ErrorCode > >	GetError () const noexcept
	Get the error code and reason for the subscribe namespace, if any. More...

constexpr Mode	GetMode () const noexcept
	Get the mode this handler is operating in. More...

TrackNamespace	ExpandSuffix (const TrackNamespace &suffix) const
	Fully qualifies a NAMESPACE suffix relative to the subscribed prefix. More...

template<typename T >
requires std::is_base_of_v< TrackHandler, T > std::shared_ptr< T >	Get ()
	Get the derived type of the track handler. More...

void	SetRequestId (std::optional< uint64_t > request_id)
	Sets or clears the connection-scoped request ID. More...

std::optional< uint64_t >	GetRequestId () const noexcept
	Get the request ID. More...

std::optional< uint64_t >	GetRequestStreamId () const
	Get the stream ID of the request control stream. More...

FullTrackName	GetFullTrackName () const noexcept
	Get the full track name. More...

uint64_t	GetConnectionId () const noexcept
	Gets the transport connection identifier assigned by the session. More...

std::shared_ptr< Connection >	GetConnection () const

Binding	GetBinding () const

Static Public Member Functions
static auto	Create (const TrackNamespace &prefix, const Mode mode, const messages::Filter &filter=std::monostate{})
	Creates a namespace subscription with shared ownership. More...

Protected Member Functions
	SubscribeNamespaceHandler (const TrackNamespace &prefix, Mode mode, const messages::Filter &filter=std::monostate{})
	Constructs a namespace subscription. More...

virtual void	NamespaceReceived ([[maybe_unused]] const TrackNamespace &name_space)
	Reports a NAMESPACE notification in `kNamespaces` mode. More...

virtual void	NamespaceDoneReceived ([[maybe_unused]] const TrackNamespace &name_space)
	Reports a NAMESPACE_DONE notification in `kNamespaces` mode. More...

void	SetStatus (const Status status) noexcept
	Set the subscribe status. More...

void	SetError (const Error< ErrorCode > &error)
	Stores an error and transitions to `kError`. More...

void	RequestOkReceived (const messages::Parameters &params) override
	Handles acceptance by validating empty parameters and entering `kOk`. More...

Reply< messages::Parameters, ErrorCode >	RequestUpdateReceived (const messages::Parameters &params) override
	Rejects updates to a namespace subscription. More...

void	RequestError (ErrorCode error_code, std::string reason) override
	Stores a request error and enters `kError`. More...

void	SetTransport (std::shared_ptr< Session > transport)
	Sets the session used for control and data operations. More...

const std::weak_ptr< Session > &	GetSession () const noexcept
	Gets the non-owning session handle. More...

Protected Attributes
FullTrackName	full_track_name_
	Full track identity retained for the handler's lifetime. More...

std::mutex	binding_operation_mutex_

Detailed Description

Receives namespace or track publication notifications below a prefix.

Create the handler, customize its protected callbacks in a derived class, and pass it to the session. Callback and status mutation occur on session processing paths; getters are not synchronized with those callbacks.

Member Enumeration Documentation

◆ Mode

enum quicr::SubscribeNamespaceHandler::Mode

strong

Selects which notification family the peer sends for the prefix.

Enumerator
kNamespaces	Receive NAMESPACE notifications for matching namespaces.
kTracks	Receive PUBLISH notifications for matching tracks.

◆ Status

enum quicr::SubscribeNamespaceHandler::Status : uint8_t

strong

Status codes for the subscribe track.

Enumerator
kOk	The peer accepted the subscription.
kNotSubscribed	Initial state; no active namespace subscription.
kError	The peer or library rejected the request; inspect `GetError()`.

Constructor & Destructor Documentation

◆ SubscribeNamespaceHandler()

quicr::SubscribeNamespaceHandler::SubscribeNamespaceHandler	(	const TrackNamespace &	prefix,
		Mode	mode,
		const messages::Filter &	filter = `std::monostate{}`
	)

protected

Constructs a namespace subscription.

Parameters

prefix	Namespace prefix against which notifications are matched.
mode	Kind of notification to receive.
filter	Protocol filter sent with the subscription.

◆ ~SubscribeNamespaceHandler()

virtual quicr::SubscribeNamespaceHandler::~SubscribeNamespaceHandler ( )

virtual

Destroys the handler; destruction currently sends no protocol message.

Member Function Documentation

◆ Create()

static auto quicr::SubscribeNamespaceHandler::Create	(	const TrackNamespace &	prefix,
		const Mode	mode,
		const messages::Filter &	filter = `std::monostate{}`
	)

inlinestatic

Creates a namespace subscription with shared ownership.

Parameters

prefix	Namespace prefix against which notifications are matched.
mode	Kind of notification to receive.
filter	Protocol filter sent with the subscription.

Returns: Shared ownership of the new handler.

◆ ExpandSuffix()

TrackNamespace quicr::SubscribeNamespaceHandler::ExpandSuffix ( const TrackNamespace & suffix ) const

Fully qualifies a NAMESPACE suffix relative to the subscribed prefix.

Parameters

suffix Relative namespace entries received from the peer.

Returns: A new namespace containing the prefix followed by the suffix.

◆ Get()

template<typename T >

requires std::is_base_of_v<TrackHandler, T> std::shared_ptr<T> quicr::TrackHandler::Get ( )

inlineinherited

Get the derived type of the track handler.

Template Parameters

T	Derived type of the track handler.

Returns: Shared ownership cast to T, or null when the dynamic type is incompatible.

Exceptions

std::bad_weak_ptr if this object is not currently owned by a shared_ptr.

◆ GetBinding()

Binding quicr::TrackHandler::GetBinding ( ) const

inlineinherited

◆ GetConnection()

std::shared_ptr<Connection> quicr::TrackHandler::GetConnection ( ) const

inherited

◆ GetConnectionId()

uint64_t quicr::TrackHandler::GetConnectionId ( ) const

inlinenoexceptinherited

Gets the transport connection identifier assigned by the session.

Returns: Connection ID, or the initial value zero before assignment.

◆ GetError()

std::optional<Error<ErrorCode> > quicr::SubscribeNamespaceHandler::GetError ( ) const

inlinenoexcept

Get the error code and reason for the subscribe namespace, if any.

Returns: Subscribe namespace error code and reason.

◆ GetFilter()

constexpr const messages::Filter& quicr::SubscribeNamespaceHandler::GetFilter ( ) const

inlineconstexprnoexcept

Returns: Borrowed immutable subscription filter, valid for this handler's lifetime.

◆ GetFilterType()

messages::FilterType quicr::SubscribeNamespaceHandler::GetFilterType ( ) const

inlinenoexcept

Returns: The protocol discriminator for GetFilter().

◆ GetFullTrackName()

FullTrackName quicr::TrackHandler::GetFullTrackName ( ) const

inlinenoexceptinherited

Get the full track name.

Returns: A copy of the full track name.

◆ GetMode()

constexpr Mode quicr::SubscribeNamespaceHandler::GetMode ( ) const

inlineconstexprnoexcept

Get the mode this handler is operating in.

Returns: Subscribe mode for this namespace handler.

◆ GetPrefix()

const TrackNamespace& quicr::SubscribeNamespaceHandler::GetPrefix ( ) const

inlinenoexcept

Returns: Borrowed immutable prefix, valid for this handler's lifetime.

◆ GetRequestId()

std::optional<uint64_t> quicr::TrackHandler::GetRequestId ( ) const

inlinenoexceptinherited

Get the request ID.

Returns: Current connection-scoped request ID, or std::nullopt when none is assigned.

◆ GetRequestStreamId()

std::optional<uint64_t> quicr::TrackHandler::GetRequestStreamId ( ) const

inherited

Get the stream ID of the request control stream.

Returns: Request stream's ID, or std::nullopt if no stream is attached.

Note: Thread-safe with request-stream installation/removal.

◆ GetSession()

const std::weak_ptr<Session>& quicr::TrackHandler::GetSession ( ) const

protectednoexceptinherited

Gets the non-owning session handle.

Returns: Borrowed reference to the stored weak pointer, valid for this handler's lifetime. Callers must lock it before use.

◆ GetStatus()

constexpr Status quicr::SubscribeNamespaceHandler::GetStatus ( ) const

inlineconstexprnoexcept

Get the status of the subscribe.

Returns: Status of the subscribe

◆ NamespaceDoneReceived()

virtual void quicr::SubscribeNamespaceHandler::NamespaceDoneReceived ( [[maybe_unused] ] const TrackNamespace & name_space )

inlineprotectedvirtual

Reports a NAMESPACE_DONE notification in kNamespaces mode.

Parameters

name_space Namespace relative to GetPrefix().

Note: The default implementation does nothing. Called synchronously on a session path.

◆ NamespaceReceived()

virtual void quicr::SubscribeNamespaceHandler::NamespaceReceived ( [[maybe_unused] ] const TrackNamespace & name_space )

inlineprotectedvirtual

Reports a NAMESPACE notification in kNamespaces mode.

Parameters

name_space Namespace relative to GetPrefix(); use ExpandSuffix() to qualify it.

Note: The default implementation does nothing. Called synchronously on a session path.

◆ RequestError()

void quicr::SubscribeNamespaceHandler::RequestError	(	ErrorCode	error_code,
		std::string	reason
	)

inlineoverrideprotectedvirtual

Stores a request error and enters kError.

Parameters

error_code	Peer-provided error code.
reason	Peer-provided reason, moved into the stored error.

Reimplemented from quicr::TrackHandler.

◆ RequestOkReceived()

void quicr::SubscribeNamespaceHandler::RequestOkReceived ( const messages::Parameters & params )

overrideprotectedvirtual

Handles acceptance by validating empty parameters and entering kOk.

Parameters

params Response parameters, which must be empty.

Exceptions

messages::ProtocolViolationException if unsupported parameters are present.

Implements quicr::TrackHandler.

◆ RequestUpdateReceived()

Reply<messages::Parameters, ErrorCode> quicr::SubscribeNamespaceHandler::RequestUpdateReceived ( const messages::Parameters & params )

overrideprotectedvirtual

Rejects updates to a namespace subscription.

Parameters

params Unused update parameters.

Returns: Never returns.

Exceptions

messages::ProtocolViolationException Always.

Implements quicr::TrackHandler.

◆ SetError()

void quicr::SubscribeNamespaceHandler::SetError ( const Error< ErrorCode > & error )

inlineprotected

Stores an error and transitions to kError.

Parameters

error Error code and optional reason, copied into the handler.

◆ SetRequestId()

void quicr::TrackHandler::SetRequestId ( std::optional< uint64_t > request_id )

inlineinherited

Sets or clears the connection-scoped request ID.

Parameters

request_id Request ID assigned by the session, or std::nullopt when unbound.

Note: Thread-safe with request-stream installation and removal.

◆ SetStatus()

void quicr::SubscribeNamespaceHandler::SetStatus ( const Status status )

inlineprotectednoexcept

Set the subscribe status.

Parameters

status Status of the subscribe

Entering kError without a preceding SetError() installs an internal-error fallback, then invokes StatusChanged even if the value did not change.

◆ SetTransport()

void quicr::TrackHandler::SetTransport ( std::shared_ptr< Session > transport )

protectedinherited

Sets the session used for control and data operations.

Parameters

transport Session retained weakly; passing null clears effective access.

Note: The caller must keep the session alive independently.

◆ StatusChanged()

virtual void quicr::SubscribeNamespaceHandler::StatusChanged ( Status status )

virtual

Notification of subscribe status.

Notification of the subscribe status

Parameters

status Indicates status of the subscribe

Note: The default implementation does nothing. Called synchronously on a session path.

Member Data Documentation

◆ binding_operation_mutex_

std::mutex quicr::TrackHandler::binding_operation_mutex_

protectedinherited

◆ full_track_name_

FullTrackName quicr::TrackHandler::full_track_name_

protectedinherited

Full track identity retained for the handler's lifetime.

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

include/quicr/handlers/subscribe_namespace_handler.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ Mode

◆ Status

Constructor & Destructor Documentation

◆ SubscribeNamespaceHandler()

◆ ~SubscribeNamespaceHandler()

Member Function Documentation

◆ Create()

◆ ExpandSuffix()

◆ Get()

◆ GetBinding()

◆ GetConnection()

◆ GetConnectionId()

◆ GetError()

◆ GetFilter()

◆ GetFilterType()

◆ GetFullTrackName()

◆ GetMode()

◆ GetPrefix()

◆ GetRequestId()

◆ GetRequestStreamId()

◆ GetSession()

◆ GetStatus()

◆ NamespaceDoneReceived()

◆ NamespaceReceived()

◆ RequestError()

◆ RequestOkReceived()

◆ RequestUpdateReceived()

◆ SetError()

◆ SetRequestId()

◆ SetStatus()

◆ SetTransport()

◆ StatusChanged()

Member Data Documentation

◆ binding_operation_mutex_

◆ full_track_name_