privmx::endpoint::stream::StreamApi Class Reference

#include <stream/webrtc/include_pub/privmx/endpoint/stream/StreamApi.hpp>

Public Member Functions
	StreamApi ()=default
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< 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)
std::vector< StreamInfo >	listStreams (const std::string &streamRoomId)
std::vector< StreamSubscriber >	listStreamRoomParticipants (const std::string &streamRoomId)
void	joinStreamRoom (const std::string &streamRoomId)
void	leaveStreamRoom (const std::string &streamRoomId)
StreamHandle	createStream (const std::string &streamRoomId)
std::vector< AudioDevice >	getAudioDevices ()
std::vector< VideoDevice >	getVideoDevices ()
std::vector< DesktopDevice >	getDesktopDevices (DesktopType desktopType)
MediaTrack	addTrack (const StreamHandle &streamHandle, const MediaDevice &track, const MediaTrackConstrains &mediaTrackConstrains)
void	removeTrack (const StreamHandle &streamHandle, const MediaDevice &track)
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)
void	dropBrokenFrames (const std::string &streamRoomId, bool enable)
void	addRemoteStreamListener (const std::string &streamRoomId, std::optional< int64_t > streamId, std::shared_ptr< OnTrackInterface > onTrack)
void	sendData (const StreamHandle &streamHandle, core::Buffer data)
std::shared_ptr< StreamApiImpl >	getImpl () const

Static Public Member Functions
static StreamApi	create (core::Connection &connection, event::EventApi &eventApi)

Detailed Description

Represents Endpoint's API for Stream Rooms and Streams, with a built-in WebRTC layer.

StreamApi handles everything StreamApiLow leaves to you: it configures the TURN servers, negotiates the PeerConnections, captures the local media devices, and encrypts the media it sends. Use StreamApiLow instead when you bring your own WebRTC stack.

Streaming in a Stream Room follows a fixed order: joinStreamRoom, then createStream, addTrack, and publishStream to send media and createSubscriberStream to receive it, and finally leaveStreamRoom. Managing the Stream Rooms themselves, that is creating, updating, listing, and deleting them, works without joining them.

Constructor & Destructor Documentation

StreamApi()

privmx::endpoint::stream::StreamApi::StreamApi ( )

default

//doc-gen:ignore

Member Function Documentation

addRemoteStreamListener()

void privmx::endpoint::stream::StreamApi::addRemoteStreamListener	(	const std::string &	streamRoomId,
		std::optional< int64_t >	streamId,
		std::shared_ptr< OnTrackInterface >	onTrack )

Registers a listener for the remote tracks in the Stream Room.

The listener receives the tracks which the Subscriber Stream subscribes to.

Parameters

streamRoomId	ID of the Stream Room
streamId	ID of a single remote Stream to listen to, or std::nullopt to listen to all of them
onTrack	listener implementation

addTrack()

MediaTrack privmx::endpoint::stream::StreamApi::addTrack	(	const StreamHandle &	streamHandle,
		const MediaDevice &	track,
		const MediaTrackConstrains &	mediaTrackConstrains )

Adds a track to a Publisher Stream.

The track stays local until the next publishStream or updateStream call, which sends it to the other participants. A device unknown to the system throws IncorrectTrackIdException. A Stream carries at most one data track, that is one device of the Plain type. Adding a second one throws ThereCanBeOnlyOneDataTrackException.

Parameters

streamHandle	handle returned by createStream
track	media device to capture from
mediaTrackConstrains	capture constraints, which apply to the video and desktop devices only

Returns

MediaTrack struct which enables and disables the track

buildSubscriptionQuery()

std::string privmx::endpoint::stream::StreamApi::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()

StreamApi privmx::endpoint::stream::StreamApi::create ( core::Connection & connection, event::EventApi & eventApi )

static

Creates an instance of StreamApi.

This method reads the TURN credentials from PrivMX Bridge and initializes the WebRTC stack with them, so the given Connection has to be connected.

Parameters

connection	instance of Connection
eventApi	(deprecated) instance of EventApi, the value is ignored

Returns

StreamApi object

createStream()

StreamHandle privmx::endpoint::stream::StreamApi::createStream

(

const std::string &

streamRoomId

)

Creates a Publisher Stream in given Stream Room.

The Stream lives locally until you publish it: add its tracks with addTrack and then call publishStream to make the Stream visible to the other participants. A Stream Room holds one Publisher Stream at a time. Remove the current one with removeStream before you create another.

Parameters

streamRoomId

ID of the Stream Room to create the Stream in

Returns

handle to the created Stream

createStreamRoom()

std::string privmx::endpoint::stream::StreamApi::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 uses the server default (closes it immediately)

Returns

ID of the created Stream Room

createSubscriberStream()

SubscriberStreamHandle privmx::endpoint::stream::StreamApi::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 holds one Subscriber Stream at a time. Remove the current one with removeSubscriberStream before you create another. The 'subscriptions' list has to contain at least one feed to create a subscriber Stream successfully. A StreamSubscription without streamTrackId subscribes to all the tracks available in that Stream. Register a listener with addRemoteStreamListener to receive the media of the subscribed Streams.

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

deleteStreamRoom()

void privmx::endpoint::stream::StreamApi::deleteStreamRoom

(

const std::string &

streamRoomId

)

Deletes a Stream Room by given Stream Room ID.

Parameters

streamRoomId

ID of the Stream Room to delete

dropBrokenFrames()

void privmx::endpoint::stream::StreamApi::dropBrokenFrames	(	const std::string &	streamRoomId,
		bool	enable )

Configures what the Stream Room does with the frames it fails to decrypt.

By default such frames reach the receiving track as they are. Enable this option to drop them instead.

Parameters

streamRoomId	ID of the Stream Room
enable	true drops the frames which fail to decrypt

getAudioDevices()

std::vector< AudioDevice > privmx::endpoint::stream::StreamApi::getAudioDevices

(

)

Lists the local audio input devices.

Pass one of the returned devices to addTrack to capture from it.

Returns

list of audio devices

getDesktopDevices()

std::vector< DesktopDevice > privmx::endpoint::stream::StreamApi::getDesktopDevices

(

DesktopType

desktopType

)

Lists the local desktop capture sources.

Pass one of the returned devices to addTrack to capture from it.

Parameters

desktopType

type of the desktop source: Screen or Window

Returns

list of desktop devices

getImpl()

std::shared_ptr< StreamApiImpl > privmx::endpoint::stream::StreamApi::getImpl ( ) const

inline

//doc-gen:ignore

getStreamRoom()

StreamRoom privmx::endpoint::stream::StreamApi::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

getVideoDevices()

std::vector< VideoDevice > privmx::endpoint::stream::StreamApi::getVideoDevices

(

)

Lists the local video input devices, that is the cameras.

Pass one of the returned devices to addTrack to capture from it.

Returns

list of video devices

joinStreamRoom()

void privmx::endpoint::stream::StreamApi::joinStreamRoom

(

const std::string &

streamRoomId

)

Joins a Stream Room.

This is required to work with the Streams, the Stream events, and the data tracks inside a Stream Room. Joining hands the Stream Room's encryption keys to the built-in WebRTC layer and keeps them up to date for as long as the Stream Room is joined. A Stream Room accepts one join at a time.

Parameters

streamRoomId

ID of the Stream Room to join

leaveStreamRoom()

void privmx::endpoint::stream::StreamApi::leaveStreamRoom

(

const std::string &

streamRoomId

)

Leaves a Stream Room and closes all its Publisher and Subscriber Streams.

This call invalidates the handles of the Stream Room's Streams and closes their PeerConnections, so the user disappears from the list of participants. Join the Stream Room again to publish or receive anything in it.

Parameters

streamRoomId

ID of the Stream Room to leave

listStreamRoomParticipants()

std::vector< StreamSubscriber > privmx::endpoint::stream::StreamApi::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::StreamApi::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::StreamApi::listStreams

(

const std::string &

streamRoomId

)

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

The returned Streams and their tracks are what you pass 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::StreamApi::publishStream

(

const StreamHandle &

streamHandle

)

Publishes the Stream with the tracks currently added to it.

This method starts the capturers of the added tracks and sends them to the media server. A Stream which is already published throws StreamAlreadyPublishedException. 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::StreamApi::removeStream

(

const StreamHandle &

streamHandle

)

Stops publishing the Stream and closes it.

Parameters

streamHandle

handle returned by createStream

removeSubscriberStream()

void privmx::endpoint::stream::StreamApi::removeSubscriberStream

(

const SubscriberStreamHandle &

subscriptionHandle

)

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

Parameters

subscriptionHandle

handle returned by createSubscriberStream

removeTrack()

void privmx::endpoint::stream::StreamApi::removeTrack	(	const StreamHandle &	streamHandle,
		const MediaDevice &	track )

Removes a track from a Publisher Stream.

A track which has never been published disappears right away. A published one stays with the other participants until the next updateStream call.

Parameters

streamHandle	handle returned by createStream
track	media device previously passed to addTrack

sendData()

void privmx::endpoint::stream::StreamApi::sendData	(	const StreamHandle &	streamHandle,
		core::Buffer	data )

Encrypts and sends binary data over the Stream's data track.

The Stream needs a published data track, that is a device of the Plain type added with addTrack and sent by publishStream or updateStream. Otherwise this method throws DataTrackNotInitializedException.

Parameters

streamHandle	handle returned by createStream
data	data to send

subscribeFor()

std::vector< std::string > privmx::endpoint::stream::StreamApi::subscribeFor

(

const std::vector< std::string > &

subscriptionQueries

)

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

Build the queries with buildSubscriptionQuery. The returned IDs are the only way to stop receiving those events, so keep them for the matching unsubscribeFrom call.

Parameters

subscriptionQueries

list of queries

Returns

list of subscriptionIds in matching order to subscriptionQueries

unsubscribeFrom()

void privmx::endpoint::stream::StreamApi::unsubscribeFrom

(

const std::vector< std::string > &

subscriptionIds

)

Unsubscribe from events for the given subscriptionId.

Parameters

subscriptionIds

list of subscriptionId

updateStream()

StreamPublishResult privmx::endpoint::stream::StreamApi::updateStream

(

const StreamHandle &

streamHandle

)

Updates an already published Stream after its tracks have changed.

This method applies every addTrack and removeTrack call made since the Stream was published.

Parameters

streamHandle

handle returned by createStream

Returns

result of the update operation

updateStreamRoom()

void privmx::endpoint::stream::StreamApi::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::StreamApi::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.

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:

• stream/webrtc/include_pub/privmx/endpoint/stream/StreamApi.hpp