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 }
	Publish status codes. More...

enum class	Status : uint8_t { kOk = 0 , kNotConnected , kNotAnnounced , kPendingAnnounceResponse , kAnnounceNotAuthorized , kNoSubscribers , kSendingUnannounce , kSubscriptionUpdated , kNewGroupRequested }
	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

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 Status	GetStatus () const noexcept
	Get the publish status.

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)
	Publish track handler constructor.

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.

◆ Status

enum class quicr::PublishTrackHandler::Status : uint8_t

strong

Status codes for the publish track.

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

Constructor & Destructor Documentation

◆ PublishTrackHandler()

quicr::PublishTrackHandler::PublishTrackHandler	(	const FullTrackName &	full_track_name,
		TrackMode	track_mode,
		uint8_t	default_priority,
		uint32_t	default_ttl )

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

Member Function Documentation

◆ Create()

static 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

◆ GetStatus()

Status quicr::PublishTrackHandler::GetStatus ( ) const

inlineconstexprnoexcept

Get the publish status.

Returns: Status of publish

◆ 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()

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

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

◆ 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

◆ 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

◆ 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.

Member Data Documentation

◆ 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.

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

Detailed Description

Member Enumeration Documentation

◆ PublishObjectStatus

◆ Status

Constructor & Destructor Documentation

◆ PublishTrackHandler()

Member Function Documentation

◆ Create()

◆ ForwardPublishedData()

◆ GetStatus()

◆ MetricsSampled()

◆ PublishObject()

◆ PublishPartialObject()

◆ SetDefaultPriority()

◆ SetDefaultTrackMode()

◆ SetDefaultTTL()

◆ StatusChanged()

Member Data Documentation

◆ publish_track_metrics_