#include <privmx/endpoint/stream/StreamApiLow.hpp>

Inheritance diagram for privmx::endpoint::stream::StreamApiLow:

Collaboration diagram for privmx::endpoint::stream::StreamApiLow:

Public Member Functions
	StreamApiLow ()
	StreamApiLow (const StreamApiLow &obj)
StreamApiLow &	operator= (const StreamApiLow &obj)
	StreamApiLow (StreamApiLow &&obj)
std::vector< TurnCredentials >	getTurnCredentials ()
std::string	createStreamRoom (const std::string &contextId, const std::vector< core::UserWithPubKey > &users, const std::vector< core::UserWithPubKey > &managers, const core::Buffer &publicMeta, const core::Buffer &privateMeta, const std::optional< core::ContainerPolicyWithoutItem > &policies, const std::optional< int64_t > &emptyRoomTtl=std::nullopt)
void	updateStreamRoom (const std::string &streamRoomId, const std::vector< core::UserWithPubKey > &users, const std::vector< core::UserWithPubKey > &managers, const core::Buffer &publicMeta, const core::Buffer &privateMeta, const int64_t version, const bool force, const bool forceGenerateNewKey, const std::optional< core::ContainerPolicyWithoutItem > &policies)
core::PagingList< StreamRoom >	listStreamRooms (const std::string &contextId, const core::PagingQuery &query)
StreamRoom	getStreamRoom (const std::string &streamRoomId)
void	deleteStreamRoom (const std::string &streamRoomId)
std::vector< StreamInfo >	listStreams (const std::string &streamRoomId)
std::vector< StreamSubscriber >	listStreamRoomParticipants (const std::string &streamRoomId)
std::vector< std::string >	subscribeFor (const std::vector< std::string > &subscriptionQueries)
void	unsubscribeFrom (const std::vector< std::string > &subscriptionIds)
std::string	buildSubscriptionQuery (EventType eventType, EventSelectorType selectorType, const std::string &selectorId)
void	trickle (const int64_t sessionId, const std::string &candidateAsJson)
void	setNewOfferOnReconfigure (const int64_t sessionId, const SdpWithTypeModel &sdp)
void	joinStreamRoom (const std::string &streamRoomId, std::shared_ptr< WebRTCInterface > webRtc)
void	leaveStreamRoom (const std::string &streamRoomId)
StreamHandle	createStream (const std::string &streamRoomId)
StreamPublishResult	publishStream (const StreamHandle &streamHandle)
StreamPublishResult	updateStream (const StreamHandle &streamHandle)
void	removeStream (const StreamHandle &streamHandle)
SubscriberStreamHandle	createSubscriberStream (const std::string &streamRoomId, const std::vector< StreamSubscription > &subscriptions)
void	updateSubscriberStream (const SubscriberStreamHandle &subscriptionHandle, const std::vector< StreamSubscription > &subscriptionsToAdd, const std::vector< StreamSubscription > &subscriptionsToRemove)
void	removeSubscriberStream (const SubscriberStreamHandle &subscriptionHandle)
core::Buffer	encryptDataChannelMessage (const std::string &streamRoomId, const DataChannelMessage &plainMessage)
DecryptedDataChannelMessage	decryptDataChannelMessage (const std::string &streamRoomId, const std::string &remoteStreamId, const core::Buffer &encryptedData)
Public Member Functions inherited from privmx::endpoint::core::ExtendedPointer< StreamApiLowImpl >
ExtendedPointer &	operator= (const ExtendedPointer &obj)
std::shared_ptr< StreamApiLowImpl >	getImpl () const

Static Public Member Functions
static StreamApiLow	create (const core::Connection &connection)

Additional Inherited Members
Protected Member Functions inherited from privmx::endpoint::core::ExtendedPointer< StreamApiLowImpl >
void	attachToPtrIfPossible ()
void	detachFromPtrIfPossible ()
Protected Attributes inherited from privmx::endpoint::core::ExtendedPointer< StreamApiLowImpl >
std::weak_ptr< StreamApiLowImpl >	_ptr

Detailed Description

Represents Endpoint's API for Stream Rooms and Streams.

It does not provide a WebRTC stack on its own - an implementation of 'WebRTCInterface' has to be passed when joining a Stream Room. This API and that implementation drive each other: this API tells the WebRTC layer to create and apply the session descriptions.

Streaming in a Stream Room follows a fixed order: joinStreamRoom, then createStream and publishStream to send media and/or createSubscriberStream to receive it, and finally leaveStreamRoom. Managing the Stream Rooms themselves (creating, updating, listing, deleting) does not require joining them.

Constructor & Destructor Documentation

◆ StreamApiLow()

privmx::endpoint::stream::StreamApiLow::StreamApiLow ( )

//doc-gen:ignore

Member Function Documentation

◆ buildSubscriptionQuery()

std::string privmx::endpoint::stream::StreamApiLow::buildSubscriptionQuery	(	EventType	eventType,
		EventSelectorType	selectorType,
		const std::string &	selectorId )

Generate subscription Query for the Stream Room events.

The selector narrows the query down to a single scope, so 'selectorId' has to be an ID of the kind named by 'selectorType' - a Context ID, a Stream Room ID or a Stream ID.

Parameters

eventType	type of event which you listen for
selectorType	scope on which you listen for events
selectorId	ID of the selector

Returns: subscription query string

◆ create()

StreamApiLow privmx::endpoint::stream::StreamApiLow::create ( const core::Connection & connection )

static

Creates an instance of 'StreamApiLow'.

Parameters

connection instance of 'Connection'

Returns: StreamApiLow object

◆ createStream()

StreamHandle privmx::endpoint::stream::StreamApiLow::createStream ( const std::string & streamRoomId )

Creates a publisher Stream in given Stream Room.

The Stream is only created locally - nothing is sent to the server and the Stream becomes visible to other participants after calling publishStream. A Stream Room can hold one publisher Stream at a time - creating a second one throws 'StreamAlreadyPublishedException' until the current one is removed by removeStream.

Parameters

streamRoomId ID of the Stream Room to create the Stream in

Returns: handle to the created Stream

◆ createStreamRoom()

std::string privmx::endpoint::stream::StreamApiLow::createStreamRoom	(	const std::string &	contextId,
		const std::vector< core::UserWithPubKey > &	users,
		const std::vector< core::UserWithPubKey > &	managers,
		const core::Buffer &	publicMeta,
		const core::Buffer &	privateMeta,
		const std::optional< core::ContainerPolicyWithoutItem > &	policies,
		const std::optional< int64_t > &	emptyRoomTtl = std::nullopt )

Creates a new Stream Room in given Context.

Parameters

contextId	ID of the Context to create the Stream Room in
users	vector of UserWithPubKey structs which indicates who will have access to the created Stream Room
managers	vector of UserWithPubKey structs which indicates who will have access (and management rights) to the created Stream Room
publicMeta	public (unencrypted) metadata
privateMeta	private (encrypted) metadata
policies	Stream Room's policies (pass std::nullopt to use defaults)
emptyRoomTtl	grace period (ms) the Stream Room stays open after the last participant leaves; 0 closes it immediately; std::nullopt use the server default (closes it immediately)

Returns: ID of the created Stream Room

◆ createSubscriberStream()

SubscriberStreamHandle privmx::endpoint::stream::StreamApiLow::createSubscriberStream	(	const std::string &	streamRoomId,
		const std::vector< StreamSubscription > &	subscriptions )

Creates a Subscriber Stream receiving the selected streams or tracks published in given Stream Room.

A Stream Room can hold one subscriber Stream at a time - another one can be created only after the current one is removed by removeSubscriberStream. The 'subscriptions' list has to contain at least one feed to create a subscriber Stream successfully. If the media server answers with an offer, the negotiation is completed internally using the Stream Room's WebRTC layer, so the caller does not have to handle it. A 'StreamSubscription' without 'streamTrackId' subscribes to all the tracks available in that Stream.

Parameters

streamRoomId	ID of the Stream Room to create the Stream in
subscriptions	list of Streams and tracks to subscribe to

Returns: handle to the created Stream

◆ decryptDataChannelMessage()

DecryptedDataChannelMessage privmx::endpoint::stream::StreamApiLow::decryptDataChannelMessage	(	const std::string &	streamRoomId,
		const std::string &	remoteStreamId,
		const core::Buffer &	encryptedData )

Decrypts a message received over the Stream Room's data channel.

A message which cannot be decrypted is reported by the 'statusCode' of the returned struct rather than by an exception, so that a single broken message does not break the whole data channel. A message with an invalid sequence number throws 'InvalidDataChannelSeqException', so the same message cannot be decrypted twice.

Parameters

streamRoomId	ID of the Stream Room the message was received in
remoteStreamId	ID of the remote Stream which sent the message
encryptedData	received encrypted message

Returns: decrypted message

◆ deleteStreamRoom()

void privmx::endpoint::stream::StreamApiLow::deleteStreamRoom ( const std::string & streamRoomId )

Deletes a Stream Room by given Stream Room ID.

Parameters

streamRoomId ID of the Stream Room to delete

◆ encryptDataChannelMessage()

core::Buffer privmx::endpoint::stream::StreamApiLow::encryptDataChannelMessage	(	const std::string &	streamRoomId,
		const DataChannelMessage &	plainMessage )

Encrypts a message to be sent over the Stream Room's data channel.

The Stream Room has to be joined, as the message is encrypted with its current key. The message's 'seq' is assigned by the caller and has to grow strictly with every message sent over the same Stream - the receiving side rejects a message whose 'seq' is not greater than the last accepted one.

Parameters

streamRoomId	ID of the Stream Room to send the message in
plainMessage	message to encrypt

Returns: encrypted message

◆ getStreamRoom()

StreamRoom privmx::endpoint::stream::StreamApiLow::getStreamRoom ( const std::string & streamRoomId )

Gets a single Stream Room by given Stream Room ID.

Parameters

streamRoomId ID of the Stream Room to get

Returns: struct containing information about the Stream Room

◆ getTurnCredentials()

std::vector< TurnCredentials > privmx::endpoint::stream::StreamApiLow::getTurnCredentials ( )

Gets credentials of the TURN servers.

A TURN server relays the Streams when the network configuration blocks direct traffic, e.g. because of a firewall or a double NAT. The credentials expire, so they should be fetched again when a new connection is being configured rather than stored for the lifetime of the application.

Returns: list of TURN servers credentials

◆ joinStreamRoom()

void privmx::endpoint::stream::StreamApiLow::joinStreamRoom	(	const std::string &	streamRoomId,
		std::shared_ptr< WebRTCInterface >	webRtc )

Joins a Stream Room using the given WebRTC layer implementation.

This is required to work with the Streams, the Stream events and the data channels inside a Stream Room. Joining passes the Stream Room's current encryption keys to the given WebRTC layer and keeps them up to date for as long as the Stream Room is joined, so the same instance has to stay alive until leaveStreamRoom. A Stream Room can be joined only once at a time.

Parameters

streamRoomId	ID of the Stream Room to join
webRtc	implementation of 'WebRTCInterface' handling the Stream Room's connections

◆ leaveStreamRoom()

void privmx::endpoint::stream::StreamApiLow::leaveStreamRoom ( const std::string & streamRoomId )

Leaves a Stream Room and closes all opened Publisher/Subscriber Streams.

The handles of the Stream Room's publisher and subscriber Streams are invalidated by this call and the Stream Room has to be joined again to publish or receive anything in it. It also closes all the connections between PrivMX Bridge and the Stream Room in the Janus Gateway, so the user disappears from the list of participants.

Parameters

streamRoomId ID of the Stream Room to leave

◆ listStreamRoomParticipants()

std::vector< StreamSubscriber > privmx::endpoint::stream::StreamApiLow::listStreamRoomParticipants ( const std::string & streamRoomId )

Gets a list of participants of given Stream Room.

Each participant is described by their current subscriptions and by the Stream they publish, if any. A user becomes a participant from the moment they call joinStreamRoom until they call leaveStreamRoom, and may have no subscriptions and no published Stream in the meantime.

Parameters

streamRoomId ID of the Stream Room

Returns: list of StreamSubscriber structs describing current participants

◆ listStreamRooms()

core::PagingList< StreamRoom > privmx::endpoint::stream::StreamApiLow::listStreamRooms	(	const std::string &	contextId,
		const core::PagingQuery &	query )

Gets a list of Stream Rooms in given Context.

Parameters

contextId	ID of the Context to get the Stream Rooms from
query	struct with list query parameters

Returns: struct containing a list of Stream Rooms

◆ listStreams()

std::vector< StreamInfo > privmx::endpoint::stream::StreamApiLow::listStreams ( const std::string & streamRoomId )

Gets a list of currently published Streams in given Stream Room.

The returned Streams and their feeds are what can be passed to createSubscriberStream.

Parameters

streamRoomId ID of the Stream Room to list the Streams from

Returns: list of StreamInfo structs describing currently published Streams

◆ publishStream()

StreamPublishResult privmx::endpoint::stream::StreamApiLow::publishStream ( const StreamHandle & streamHandle )

Publishes the Stream with the feeds currently added to it by the WebRTC layer.

The feeds have to be added to the WebRTC layer's Publisher Connection before this call, because the offer sent to the server is created from that PeerConnection's current state. A publisher Stream has to have at least one feed added to be published successfully.

Parameters

streamHandle handle returned by createStream

Returns: result of the publish operation

◆ removeStream()

void privmx::endpoint::stream::StreamApiLow::removeStream ( const StreamHandle & streamHandle )

Stops publishing and closes the Publisher Stream.

The handle is closed after this call and cannot be used anymore, but a new Publisher Stream can be created in the same Stream Room with createStream.

Parameters

streamHandle handle returned by createStream

◆ removeSubscriberStream()

void privmx::endpoint::stream::StreamApiLow::removeSubscriberStream ( const SubscriberStreamHandle & subscriptionHandle )

Unsubscribes from all the Streams received by the given Subscriber Stream and closes it.

The handle is closed after this call and cannot be used anymore, but a new subscriber Stream can be created in the same Stream Room with createSubscriberStream.

Parameters

subscriptionHandle handle returned by createSubscriberStream

◆ setNewOfferOnReconfigure()

void privmx::endpoint::stream::StreamApiLow::setNewOfferOnReconfigure	(	const int64_t	sessionId,
		const SdpWithTypeModel &	sdp )

Sends a new offer to the media server to reconfigure an existing Stream.

This method can be used to start the renegotiation process when the WebRTC layer signals that renegotiation is needed on the PeerConnection observer.

Parameters

sessionId	ID of the media server session to reconfigure
sdp	offer created by the WebRTC layer

◆ subscribeFor()

std::vector< std::string > privmx::endpoint::stream::StreamApiLow::subscribeFor ( const std::vector< std::string > & subscriptionQueries )

Subscribe for the Stream Room events on the given subscription query.

The queries are built by buildSubscriptionQuery. The returned IDs are the only way to stop receiving those events, so they have to be kept for the matching unsubscribeFrom call.

Parameters

subscriptionQueries list of queries

Returns: list of subscriptionIds in matching order to subscriptionQueries

◆ trickle()

void privmx::endpoint::stream::StreamApiLow::trickle	(	const int64_t	sessionId,
		const std::string &	candidateAsJson )

Sends a locally gathered ICE candidate to the media server.

This is meant to be called by the WebRTC layer for every candidate it gathers, with the session ID which this API has assigned to that Stream by calling 'WebRTCInterface::updateSessionId'.

Parameters

sessionId	ID of the media server session the candidate belongs to
candidateAsJson	ICE candidate in serialized JSON

◆ unsubscribeFrom()

void privmx::endpoint::stream::StreamApiLow::unsubscribeFrom ( const std::vector< std::string > & subscriptionIds )

Unsubscribe from events for the given subscriptionId.

Parameters

subscriptionIds list of subscriptionId

◆ updateStream()

StreamPublishResult privmx::endpoint::stream::StreamApiLow::updateStream ( const StreamHandle & streamHandle )

Updates an already published Stream after its feeds have changed (added or removed).

As in publishStream, the changes have to be applied to the WebRTC layer's publisher connection first. The Stream has to be published before.

Parameters

streamHandle handle returned by createStream

Returns: result of the update operation

◆ updateStreamRoom()

void privmx::endpoint::stream::StreamApiLow::updateStreamRoom	(	const std::string &	streamRoomId,
		const std::vector< core::UserWithPubKey > &	users,
		const std::vector< core::UserWithPubKey > &	managers,
		const core::Buffer &	publicMeta,
		const core::Buffer &	privateMeta,
		const int64_t	version,
		const bool	force,
		const bool	forceGenerateNewKey,
		const std::optional< core::ContainerPolicyWithoutItem > &	policies )

Updates an existing Stream Room.

Parameters

streamRoomId	ID of the Stream Room to update
users	vector of UserWithPubKey structs which indicates who will have access to the Stream Room
managers	vector of UserWithPubKey structs which indicates who will have access (and management rights) to the Stream Room
publicMeta	public (unencrypted) metadata
privateMeta	private (encrypted) metadata
version	current version of the updated Stream Room
force	force update (without checking version)
forceGenerateNewKey	force to regenerate a key for the Stream Room
policies	Stream Room's policies (pass std::nullopt to keep current/defaults)

◆ updateSubscriberStream()

void privmx::endpoint::stream::StreamApiLow::updateSubscriberStream	(	const SubscriberStreamHandle &	subscriptionHandle,
		const std::vector< StreamSubscription > &	subscriptionsToAdd,
		const std::vector< StreamSubscription > &	subscriptionsToRemove )

Modifies the subscriptions of an existing Subscriber Stream.

The resulting set of subscriptions is the current one without 'subscriptionsToRemove' plus 'subscriptionsToAdd'. As in createSubscriberStream, the negotiation which may follow is completed internally.

Parameters

subscriptionHandle	handle returned by createSubscriberStream
subscriptionsToAdd	list of subscriptions to add
subscriptionsToRemove	list of subscriptions to remove

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

privmx/endpoint/stream/StreamApiLow.hpp

PrivMX DOCS PrivMX Endpoint v2.8.0

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ StreamApiLow()

Member Function Documentation

◆ buildSubscriptionQuery()

◆ create()

◆ createStream()

◆ createStreamRoom()

◆ createSubscriberStream()

◆ decryptDataChannelMessage()

◆ deleteStreamRoom()

◆ encryptDataChannelMessage()

◆ getStreamRoom()

◆ getTurnCredentials()

◆ joinStreamRoom()

◆ leaveStreamRoom()

◆ listStreamRoomParticipants()

◆ listStreamRooms()

◆ listStreams()

◆ publishStream()

◆ removeStream()

◆ removeSubscriberStream()

◆ setNewOfferOnReconfigure()

◆ subscribeFor()

◆ trickle()

◆ unsubscribeFrom()

◆ updateStream()

◆ updateStreamRoom()

◆ updateSubscriberStream()