MOQ track handler for published track. More...

#include <publish_track_handler.h>

Inheritance diagram for quicr::PublishTrackHandler:

Public Types
enum class	PublishObjectStatus : uint8_t { kOk = 0 , kInternalError , kNotAuthorized , kNotAnnounced , kNoSubscribers , kObjectPayloadLengthExceeded , kPreviousObjectTruncated , kNoPreviousObject , kObjectDataComplete , kObjectContinuationDataNeeded , kObjectDataIncomplete , kObjectDataTooLarge , kPreviousObjectNotCompleteMustStartNewGroup , kPreviousObjectNotCompleteMustStartNewTrack , kPaused }
	Publish status codes. More...
enum class	Status : uint8_t { kOk = 0 , kNotConnected , kNotAnnounced , kPendingAnnounceResponse , kAnnounceNotAuthorized , kNoSubscribers , kSendingUnannounce , kSubscriptionUpdated , kNewGroupRequested , kPendingPublishOk , kPaused }
	Status codes for the publish track. More...

Public Member Functions
void	SetDefaultPriority (const uint8_t priority) noexcept
	set/update the default priority for published objects
constexpr uint8_t	GetDefaultPriority () const noexcept
	Get the default priority for published objects.
void	SetDefaultTTL (const uint32_t ttl) noexcept
	set/update the default TTL expiry for published objects
void	SetDefaultTrackMode (const TrackMode track_mode) noexcept
	set/update the default track mode for objects
constexpr messages::StreamHeaderType	GetStreamMode () const noexcept
	Get the current stream mode.
constexpr Status	GetStatus () const noexcept
	Get the publish status.
constexpr bool	UsingAnnounce () const noexcept
	Get use announce setting.
constexpr void	SetUseAnnounce (bool use) noexcept
	Set use announce.
constexpr bool	CanPublish () const noexcept
	Check if the state allows publishing or not.
void	SetTrackAlias (uint64_t track_alias)
	Set the track alias.
std::optional< uint64_t >	GetTrackAlias () const noexcept
	Get the track alias.
virtual PublishObjectStatus	PublishObject (const ObjectHeaders &object_headers, BytesSpan data)
	Publish [full] object.
PublishObjectStatus	ForwardPublishedData (bool is_new_stream, std::shared_ptr< const std::vector< uint8_t > > data)
	Forward received object data to subscriber/relay/remote client.
PublishObjectStatus	PublishPartialObject (const ObjectHeaders &object_headers, BytesSpan data)
	Publish object to the announced track.
Callbacks
virtual void	StatusChanged (Status status)
	Notification of publish track status change.
virtual void	MetricsSampled (const PublishTrackMetrics &metrics)
	Notification callback to provide sampled metrics.

Static Public Member Functions
static std::shared_ptr< PublishTrackHandler >	Create (const FullTrackName &full_track_name, TrackMode track_mode, uint8_t default_priority, uint32_t default_ttl)
	Create a shared Publish track handler.

Public Attributes
PublishTrackMetrics	publish_track_metrics_
	Publish metrics for the track.

Protected Member Functions
	PublishTrackHandler (const FullTrackName &full_track_name, TrackMode track_mode, uint8_t default_priority, uint32_t default_ttl, std::optional< messages::StreamHeaderType > stream_mode=std::nullopt)
	Publish track handler constructor.
void	SetDataContextId (uint64_t data_ctx_id) noexcept
	Set the Data context ID.
constexpr uint64_t	GetDataContextId () const noexcept
	Get the Data context ID.
void	SetStatus (Status status) noexcept
	Set the publish status.

Protected Attributes
Status	publish_status_ { Status::kNotAnnounced }
TrackMode	default_track_mode_
messages::StreamHeaderType	stream_mode_
uint8_t	default_priority_
uint32_t	default_ttl_
uint64_t	publish_data_ctx_id_
uint64_t	latest_group_id_ { 0 }
uint64_t	latest_sub_group_id_ { 0 }
uint64_t	latest_object_id_ { 0 }
uint64_t	object_payload_remaining_length_ { 0 }
std::optional< uint64_t >	track_alias_
bool	seen_first_object_ { false }
Bytes	object_msg_buffer_
bool	use_announce { false }

Detailed Description

MOQ track handler for published track.

MOQ publish track handler defines all track related callbacks and functions for publish. Track handler operates on a single track (namespace + name).

This extends the base track handler to add publish (aka send) handling

Examples: client.cpp, and server.cpp.

Member Enumeration Documentation

◆ PublishObjectStatus

enum class quicr::PublishTrackHandler::PublishObjectStatus : uint8_t

strong

Publish status codes.

Enumerator
kOk
kInternalError
kNotAuthorized
kNotAnnounced
kNoSubscribers
kObjectPayloadLengthExceeded
kPreviousObjectTruncated
kNoPreviousObject
kObjectDataComplete
kObjectContinuationDataNeeded
kObjectDataIncomplete	PublishObject() was called when continuation data remains.
kObjectDataTooLarge	Indicates that the published object data is too large based on the object header payload size plus any/all data that was sent already.
kPreviousObjectNotCompleteMustStartNewGroup	Previous object payload has not been completed and new object cannot start in per-group track mode unless new group is used.
kPreviousObjectNotCompleteMustStartNewTrack	Previous object payload has not been completed and new object cannot start in per-track track mode without creating a new track. This requires to unpublish and to publish track again.
kPaused

◆ Status

enum class quicr::PublishTrackHandler::Status : uint8_t

strong

Status codes for the publish track.

Note: kOk is not the only status that means it is okay to publish. CanPublish() method should be used to determine if the status is okay to still publish or not.

Enumerator
kOk
kNotConnected
kNotAnnounced
kPendingAnnounceResponse
kAnnounceNotAuthorized
kNoSubscribers
kSendingUnannounce	In this state, callbacks will not be called.
kSubscriptionUpdated
kNewGroupRequested
kPendingPublishOk
kPaused

Constructor & Destructor Documentation

◆ PublishTrackHandler()

quicr::PublishTrackHandler::PublishTrackHandler	(	const FullTrackName &	full_track_name,
		TrackMode	track_mode,
		uint8_t	default_priority,
		uint32_t	default_ttl,
		std::optional< messages::StreamHeaderType >	stream_mode = std::nullopt )

inlineprotected

Publish track handler constructor.

Parameters

full_track_name	Full track name
track_mode	The track mode to operate using
default_priority	Default priority for objects if not specified in ObjectHeaderss
default_ttl	Default TTL for objects if not specified in ObjectHeaderss
stream_mode	Stream to use when track mode is kStream.

Member Function Documentation

◆ CanPublish()

bool quicr::PublishTrackHandler::CanPublish ( ) const

inlineconstexprnoexcept

Check if the state allows publishing or not.

Returns: true to indicate that the publisher can publish, false if the publisher cannot

◆ Create()

std::shared_ptr< PublishTrackHandler > quicr::PublishTrackHandler::Create	(	const FullTrackName &	full_track_name,
		TrackMode	track_mode,
		uint8_t	default_priority,
		uint32_t	default_ttl )

inlinestatic

Create a shared Publish track handler.

Parameters

full_track_name	Full track name
track_mode	The track mode to operate using
default_priority	Default priority for objects if not specified in ObjectHeaderss
default_ttl	Default TTL for objects if not specified in ObjectHeaderss

◆ ForwardPublishedData()

PublishObjectStatus quicr::PublishTrackHandler::ForwardPublishedData	(	bool	is_new_stream,
		std::shared_ptr< const std::vector< uint8_t > >	data )

Forward received object data to subscriber/relay/remote client.

This method is similar to PublishObject except that the data forwarded is byte array level data, which should have already been encoded upon receive from the origin publisher. Relays implement this method to forward bytes received to subscriber connection.

Parameters

is_new_stream	Indicates if this data starts a new stream
data	MoQ data to send

Returns: Publish status on forwarding the data

◆ GetDataContextId()

uint64_t quicr::PublishTrackHandler::GetDataContextId ( ) const

inlineconstexprprotectednoexcept

Get the Data context ID.

◆ GetDefaultPriority()

uint8_t quicr::PublishTrackHandler::GetDefaultPriority ( ) const

inlineconstexprnoexcept

Get the default priority for published objects.

Returns: The default priority.

◆ GetStatus()

Status quicr::PublishTrackHandler::GetStatus ( ) const

inlineconstexprnoexcept

Get the publish status.

Returns: Status of publish

◆ GetStreamMode()

messages::StreamHeaderType quicr::PublishTrackHandler::GetStreamMode ( ) const

inlineconstexprnoexcept

Get the current stream mode.

Returns: The current stream mode.

◆ GetTrackAlias()

std::optional< uint64_t > quicr::PublishTrackHandler::GetTrackAlias ( ) const

inlinenoexcept

Get the track alias.

If the track alias is set, it will be returned, otherwise std::nullopt.

Returns: Track alias if set, otherwise std::nullopt.

Examples: client.cpp, and server.cpp.

◆ MetricsSampled()

virtual void quicr::PublishTrackHandler::MetricsSampled ( const PublishTrackMetrics & metrics )

virtual

Notification callback to provide sampled metrics.

Callback will be triggered on Config::metrics_sample_ms to provide the sampled data based on the sample period. After this callback, the period/sample based metrics will reset and start over for the new period.

Parameters

metrics Copy of the published metrics for the sample period

Examples: server.cpp.

◆ PublishObject()

virtual PublishObjectStatus quicr::PublishTrackHandler::PublishObject	(	const ObjectHeaders &	object_headers,
		BytesSpan	data )

virtual

Publish [full] object.

Publish a full object. If not announced, it will be announced. Status will indicate if there are no subscribers. In this case, the object will not be sent.

Note: If data is less than ObjectHeaders::payload_length, the error kObjectDataIncomplete will be returned and the object will not be sent.

Restrictions:

This method cannot be called twice with the same object header group and object IDs.
In TrackMode::kStreamPerGroup, ObjectHeaders::group_id MUST be different than the previous when calling this method when the previous has not been completed yet using PublishContinuationData(). If group id is not different, the PublishStatus::kPreviousObjectNotCompleteMustStartNewGroup will be returned and the object will not be sent. If new group ID is provided, then the previous object will terminate with stream closure, resulting in the previous being truncated.
In TrackMode::kStreamPerTrack, this method CANNOT be called until the previous object has been completed using PublishContinuationData(). Calling this method before completing the previous object remaining data will result in PublishStatus::kObjectDataIncomplete. No data would be sent and the stream would remain unchanged. It is expected that the caller would send the remaining continuation data.

Parameters

object_headers	Object headers, must include group and object Ids
data	Full complete payload data for the object

Returns: Publish status of the publish

Reimplemented in quicr::PublishFetchHandler.

◆ PublishPartialObject()

PublishObjectStatus quicr::PublishTrackHandler::PublishPartialObject	(	const ObjectHeaders &	object_headers,
		BytesSpan	data )

Publish object to the announced track.

Publish a partial object. If not announced, it will be announced. Status will indicate if there are no subscribers. In this case, the object will not be sent.

Restrictions:

In TrackMode::kStreamPerGroup, /::group_id MUST be different than the previous when calling this method when the previous has not been completed yet using PublishContinuationData(). If group id is not different, the PublishStatus::kPreviousObjectNotCompleteMustStartNewGroup will be returned and the object will not be sent. If new group ID is provided, then the previous object will terminate with stream closure, resulting in the previous being truncated.
In TrackMode::kStreamPerTrack, this method CANNOT be called until the previous object has been completed using PublishContinuationData(). Calling this method before completing the previous object remaining data will result in PublishStatus::kObjectDataIncomplete. No data would be sent and the stream would remain unchanged. It is expected that the caller would send the remaining continuation data.

Note: If data is less than ObjectHeaders::payload_length, then PublishObject() should be called to send the remaining data.

Parameters

object_headers	Object headers, must include group and object Ids
data	Payload data for the object, must be <= object_headers.payload_length

Returns

Publish status of the publish

PublishStatus::kObjectContinuationDataNeeded if the object payload data is not completed but it was sent,
PublishStatus::kObjectDataComplete if the object data was sent and the data is complete,
other PublishStatus

◆ SetDataContextId()

void quicr::PublishTrackHandler::SetDataContextId ( uint64_t data_ctx_id )

inlineprotectednoexcept

Set the Data context ID.

The MOQ Handler sets the data context ID

◆ SetDefaultPriority()

void quicr::PublishTrackHandler::SetDefaultPriority ( const uint8_t priority )

inlinenoexcept

set/update the default priority for published objects

◆ SetDefaultTrackMode()

void quicr::PublishTrackHandler::SetDefaultTrackMode ( const TrackMode track_mode )

inlinenoexcept

set/update the default track mode for objects

◆ SetDefaultTTL()

void quicr::PublishTrackHandler::SetDefaultTTL ( const uint32_t ttl )

inlinenoexcept

set/update the default TTL expiry for published objects

◆ SetStatus()

void quicr::PublishTrackHandler::SetStatus ( Status status )

inlineprotectednoexcept

Set the publish status.

Parameters

status Status of publishing (aka publish objects)

◆ SetTrackAlias()

void quicr::PublishTrackHandler::SetTrackAlias ( uint64_t track_alias )

inline

Set the track alias.

Parameters

track_alias MoQ track alias for track namespace+name

◆ SetUseAnnounce()

void quicr::PublishTrackHandler::SetUseAnnounce ( bool use )

inlineconstexprnoexcept

Set use announce.

Parameters

use	True to request announce flow to be used. False to use publish flow.

◆ StatusChanged()

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

virtual

Notification of publish track status change.

Notification of a change to publish track status, such as when it's ready to publish or not ready to publish

Parameters

status Indicates the status of being able to publish

Examples: client.cpp, and server.cpp.

◆ UsingAnnounce()

bool quicr::PublishTrackHandler::UsingAnnounce ( ) const

inlineconstexprnoexcept

Get use announce setting.

Returns: true to indicate announce flow will be used. false to indicate publish flow will be used

Member Data Documentation

◆ default_priority_

uint8_t quicr::PublishTrackHandler::default_priority_

protected

◆ default_track_mode_

TrackMode quicr::PublishTrackHandler::default_track_mode_

protected

◆ default_ttl_

uint32_t quicr::PublishTrackHandler::default_ttl_

protected

◆ latest_group_id_

uint64_t quicr::PublishTrackHandler::latest_group_id_ { 0 }

protected

◆ latest_object_id_

uint64_t quicr::PublishTrackHandler::latest_object_id_ { 0 }

protected

◆ latest_sub_group_id_

uint64_t quicr::PublishTrackHandler::latest_sub_group_id_ { 0 }

protected

◆ object_msg_buffer_

Bytes quicr::PublishTrackHandler::object_msg_buffer_

protected

◆ object_payload_remaining_length_

uint64_t quicr::PublishTrackHandler::object_payload_remaining_length_ { 0 }

protected

◆ publish_data_ctx_id_

uint64_t quicr::PublishTrackHandler::publish_data_ctx_id_

protected

◆ publish_status_

Status quicr::PublishTrackHandler::publish_status_ { Status::kNotAnnounced }

protected

◆ publish_track_metrics_

PublishTrackMetrics quicr::PublishTrackHandler::publish_track_metrics_

Publish metrics for the track.

Publish metrics are updated real-time and transport quic metrics on metrics_sample_ms period.

◆ seen_first_object_

bool quicr::PublishTrackHandler::seen_first_object_ { false }

protected

◆ stream_mode_

messages::StreamHeaderType quicr::PublishTrackHandler::stream_mode_

protected

◆ track_alias_

std::optional<uint64_t> quicr::PublishTrackHandler::track_alias_

protected

◆ use_announce

bool quicr::PublishTrackHandler::use_announce { false }

protected

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

include/quicr/publish_track_handler.h

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ PublishObjectStatus

◆ Status

Constructor & Destructor Documentation

◆ PublishTrackHandler()

Member Function Documentation

◆ CanPublish()

◆ Create()

◆ ForwardPublishedData()

◆ GetDataContextId()

◆ GetDefaultPriority()

◆ GetStatus()

◆ GetStreamMode()

◆ GetTrackAlias()

◆ MetricsSampled()

◆ PublishObject()

◆ PublishPartialObject()

◆ SetDataContextId()

◆ SetDefaultPriority()

◆ SetDefaultTrackMode()

◆ SetDefaultTTL()

◆ SetStatus()

◆ SetTrackAlias()

◆ SetUseAnnounce()

◆ StatusChanged()

◆ UsingAnnounce()

Member Data Documentation

◆ default_priority_

◆ default_track_mode_

◆ default_ttl_

◆ latest_group_id_

◆ latest_object_id_

◆ latest_sub_group_id_

◆ object_msg_buffer_

◆ object_payload_remaining_length_

◆ publish_data_ctx_id_

◆ publish_status_

◆ publish_track_metrics_

◆ seen_first_object_

◆ stream_mode_

◆ track_alias_

◆ use_announce