services::conference

Module: Conference Service

Provides methods of the Conference Service.

Attention: The conference interface that contains methods that return async_result. Each function that returns async_result is asynchronous and the operation is executed during the SDK event loop. The caller can block the calling thread until the operation completes using the wait helper. The caller can also chain consecutive operations, which are dependent on the completion of this method, using the async_result::then calls. Each async_result chain needs to be terminated with an async_result::on_error.

#include <conference.h>

Public Classes

Name
structjoin_options
The options that define how the application expects to join a conference in terms of media preference.
structconference_options
The conference options structure that provides additional information about a conference.

Public Functions

Name
virtual async_result< void >stop_video() =0
Destructs the WebRTC VideoTrack and detaches it from an active Peer Connection. This method also disconnects the Video Sink of the media_source_interface from the WebRTC Video Source, which deconstructs the video delivery pipeline. All frames captured after the return of stop_video are discarded, so an application should stop capturing video from the local media source when async_result of this method resolves.
virtual async_result< void >stop_audio() =0
Destructs a WebRTC AudioTrack and detaches it from an active Peer Connection. This method also disconnects the Audio Sink of the media_source_interface from the WebRTC Audio Source, which deconstructs the audio delivery pipeline. All frames captured after the return of stop_audio are discarded, so an application should stop capturing audio from the local media source when async_result of this method resolves.
virtual async_result< void >start_video() =0
Creates a WebRTC VideoTrack and attaches the VideoTrack to an active Peer Connection. This method also connects the Video Sink of the media_source_interface with the WebRTC Video Source, creating the video delivery pipeline. When the async_result of this method resolves, the application can start a video stream from any media source it chooses, pass the raw video frames to the injector module from this source, and inject the video frames into a conference.
virtual async_result< void >start_audio() =0
Creates a WebRTC AudioTrack and attaches the AudioTrack to an active Peer Connection. This method also connects the Audio Sink of the media_source_interface with the WebRTC Audio Source, creating the audio delivery pipeline. When the async_result of this method resolves, the application can start an audio stream from any media source it chooses, pass the raw audio PCM data to the injector module from this source, and inject the audio data into a conference.
virtual async_result< void >set_media_source(media_source_interface * source) =0
Sets the Media Injector instance as the Media Source for the SDK. The Media Injector module handles the injection of audio and video frames into WebRTC media pipelines. The module allows providing raw media frames from any source, for example, an external stream or a media file. The plugin::injector_paced and plugin::injector_passthrough modules are available as default injectors, although applications can also provide their own.
virtual async_result< void >set_media_sink(media_sink_interface * sink) =0
Sets the Media Recorder instance as the Media Sink for the SDK. The Media Recorder module handles pipelines for receiving, encoding, and muxing audio and video frames. The module also captures and processes audio and video tracks produced by WebRTC. The plugin::recorder module is available as the default recorder, although application users can also provide their own recorders.
virtual async_result< void >set_audio_processing(bool audio_processing) =0
This method enables and disables audio processing of the local audio stream that is sent to the conference.
virtual async_result< void >send(const std::string & message) =0
Sends a message to the current conference.
virtual async_result< conference_info >listen(const conference_info & conf, const join_options & join) =0
Joins an existing conference as a listener who can receive audio and video streams, but cannot send any stream to the conference.
virtual async_result< void >leave() =0
Leaves a conference.
virtual async_result< conference_info >join(const conference_info & conf, const join_options & join) =0
Joins an existing conference as an active user who can both receive media from the conference and inject media into the conference.
virtual async_result< conference_info >create(const conference_options & create) =0
Creates a conference and returns information about the conference upon completion.
virtual async_result< event_handler_id >add_event_handler(event_handler< conference_status_updated > && callback) =0
Adds a listener for the conference_status_updated events.
virtual async_result< event_handler_id >add_event_handler(event_handler< participant_added > && callback) =0
Adds a listener for the participant added events.
virtual async_result< event_handler_id >add_event_handler(event_handler< participant_updated > && callback) =0
Adds a listener for participant_updated events.
virtual async_result< event_handler_id >add_event_handler(event_handler< active_speaker_change > && callback) =0
Adds a listener for active_speaker_changed events.
virtual async_result< event_handler_id >add_event_handler(event_handler< dolbyio::comms::video_track_added > && callback) =0
Adds a listener for video_track_added events.
virtual async_result< event_handler_id >add_event_handler(event_handler< dolbyio::comms::video_track_removed > && callback) =0
Adds a listener for video_track_removed events.
virtual async_result< event_handler_id >add_event_handler(event_handler< dolbyio::comms::audio_track_added > && callback) =0
Adds a listener for audio_track_added events.
virtual async_result< event_handler_id >add_event_handler(event_handler< dolbyio::comms::audio_track_removed > && callback) =0
Adds a listener for audio_track_removed events.
virtual async_result< event_handler_id >add_event_handler(event_handler< dolbyio::comms::dvc_error_exception > && callback) =0
Uses the add_event_handler method for dvc_error_exception to handle DVC errors when the media engine encounters an error from the DVC libray.
virtual async_result< event_handler_id >add_event_handler(event_handler< dolbyio::comms::peer_connection_failed_exception > && callback) =0
Uses the add_event_handler method for peer_connection_failed_exception to handle errors which are generated when the PeerConnection has entered a failed state.
virtual async_result< event_handler_id >add_event_handler(event_handler< conference_message_received > && callback) =0
Adds a listener for conference_message_received events.
class dolbyio::comms::services::conference;

Public Functions Documentation

function stop_video

🚀

SDK Beta

This API is a part of the Beta program.

virtual async_result< void > stop_video() =0

Destructs the WebRTC VideoTrack and detaches it from an active Peer Connection. This method also disconnects the Video Sink of the media_source_interface from the WebRTC Video Source, which deconstructs the video delivery pipeline. All frames captured after the return of stop_video are discarded, so an application should stop capturing video from the local media source when async_result of this method resolves.

Return: The result object producing the operation status asynchronously.

Attention:

  • This method does not stop the capturing from a media source; this action needs to be performed separately by an application before or after calling stop_video.
  • Call this method only when a conference is active.
// Invoke the method via wait blocks until the method succeeds or fails
wait(sdk->conference().stop_video());

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().stop_video()
  .then([this]() {
    if (file_injection_src_)
     file_injection_src_->stop_reading_video();
  })
  .on_error([](auto&& e) {
    // starting video track failed
  });

function stop_audio

🚀

SDK Beta

This API is a part of the Beta program.

virtual async_result< void > stop_audio() =0

Destructs a WebRTC AudioTrack and detaches it from an active Peer Connection. This method also disconnects the Audio Sink of the media_source_interface from the WebRTC Audio Source, which deconstructs the audio delivery pipeline. All frames captured after the return of stop_audio are discarded, so an application should stop capturing audio from the local media source when async_result of this method resolves.

Return: The result object producing the operation status asynchronously.

Attention:

  • This method does not stop the capturing from a media source; this action needs to be performed separately by an application before or after calling stop_audio.
  • Call this method only when a conference is active.
// Invoke the method via wait blocks until the method succeeds or fails
wait(sdk->conference().stop_audio());

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().stop_audio()
  .then([this]() {
    if (file_injection_src_)
     file_injection_src_->stop_reading_audio();
  })
  .on_error([](auto&& e) {
    // starting audio track failed
  });

function start_video

🚀

SDK Beta

This API is a part of the Beta program.

virtual async_result< void > start_video() =0

Creates a WebRTC VideoTrack and attaches the VideoTrack to an active Peer Connection. This method also connects the Video Sink of the media_source_interface with the WebRTC Video Source, creating the video delivery pipeline. When the async_result of this method resolves, the application can start a video stream from any media source it chooses, pass the raw video frames to the injector module from this source, and inject the video frames into a conference.

Return: The result object producing the operation status asynchronously.

Attention:

  • This method does not start the capturing from a media source; this action needs to be performed separately, when the async_result of this method is resolved.
  • Call this method only when a conference is active.
// Invoke the method via wait blocks until the method succeeds or fails
wait(sdk->conference().start_video());

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().start_video()
  .then([this]() {
    if (file_injection_src_)
     file_injection_src_->start_reading_video();
  })
  .on_error([](auto&& e) {
    // starting video track failed
  });

function start_audio

🚀

SDK Beta

This API is a part of the Beta program.

virtual async_result< void > start_audio() =0

Creates a WebRTC AudioTrack and attaches the AudioTrack to an active Peer Connection. This method also connects the Audio Sink of the media_source_interface with the WebRTC Audio Source, creating the audio delivery pipeline. When the async_result of this method resolves, the application can start an audio stream from any media source it chooses, pass the raw audio PCM data to the injector module from this source, and inject the audio data into a conference.

Return: The result object producing the operation status asynchronously.

Attention:

  • This method does not start the capturing from a media source; this action needs to be performed separately, when the async_result of this method is resolved.
  • Call this method only when a conference is active.
// Invoke the method via wait blocks until the method succeeds or fails
wait(sdk->conference().start_audio());

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().start_audio()
  .then([this]() {
    if (file_injection_src_)
     file_injection_src_->start_reading_audio();
  })
  .on_error([](auto&& e) {
    // starting audio track failed
  });

function set_media_source

🚀

SDK Beta

This API is a part of the Beta program.

virtual async_result< void > set_media_source(
    media_source_interface * source
) =0

Sets the Media Injector instance as the Media Source for the SDK. The Media Injector module handles the injection of audio and video frames into WebRTC media pipelines. The module allows providing raw media frames from any source, for example, an external stream or a media file. The plugin::injector_paced and plugin::injector_passthrough modules are available as default injectors, although applications can also provide their own.

Parameters:

  • source The pointer to the instance of the Media Source interface, which can be either the default injector or an implemented customized injector module.

Return: The result object producing the operation status asynchronously.

Attention: The media injector can not be set when a conference is active.

// Invoke the method via wait blocks until the method succeeds or fails
wait(sdk->conference().set_media_source(injector));

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().set_media_source(injector)
  .then([]() {
    // Media source is now set
  })
  .on_error([](auto&& e) {
    // handle exception
  });

function set_media_sink

virtual async_result< void > set_media_sink(
    media_sink_interface * sink
) =0

Sets the Media Recorder instance as the Media Sink for the SDK. The Media Recorder module handles pipelines for receiving, encoding, and muxing audio and video frames. The module also captures and processes audio and video tracks produced by WebRTC. The plugin::recorder module is available as the default recorder, although application users can also provide their own recorders.

Parameters:

  • sink The pointer to the instance of the Media Sink interface, which can be either the default recorder created through the plugin::recorder interface or an implemented customized recording module.

Return: The result object producing the operation status asynchronously.

Attention: The media recorder can not be set when a conference is active.

// Invoke the method via wait blocks until the method succeeds or fails
wait(sdk->conference().set_media_sink(recorder));

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().set_media_sink(recorder)
  .then([]() {
    // Media capturer is now set
  })
  .on_error([](auto&& e) {
    // handle exception
  });

function set_audio_processing

🚀

SDK Beta

This API is a part of the Beta program.

virtual async_result< void > set_audio_processing(
    bool audio_processing
) =0

This method enables and disables audio processing of the local audio stream that is sent to the conference.

Return: The result object producing the operation status asynchronously.

Attention: Call this method only when a conference is active.

// Invoke the method via wait blocks until the method succeeds or fails
wait(sdk->conference().set_audio_processing(false));

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().set_audio_processing(false)
  .then([]() {
    // audio processing turned off
  })
  .on_error([](auto&& e) {
    // setting audio processing failed
  });

function send

virtual async_result< void > send(
    const std::string & message
) =0

Sends a message to the current conference. Message size is limited to 16KB.

Parameters:

  • message The message.

Return: The result object producing the operation status asynchronously.

// Invoke the method via wait blocks until the method succeeds or fails
wait(sdk->conference().send("some message"));

// Invoking the method directly requires chaining successive operations
// via the `then` call
 sdk->conference().send("some message")
 .then([]() {
    // the message was sent
 })
 .on_error([](auto&& e){
    // rethrow and handle the exception
 });

function listen

virtual async_result< conference_info > listen(
    const conference_info & conf,
    const join_options & join
) =0

Joins an existing conference as a listener who can receive audio and video streams, but cannot send any stream to the conference.

Parameters:

  • conf The conference options that need to contain conference_id.
  • join The join options for the SDK user.

Return: The result object producing the #conference_info asynchronously.

// Invoke the method via wait blocks until the method succeeds or fails
wait(sdk->conference().listen(conf, join));

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().listen(conf, join)
  .then([](conference_info&&) {
    // the user joined the conference
  })
  .on_error([](auto&& e) {
    // handle exception
  });

function leave

virtual async_result< void > leave() =0

Leaves a conference.

Return: The result object producing the operation status asynchronously.

// Invoke the method via wait blocks until the method succeeds or fails
wait(sdk->conference().leave());

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().leave()
  .then([]() {
    // the user left the conference
  })
  .on_error([](auto&& e) {
    // handle exception
  });

function join

🚀

SDK Beta

This API is a part of the Beta program.

virtual async_result< conference_info > join(
    const conference_info & conf,
    const join_options & join
) =0

Joins an existing conference as an active user who can both receive media from the conference and inject media into the conference.

Parameters:

  • conf The conference options that need to contain conference_id.
  • join The join options for the SDK user.

Return: The result object producing the #conference_info asynchronously.

// Wait for the conference creation
auto conf_info = wait(sdk->conference().join(conf_options, join_options));

// Use the returned value in the `then` call
sdk->conference().join(conf_options, join_options))
   .then[](auto&& info) {
     // do something with the returned conf info;
   })
   .on_error([](auto&& e) {
     // handle exception
   });

function create

virtual async_result< conference_info > create(
    const conference_options & create
) =0

Creates a conference and returns information about the conference upon completion.

Parameters:

  • create The conference options.

Return: The result object producing the #conference_info asynchronously.

// Wait for the conference creation
auto conf_info = wait(sdk->conference().create(options));

// Use the returned value in the `then` call
sdk->conference().create(options))
   .then[](auto&& info) {
     // do something with the returned conf info;
   })
   .on_error([](auto&& e) {
     // handle exception
   });

function add_event_handler

virtual async_result< event_handler_id > add_event_handler(
    event_handler< conference_status_updated > && callback
) =0

Adds a listener for the conference_status_updated events.

Parameters:

  • callback The function object that will be invoked when the conference status changes.

Return: The result object producing the event_handler_id asynchronously.

// Invoke the method via wait blocks until the method succeeds or fails
handlers.push_back(wait(sdk->conference().add_event_handler(
  [](const dolbyio::comms::conference_status_updated& e) {
    // process the event
  })));

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().add_event_handler(
  [](const dolbyio::comms::conference_status_updated& e) {
    // process the event
  }))
  .then([this](event_handler_id&& handler) {
    this->handlers.push_back(std::move(handler));
  })
  .on_error([](auto&& e) {
    // handle exception
  });

function add_event_handler

virtual async_result< event_handler_id > add_event_handler(
    event_handler< participant_added > && callback
) =0

Adds a listener for the participant added events.

Parameters:

  • callback The function object that will be invoked when a participant is added to the conference.

Return: The result object producing the event_handler_id asynchronously.

 // Invoke the method via wait blocks until the method succeeds or fails
 handlers.push_back(wait(sdk->conference().add_event_handler(
   [](const dolbyio::comms::participant_added& e) {
     // process the event
   })));

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().add_event_handler(
  [](const dolbyio::comms::participant_added& e) {
    // process the event
  }))
  .then([this](event_handler_id&& handler) {
    this->handlers.push_back(std::move(handler));
  })
  .on_error([](auto&& e) {
    // handle exception
  });

function add_event_handler

virtual async_result< event_handler_id > add_event_handler(
    event_handler< participant_updated > && callback
) =0

Adds a listener for participant_updated events.

Parameters:

  • callback The function object that will be invoked when a conference participant changes status.

Return: The result object producing the event_handler_id asynchronously.

// Invoke the method via wait blocks until the method succeeds or fails
handlers.push_back(wait(sdk->conference().add_event_handler(
  [](const dolbyio::comms::participant_updated& e) {
    // process the event
  })));

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().add_event_handler(
  [](const dolbyio::comms::participant_updated& e) {
    // process the event
  }))
  .then([this](event_handler_id&& handler) {
    this->handlers.push_back(std::move(handler));
  })
  .on_error([](auto&& e) {
    // handle exception
  });

function add_event_handler

virtual async_result< event_handler_id > add_event_handler(
    event_handler< active_speaker_change > && callback
) =0

Adds a listener for active_speaker_changed events.

Parameters:

  • callback The function object that will be invoked when the active speaker changes.

Return: The result object producing the event_handler_id asynchronously.

// Invoke the method via wait blocks until the method succeeds or fails
handlers.push_back(wait(sdk->conference().add_event_handler(
  [](const dolbyio::comms::active_speaker_change& e) {
    // process the event
  })));

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().add_event_handler(
  [](const dolbyio::comms::active_speaker_change& e) {
    // process the event
  }))
  .then([this](event_handler_id&& handler) {
    this->handlers.push_back(std::move(handler));
  })
  .on_error([](auto&& e) {
    // handle exception
  });

function add_event_handler

virtual async_result< event_handler_id > add_event_handler(
    event_handler< dolbyio::comms::video_track_added > && callback
) =0

Adds a listener for video_track_added events.

Parameters:

  • callback The function object that will be invoked when a new video track is added to a conference.

Return: The result object producing the event_handler_id asynchronously.

// Invoke the method via wait blocks until the method succeeds or fails
handlers.push_back(wait(sdk->conference().add_event_handler(
  [](const dolbyio::comms::video_track_added& e) {
    // process the event
  })));

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().add_event_handler(
  [](const dolbyio::comms::video_track_added& e) {
    // process the event
  }))
  .then([this](event_handler_id&& handler) {
    this->handlers.push_back(std::move(handler));
  })
  .on_error([](auto&& e) {
    // handle exception
  });

function add_event_handler

virtual async_result< event_handler_id > add_event_handler(
    event_handler< dolbyio::comms::video_track_removed > && callback
) =0

Adds a listener for video_track_removed events.

Parameters:

  • callback The function object that will be invoked when a video track is removed from a conference.

Return: The result object producing the event_handler_id asynchronously.

// Invoke the method via wait blocks until the method succeeds or fails
handlers.push_back(wait(sdk->conference().add_event_handler(
  [](const dolbyio::comms::video_track_removed& e) {
    // process the event
  })));

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().add_event_handler(
  [](const dolbyio::comms::video_track_removed& e) {
    // process the event
  }))
  .then([this](event_handler_id&& handler) {
    this->handlers.push_back(std::move(handler));
  })
  .on_error([](auto&& e) {
    // handle exception
  });

function add_event_handler

virtual async_result< event_handler_id > add_event_handler(
    event_handler< dolbyio::comms::audio_track_added > && callback
) =0

Adds a listener for audio_track_added events.

Parameters:

  • callback The function object that will be invoked when a new audio track is added to a conference.

Return: The result object producing the event_handler_id asynchronously.

// Invoke the method via wait blocks until the method succeeds or fails
handlers.push_back(wait(sdk->conference().add_event_handler(
  [](const dolbyio::comms::audio_track_added& e) {
    // process the event
  })));

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().add_event_handler(
  [](const dolbyio::comms::audio_track_added& e) {
    // process the event
  }))
  .then([this](event_handler_id&& handler) {
    this->handlers.push_back(std::move(handler));
  })
  .on_error([](auto&& e) {
    // handle exception
  });

function add_event_handler

virtual async_result< event_handler_id > add_event_handler(
    event_handler< dolbyio::comms::audio_track_removed > && callback
) =0

Adds a listener for audio_track_removed events.

Parameters:

  • callback The function object that will be invoked when an audio track is removed from a conference.

Return: The result object producing the event_handler_id asynchronously.

// Invoke the method via wait blocks until the method succeeds or fails
handlers.push_back(wait(sdk->conference().add_event_handler(
  [](const dolbyio::comms::audio_track_removed& e) {
    // process the event
  })));

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().add_event_handler(
  [](const dolbyio::comms::audio_track_removed& e) {
    // process the event
  }))
  .then([this](event_handler_id&& handler) {
    this->handlers.push_back(std::move(handler));
  })
  .on_error([](auto&& e) {
    // handle exception
  });

function add_event_handler

virtual async_result< event_handler_id > add_event_handler(
    event_handler< dolbyio::comms::dvc_error_exception > && callback
) =0

Uses the add_event_handler method for dvc_error_exception to handle DVC errors when the media engine encounters an error from the DVC libray.

Parameters:

Return: The result object producing the event_handler_id asynchronously.

// Invoke the method via wait blocks until the method succeeds or fails
handlers.push_back(wait(sdk->conference().add_event_handler(
  [](const dolbyio::comms::dvc_error_exception& e) {
    // process the event
  })));

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().add_event_handler(
  [](const dolbyio::comms::dvc_error_exception& e) {
    // process the event
  }))
  .then([this](event_handler_id&& handler) {
    this->handlers.push_back(std::move(handler));
  })
  .on_error([](auto&& e) {
    // handle exception
  });

function add_event_handler

virtual async_result< event_handler_id > add_event_handler(
    event_handler< dolbyio::comms::peer_connection_failed_exception > && callback
) =0

Uses the add_event_handler method for peer_connection_failed_exception to handle errors which are generated when the PeerConnection has entered a failed state.

Parameters:

Return: The result object producing the event_handler_id asynchronously.

// Invoke the method via wait blocks until the method succeeds or fails
handlers.push_back(wait(sdk->conference().add_event_handler(
  [](const dolbyio::comms::peer_connection_failed_exception& e) {
    // process the event
  })));

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().add_event_handler(
  [](const dolbyio::comms::peer_connection_failed_exception& e) {
    // process the event
  }))
  .then([this](event_handler_id&& handler) {
    this->handlers.push_back(std::move(handler));
  })
  .on_error([](auto&& e) {
    // handle exception
  });

function add_event_handler

virtual async_result< event_handler_id > add_event_handler(
    event_handler< conference_message_received > && callback
) =0

Adds a listener for conference_message_received events.

Parameters:

  • callback The function object that will be invoked when a message is received in the conference.

Return: The async_result class that wraps a solver that can contain the event_handler_id object.

 // Invoke the method via wait blocks until the method succeeds or fails
 handlers.push_back(wait(sdk->conference().add_event_handler(
     [](const dolbyio::comms::conference_message_received& e) {
       // process the event
     })));

// Invoking the method directly requires chaining successive operations
// via the `then` call
 sdk->conference().add_event_handler(
     [](const dolbyio::comms::conference_message_received& e) {
       // process the event
     })
     .then([this](event_handler_id&& handler) {
       this->handlers.push_back(std::move(handler);
     })
     .on_error([](auto&& e){
       //handle an exception
     });


Did this page help you?