Defining API result types on VoIP API
Bug: webrtc:12193
Change-Id: I6f5ffd82cc838e6982257781f225f9d8159e6b82
Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/193720
Commit-Queue: Tim Na <natim@webrtc.org>
Reviewed-by: Karl Wiberg <kwiberg@webrtc.org>
Cr-Commit-Position: refs/heads/master@{#32656}
diff --git a/api/voip/voip_base.h b/api/voip/voip_base.h
index ef83b51..c5f54aa 100644
--- a/api/voip/voip_base.h
+++ b/api/voip/voip_base.h
@@ -35,6 +35,21 @@
enum class ChannelId : int {};
+enum class VoipResult {
+ // kOk indicates the function was successfully invoked with no error.
+ kOk,
+ // kInvalidArgument indicates the caller specified an invalid argument, such
+ // as an invalid ChannelId.
+ kInvalidArgument,
+ // kFailedPrecondition indicates that the operation was failed due to not
+ // satisfying prerequisite such as not setting codec type before sending.
+ kFailedPrecondition,
+ // kInternal is used to indicate various internal failures that are not the
+ // caller's fault. Further detail is commented on each function that uses this
+ // return value.
+ kInternal,
+};
+
class VoipBase {
public:
// Creates a channel.
@@ -46,40 +61,48 @@
// 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<ChannelId> CreateChannel(
- Transport* transport,
- absl::optional<uint32_t> local_ssrc) = 0;
+ // Returns a ChannelId created for caller to handle subsequent Channel
+ // operations.
+ virtual ChannelId CreateChannel(Transport* transport,
+ absl::optional<uint32_t> local_ssrc) = 0;
// Releases |channel_id| that no longer has any use.
- virtual void ReleaseChannel(ChannelId channel_id) = 0;
+ // Returns following VoipResult;
+ // kOk - |channel_id| is released.
+ // kInvalidArgument - |channel_id| is invalid.
+ // kInternal - Fails to stop audio output device.
+ virtual VoipResult ReleaseChannel(ChannelId channel_id) = 0;
- // Starts sending on |channel_id|. This will start microphone if not started
- // yet. 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;
+ // Starts sending on |channel_id|. This starts microphone if not started yet.
+ // Returns following VoipResult;
+ // kOk - Channel successfully started to send.
+ // kInvalidArgument - |channel_id| is invalid.
+ // kFailedPrecondition - Missing prerequisite on VoipCodec::SetSendCodec.
+ // kInternal - initialization has failed on selected microphone.
+ virtual VoipResult StartSend(ChannelId channel_id) = 0;
// Stops sending on |channel_id|. If this is the last active channel, it will
// stop microphone input from underlying audio platform layer.
- // 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;
+ // Returns following VoipResult;
+ // kOk - Channel successfully stopped to send.
+ // kInvalidArgument - |channel_id| is invalid.
+ // kInternal - Failed to stop the active microphone device.
+ virtual VoipResult StopSend(ChannelId channel_id) = 0;
// Starts playing on speaker device for |channel_id|.
// This will start underlying platform speaker device if not started.
- // 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;
+ // Returns following VoipResult;
+ // kOk - Channel successfully started to play out.
+ // kInvalidArgument - |channel_id| is invalid.
+ // kFailedPrecondition - Missing prerequisite on VoipCodec::SetReceiveCodecs.
+ // kInternal - Failed to initializate the selected speaker device.
+ virtual VoipResult StartPlayout(ChannelId channel_id) = 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;
+ // Returns following VoipResult;
+ // kOk - Channel successfully stopped t play out.
+ // kInvalidArgument - |channel_id| is invalid.
+ virtual VoipResult StopPlayout(ChannelId channel_id) = 0;
protected:
virtual ~VoipBase() = default;
diff --git a/api/voip/voip_codec.h b/api/voip/voip_codec.h
index eb42c44..fec3827 100644
--- a/api/voip/voip_codec.h
+++ b/api/voip/voip_codec.h
@@ -29,15 +29,21 @@
class VoipCodec {
public:
// Set encoder type here along with its payload type to use.
- virtual void SetSendCodec(ChannelId channel_id,
- int payload_type,
- const SdpAudioFormat& encoder_spec) = 0;
+ // Returns following VoipResult;
+ // kOk - sending codec is set as provided.
+ // kInvalidArgument - |channel_id| is invalid.
+ virtual VoipResult SetSendCodec(ChannelId channel_id,
+ int payload_type,
+ const SdpAudioFormat& encoder_spec) = 0;
// Set decoder payload type here. In typical offer and answer model,
// 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 void SetReceiveCodecs(
+ // Returns following VoipResult;
+ // kOk - receiving codecs are set as provided.
+ // kInvalidArgument - |channel_id| is invalid.
+ virtual VoipResult SetReceiveCodecs(
ChannelId channel_id,
const std::map<int, SdpAudioFormat>& decoder_specs) = 0;
diff --git a/api/voip/voip_dtmf.h b/api/voip/voip_dtmf.h
index 56817ba..a7367be 100644
--- a/api/voip/voip_dtmf.h
+++ b/api/voip/voip_dtmf.h
@@ -43,9 +43,12 @@
// Register the payload type and sample rate for DTMF (RFC 4733) payload.
// Must be called exactly once prior to calling SendDtmfEvent after payload
// type has been negotiated with remote.
- virtual void RegisterTelephoneEventType(ChannelId channel_id,
- int rtp_payload_type,
- int sample_rate_hz) = 0;
+ // Returns following VoipResult;
+ // kOk - telephone event type is registered as provided.
+ // kInvalidArgument - |channel_id| is invalid.
+ virtual VoipResult RegisterTelephoneEventType(ChannelId channel_id,
+ int rtp_payload_type,
+ int sample_rate_hz) = 0;
// Send DTMF named event as specified by
// https://tools.ietf.org/html/rfc4733#section-3.2
@@ -53,10 +56,14 @@
// in place of real RTP packets instead.
// Must be called after RegisterTelephoneEventType and VoipBase::StartSend
// have been called.
- // Returns true if the requested DTMF event is successfully scheduled.
- virtual bool SendDtmfEvent(ChannelId channel_id,
- DtmfEvent dtmf_event,
- int duration_ms) = 0;
+ // Returns following VoipResult;
+ // kOk - requested DTMF event is successfully scheduled.
+ // kInvalidArgument - |channel_id| is invalid.
+ // kFailedPrecondition - Missing prerequisite on RegisterTelephoneEventType
+ // or sending state.
+ virtual VoipResult SendDtmfEvent(ChannelId channel_id,
+ DtmfEvent dtmf_event,
+ int duration_ms) = 0;
protected:
virtual ~VoipDtmf() = default;
diff --git a/api/voip/voip_engine.h b/api/voip/voip_engine.h
index 69c0a85..d223f6a 100644
--- a/api/voip/voip_engine.h
+++ b/api/voip/voip_engine.h
@@ -23,7 +23,7 @@
// VoipEngine is the main interface serving as the entry point for all VoIP
// APIs. A single instance of VoipEngine should suffice the most of the need for
// typical VoIP applications as it handles multiple media sessions including a
-// specialized session type like ad-hoc mesh conferencing. Below example code
+// specialized session type like ad-hoc conference. Below example code
// describes the typical sequence of API usage. Each API header contains more
// description on what the methods are used for.
//
@@ -38,36 +38,35 @@
// config.audio_processing = AudioProcessingBuilder().Create();
//
// auto voip_engine = CreateVoipEngine(std::move(config));
-// if (!voip_engine) return some_failure;
//
// auto& voip_base = voip_engine->Base();
// auto& voip_codec = voip_engine->Codec();
// auto& voip_network = voip_engine->Network();
//
-// absl::optional<ChannelId> channel =
-// voip_base.CreateChannel(&app_transport_);
-// if (!channel) return some_failure;
+// ChannelId channel = voip_base.CreateChannel(&app_transport_);
//
// // After SDP offer/answer, set payload type and codecs that have been
// // decided through SDP negotiation.
-// voip_codec.SetSendCodec(*channel, ...);
-// voip_codec.SetReceiveCodecs(*channel, ...);
+// // VoipResult handling omitted here.
+// voip_codec.SetSendCodec(channel, ...);
+// voip_codec.SetReceiveCodecs(channel, ...);
//
// // Start sending and playing RTP on voip channel.
-// voip_base.StartSend(*channel);
-// voip_base.StartPlayout(*channel);
+// // VoipResult handling omitted here.
+// voip_base.StartSend(channel);
+// voip_base.StartPlayout(channel);
//
// // Inject received RTP/RTCP through VoipNetwork interface.
-// voip_network.ReceivedRTPPacket(*channel, ...);
-// voip_network.ReceivedRTCPPacket(*channel, ...);
+// // VoipResult handling omitted here.
+// voip_network.ReceivedRTPPacket(channel, ...);
+// voip_network.ReceivedRTCPPacket(channel, ...);
//
// // Stop and release voip channel.
-// voip_base.StopSend(*channel);
-// voip_base.StopPlayout(*channel);
-// voip_base.ReleaseChannel(*channel);
+// // VoipResult handling omitted here.
+// voip_base.StopSend(channel);
+// voip_base.StopPlayout(channel);
+// voip_base.ReleaseChannel(channel);
//
-// Current VoipEngine defines three sub-API classes and is subject to expand in
-// near future.
class VoipEngine {
public:
virtual ~VoipEngine() = default;
diff --git a/api/voip/voip_network.h b/api/voip/voip_network.h
index c49c769..c820ca0 100644
--- a/api/voip/voip_network.h
+++ b/api/voip/voip_network.h
@@ -18,20 +18,22 @@
// VoipNetwork interface provides any network related interfaces such as
// processing received RTP/RTCP packet from remote endpoint. This interface
-// requires a ChannelId created via VoipBase interface. Note that using invalid
-// (previously released) ChannelId will silently fail these API calls as it
-// would have released underlying audio components. It's anticipated that caller
-// may be using different thread for network I/O where released channel id is
-// still used to input incoming RTP packets in which case we should silently
-// ignore. The interface is subjected to expand as needed in near future.
+// requires a ChannelId created via VoipBase interface.
class VoipNetwork {
public:
// The data received from the network including RTP header is passed here.
- virtual void ReceivedRTPPacket(ChannelId channel_id,
- rtc::ArrayView<const uint8_t> rtp_packet) = 0;
+ // Returns following VoipResult;
+ // kOk - received RTP packet is processed.
+ // kInvalidArgument - |channel_id| is invalid.
+ virtual VoipResult ReceivedRTPPacket(
+ ChannelId channel_id,
+ rtc::ArrayView<const uint8_t> rtp_packet) = 0;
// The data received from the network including RTCP header is passed here.
- virtual void ReceivedRTCPPacket(
+ // Returns following VoipResult;
+ // kOk - received RTCP packet is processed.
+ // kInvalidArgument - |channel_id| is invalid.
+ virtual VoipResult ReceivedRTCPPacket(
ChannelId channel_id,
rtc::ArrayView<const uint8_t> rtcp_packet) = 0;
diff --git a/api/voip/voip_statistics.h b/api/voip/voip_statistics.h
index cf01e95..08f4cb7 100644
--- a/api/voip/voip_statistics.h
+++ b/api/voip/voip_statistics.h
@@ -30,10 +30,12 @@
// the jitter buffer (NetEq) performance.
class VoipStatistics {
public:
- // Gets the audio ingress statistics. Returns absl::nullopt when channel_id is
- // invalid.
- virtual absl::optional<IngressStatistics> GetIngressStatistics(
- ChannelId channel_id) = 0;
+ // Gets the audio ingress statistics by |ingress_stats| reference.
+ // Returns following VoipResult;
+ // kOk - successfully set provided IngressStatistics reference.
+ // kInvalidArgument - |channel_id| is invalid.
+ virtual VoipResult GetIngressStatistics(ChannelId channel_id,
+ IngressStatistics& ingress_stats) = 0;
protected:
virtual ~VoipStatistics() = default;
diff --git a/api/voip/voip_volume_control.h b/api/voip/voip_volume_control.h
index 54e4467..d91eabc 100644
--- a/api/voip/voip_volume_control.h
+++ b/api/voip/voip_volume_control.h
@@ -36,17 +36,24 @@
// Mute/unmutes the microphone input sample before encoding process. Note that
// mute doesn't affect audio input level and energy values as input sample is
// silenced after the measurement.
- virtual void SetInputMuted(ChannelId channel_id, bool enable) = 0;
+ // Returns following VoipResult;
+ // kOk - input source muted or unmuted as provided by |enable|.
+ // kInvalidArgument - |channel_id| is invalid.
+ virtual VoipResult SetInputMuted(ChannelId channel_id, bool enable) = 0;
- // Gets the microphone volume info.
- // Returns absl::nullopt if |channel_id| is invalid.
- virtual absl::optional<VolumeInfo> GetInputVolumeInfo(
- ChannelId channel_id) = 0;
+ // Gets the microphone volume info via |volume_info| reference.
+ // Returns following VoipResult;
+ // kOk - successfully set provided input volume info.
+ // kInvalidArgument - |channel_id| is invalid.
+ virtual VoipResult GetInputVolumeInfo(ChannelId channel_id,
+ VolumeInfo& volume_info) = 0;
- // Gets the speaker volume info.
- // Returns absl::nullopt if |channel_id| is invalid.
- virtual absl::optional<VolumeInfo> GetOutputVolumeInfo(
- ChannelId channel_id) = 0;
+ // Gets the speaker volume info via |volume_info| reference.
+ // Returns following VoipResult;
+ // kOk - successfully set provided output volume info.
+ // kInvalidArgument - |channel_id| is invalid.
+ virtual VoipResult GetOutputVolumeInfo(ChannelId channel_id,
+ VolumeInfo& volume_info) = 0;
protected:
virtual ~VoipVolumeControl() = default;
