From ccefde95b3bbc1129e1fd29fd73130f55e30b5c6 Mon Sep 17 00:00:00 2001 From: Tim Na Date: Tue, 3 Mar 2020 09:29:22 -0800 Subject: [PATCH] VoIP interfaces API enhancement (continuation of 169000) Bug: webrtc:11251 Change-Id: Iecde33b86856b14db5abade3301a842d5007568d Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/169034 Commit-Queue: Tim Na Reviewed-by: Karl Wiberg Cr-Commit-Position: refs/heads/master@{#30675} --- api/voip/BUILD.gn | 3 +- api/voip/DEPS | 5 +++ api/voip/voip_base.h | 79 +++++++++++++++++++++++------------------ api/voip/voip_codec.h | 9 ++--- api/voip/voip_engine.h | 46 ++++++++++++------------ api/voip/voip_network.h | 13 ++++--- 6 files changed, 85 insertions(+), 70 deletions(-) create mode 100644 api/voip/DEPS diff --git a/api/voip/BUILD.gn b/api/voip/BUILD.gn index f32240a4c3..665b9e3da3 100644 --- a/api/voip/BUILD.gn +++ b/api/voip/BUILD.gn @@ -17,7 +17,8 @@ rtc_source_set("voip_api") { "voip_network.h", ] deps = [ - "..:transport_api", + "..:array_view", "../audio_codecs:audio_codecs_api", + "//third_party/abseil-cpp/absl/types:optional", ] } diff --git a/api/voip/DEPS b/api/voip/DEPS new file mode 100644 index 0000000000..446fd4ef5e --- /dev/null +++ b/api/voip/DEPS @@ -0,0 +1,5 @@ +specific_include_rules = { + ".*\.h": [ + "+third_party/absl/types/optional.h", + ], +} \ No newline at end of file diff --git a/api/voip/voip_base.h b/api/voip/voip_base.h index 4fb369090b..67cd49b242 100644 --- a/api/voip/voip_base.h +++ b/api/voip/voip_base.h @@ -11,10 +11,12 @@ #ifndef API_VOIP_VOIP_BASE_H_ #define API_VOIP_VOIP_BASE_H_ -#include "api/call/transport.h" +#include "third_party/absl/types/optional.h" namespace webrtc { +class Transport; + // VoipBase interface // // VoipBase provides a management interface on a media session using a @@ -22,7 +24,7 @@ namespace webrtc { // for application to request various media session operations. This // notion of channel is used throughout other interfaces as well. // -// Underneath the interface, a channel handle is mapped into an audio session +// Underneath the interface, a channel id is mapped into an audio session // object that is capable of sending and receiving a single RTP stream with // another media endpoint. It's possible to create and use multiple active // channels simultaneously which would mean that particular application @@ -30,47 +32,56 @@ namespace webrtc { // // A typical example for the usage context is outlined in VoipEngine // header file. + +enum class ChannelId : int {}; + class VoipBase { public: - // This config enables application to set webrtc::Transport callback pointer - // to receive rtp/rtcp packets from corresponding media session in VoIP - // engine. VoipEngine framework expects applications to handle network I/O - // directly and injection for incoming RTP from remote endpoint is handled - // via VoipNetwork interface. - struct Config { - Transport* transport = nullptr; - uint32_t local_ssrc = 0; - }; + // Creates a channel. + // Each channel handle maps into one audio media session where each has + // its own separate module for send/receive rtp packet with one peer. + // Caller must set |transport|, webrtc::Transport callback pointer to + // receive rtp/rtcp packets from corresponding media session in VoIP engine. + // VoipEngine framework expects applications to handle network I/O directly + // and injection for incoming RTP from remote endpoint is handled via + // VoipNetwork interface. |local_ssrc| is optional and when local_ssrc is not + // set, some random value will be used by voip engine. + // Returns value is optional as to indicate the failure to create channel. + virtual absl::optional CreateChannel( + Transport* transport, + absl::optional local_ssrc) = 0; - // Create a channel handle. - // Valid handle value is zero or greater integer whereas -1 represents error - // during media session construction. Each channel handle maps into one - // audio media session where each has its own separate module for - // send/receive rtp packet with one peer. - virtual int CreateChannel(const Config& config) = 0; + // Releases |channel_id| that has served the purpose. + // Released channel will be re-allocated again that invoking operations + // on released |channel_id| will lead to undefined behavior. + virtual void ReleaseChannel(ChannelId channel_id) = 0; - // Following methods return boolean to indicate if the operation is succeeded. - // API is subject to expand to reflect error condition to application later. + // Starts sending on |channel_id|. This will start microphone if first to + // start. Returns false if initialization has failed on selected microphone + // device. API is subject to expand to reflect error condition to application + // later. + virtual bool StartSend(ChannelId channel_id) = 0; - // Release |channel| that has served the purpose. - // Released channel handle will be re-allocated again. Invoking - // an operation on released channel will lead to undefined behavior. - virtual bool ReleaseChannel(int channel) = 0; - - // Start sending on |channel|. This will start microphone if first to start. - virtual bool StartSend(int channel) = 0; - - // Stop sending on |channel|. If this is the last active channel, it will + // Stops sending on |channel_id|. If this is the last active channel, it will // stop microphone input from underlying audio platform layer. - virtual bool StopSend(int channel) = 0; + // Returns false if termination logic has failed on selected microphone + // device. API is subject to expand to reflect error condition to application + // later. + virtual bool StopSend(ChannelId channel_id) = 0; - // Start playing on speaker device for |channel|. + // Starts playing on speaker device for |channel_id|. // This will start underlying platform speaker device if not started. - virtual bool StartPlayout(int channel) = 0; + // Returns false if initialization has failed + // on selected speaker device. API is subject to expand to reflect error + // condition to application later. + virtual bool StartPlayout(ChannelId channel_id) = 0; - // Stop playing on speaker device for |channel|. If this is the last - // active channel playing, then it will stop speaker from the platform layer. - virtual bool StopPlayout(int channel) = 0; + // Stops playing on speaker device for |channel_id|. + // If this is the last active channel playing, then it will stop speaker + // from the platform layer. + // Returns false if termination logic has failed on selected speaker device. + // API is subject to expand to reflect error condition to application later. + virtual bool StopPlayout(ChannelId channel_id) = 0; protected: virtual ~VoipBase() = default; diff --git a/api/voip/voip_codec.h b/api/voip/voip_codec.h index bba2bb707a..32c4a72e05 100644 --- a/api/voip/voip_codec.h +++ b/api/voip/voip_codec.h @@ -14,6 +14,7 @@ #include #include "api/audio_codecs/audio_format.h" +#include "api/voip/voip_base.h" namespace webrtc { @@ -24,11 +25,11 @@ namespace webrtc { // are used with negotiated codecs. This interface is subject to expand // as needed in future. // -// This interface requires a channel handle created via VoipBase interface. +// This interface requires a channel id created via VoipBase interface. class VoipCodec { public: // Set encoder type here along with its payload type to use. - virtual bool SetSendCodec(int channel, + virtual void SetSendCodec(ChannelId channel_id, int payload_type, const SdpAudioFormat& encoder_spec) = 0; @@ -36,8 +37,8 @@ class VoipCodec { // this should be called after payload type has been agreed in media // session. Note that payload type can differ with same codec in each // direction. - virtual bool SetReceiveCodecs( - int channel, + virtual void SetReceiveCodecs( + ChannelId channel_id, const std::map& decoder_specs) = 0; protected: diff --git a/api/voip/voip_engine.h b/api/voip/voip_engine.h index 6fc1c534ef..96905a121d 100644 --- a/api/voip/voip_engine.h +++ b/api/voip/voip_engine.h @@ -11,14 +11,12 @@ #ifndef API_VOIP_VOIP_ENGINE_H_ #define API_VOIP_VOIP_ENGINE_H_ -#include - -#include "api/voip/voip_base.h" -#include "api/voip/voip_codec.h" -#include "api/voip/voip_network.h" - namespace webrtc { +class VoipBase; +class VoipCodec; +class VoipNetwork; + // VoipEngine interfaces // // These pointer interfaces are valid as long as VoipEngine is available. @@ -31,47 +29,47 @@ namespace webrtc { // .SetAudioDecoderFactory(CreateBuiltinAudioDecoderFactory()) // .Create(); // -// auto* voip_base = voip_engine->Base(); -// auto* voip_codec = voip_engine->Codec(); -// auto* voip_network = voip_engine->Network(); +// auto voip_base = voip_engine->Base(); +// auto voip_codec = voip_engine->Codec(); +// auto voip_network = voip_engine->Network(); // // VoipChannel::Config config = { &app_transport_, 0xdeadc0de }; -// int channel = voip_base->CreateChannel(config); +// int channel = voip_base.CreateChannel(config); // // // After SDP offer/answer, payload type and codec usage have been // // decided through negotiation. -// voip_codec->SetSendCodec(channel, ...); -// voip_codec->SetReceiveCodecs(channel, ...); +// voip_codec.SetSendCodec(channel, ...); +// voip_codec.SetReceiveCodecs(channel, ...); // // // Start Send/Playout on voip channel. -// voip_base->StartSend(channel); -// voip_base->StartPlayout(channel); +// voip_base.StartSend(channel); +// voip_base.StartPlayout(channel); // // // Inject received rtp/rtcp thru voip network interface. -// voip_network->ReceivedRTPPacket(channel, rtp_data, rtp_size); -// voip_network->ReceivedRTCPPacket(channel, rtcp_data, rtcp_size); +// voip_network.ReceivedRTPPacket(channel, rtp_data, rtp_size); +// voip_network.ReceivedRTCPPacket(channel, rtcp_data, rtcp_size); // // // Stop and release voip channel. -// voip_base->StopSend(channel); -// voip_base->StopPlayout(channel); +// voip_base.StopSend(channel); +// voip_base.StopPlayout(channel); // -// voip_base->ReleaseChannel(channel); +// voip_base.ReleaseChannel(channel); // class VoipEngine { public: + virtual ~VoipEngine() = default; + // VoipBase is the audio session management interface that // create/release/start/stop one-to-one audio media session. - virtual VoipBase* Base() = 0; + virtual VoipBase& Base() = 0; // VoipNetwork provides injection APIs that would enable application // to send and receive RTP/RTCP packets. There is no default network module // that provides RTP transmission and reception. - virtual VoipNetwork* Network() = 0; + virtual VoipNetwork& Network() = 0; // VoipCodec provides codec configuration APIs for encoder and decoders. - virtual VoipCodec* Codec() = 0; - - virtual ~VoipEngine() = default; + virtual VoipCodec& Codec() = 0; }; } // namespace webrtc diff --git a/api/voip/voip_network.h b/api/voip/voip_network.h index c22018eefd..774297898d 100644 --- a/api/voip/voip_network.h +++ b/api/voip/voip_network.h @@ -11,7 +11,8 @@ #ifndef API_VOIP_VOIP_NETWORK_H_ #define API_VOIP_VOIP_NETWORK_H_ -#include "api/call/transport.h" +#include "api/array_view.h" +#include "api/voip/voip_base.h" namespace webrtc { @@ -25,16 +26,14 @@ class VoipNetwork { // The packets received from the network should be passed to this // function. Note that the data including the RTP-header must also be // given to the VoipEngine. - virtual bool ReceivedRTPPacket(int channel, - const uint8_t* data, - size_t length) = 0; + virtual void ReceivedRTPPacket(ChannelId channel_id, + rtc::ArrayView data) = 0; // The packets received from the network should be passed to this // function. Note that the data including the RTCP-header must also be // given to the VoipEngine. - virtual bool ReceivedRTCPPacket(int channel, - const uint8_t* data, - size_t length) = 0; + virtual void ReceivedRTCPPacket(ChannelId channel_id, + rtc::ArrayView data) = 0; protected: virtual ~VoipNetwork() = default;