1 /* 2 * Copyright (c) 2020 The WebRTC project authors. All Rights Reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 11 #ifndef API_VOIP_VOIP_BASE_H_ 12 #define API_VOIP_VOIP_BASE_H_ 13 14 #include "absl/base/attributes.h" 15 #include "absl/types/optional.h" 16 17 namespace webrtc { 18 19 class Transport; 20 21 // VoipBase interface 22 // 23 // VoipBase provides a management interface on a media session using a 24 // concept called 'channel'. A channel represents an interface handle 25 // for application to request various media session operations. This 26 // notion of channel is used throughout other interfaces as well. 27 // 28 // Underneath the interface, a channel id is mapped into an audio session 29 // object that is capable of sending and receiving a single RTP stream with 30 // another media endpoint. It's possible to create and use multiple active 31 // channels simultaneously which would mean that particular application 32 // session has RTP streams with multiple remote endpoints. 33 // 34 // A typical example for the usage context is outlined in VoipEngine 35 // header file. 36 37 enum class ChannelId : int {}; 38 39 enum class ABSL_MUST_USE_RESULT VoipResult { 40 // kOk indicates the function was successfully invoked with no error. 41 kOk, 42 // kInvalidArgument indicates the caller specified an invalid argument, such 43 // as an invalid ChannelId. 44 kInvalidArgument, 45 // kFailedPrecondition indicates that the operation was failed due to not 46 // satisfying prerequisite such as not setting codec type before sending. 47 kFailedPrecondition, 48 // kInternal is used to indicate various internal failures that are not the 49 // caller's fault. Further detail is commented on each function that uses this 50 // return value. 51 kInternal, 52 }; 53 54 class VoipBase { 55 public: 56 // Creates a channel. 57 // Each channel handle maps into one audio media session where each has 58 // its own separate module for send/receive rtp packet with one peer. 59 // Caller must set `transport`, webrtc::Transport callback pointer to 60 // receive rtp/rtcp packets from corresponding media session in VoIP engine. 61 // VoipEngine framework expects applications to handle network I/O directly 62 // and injection for incoming RTP from remote endpoint is handled via 63 // VoipNetwork interface. `local_ssrc` is optional and when local_ssrc is not 64 // set, some random value will be used by voip engine. 65 // Returns a ChannelId created for caller to handle subsequent Channel 66 // operations. 67 virtual ChannelId CreateChannel(Transport* transport, 68 absl::optional<uint32_t> local_ssrc) = 0; 69 70 // Releases `channel_id` that no longer has any use. 71 // Returns following VoipResult; 72 // kOk - `channel_id` is released. 73 // kInvalidArgument - `channel_id` is invalid. 74 // kInternal - Fails to stop audio output device. 75 virtual VoipResult ReleaseChannel(ChannelId channel_id) = 0; 76 77 // Starts sending on `channel_id`. This starts microphone if not started yet. 78 // Returns following VoipResult; 79 // kOk - Channel successfully started to send. 80 // kInvalidArgument - `channel_id` is invalid. 81 // kFailedPrecondition - Missing prerequisite on VoipCodec::SetSendCodec. 82 // kInternal - initialization has failed on selected microphone. 83 virtual VoipResult StartSend(ChannelId channel_id) = 0; 84 85 // Stops sending on `channel_id`. If this is the last active channel, it will 86 // stop microphone input from underlying audio platform layer. 87 // Returns following VoipResult; 88 // kOk - Channel successfully stopped to send. 89 // kInvalidArgument - `channel_id` is invalid. 90 // kInternal - Failed to stop the active microphone device. 91 virtual VoipResult StopSend(ChannelId channel_id) = 0; 92 93 // Starts playing on speaker device for `channel_id`. 94 // This will start underlying platform speaker device if not started. 95 // Returns following VoipResult; 96 // kOk - Channel successfully started to play out. 97 // kInvalidArgument - `channel_id` is invalid. 98 // kFailedPrecondition - Missing prerequisite on VoipCodec::SetReceiveCodecs. 99 // kInternal - Failed to initializate the selected speaker device. 100 virtual VoipResult StartPlayout(ChannelId channel_id) = 0; 101 102 // Stops playing on speaker device for `channel_id`. 103 // Returns following VoipResult; 104 // kOk - Channel successfully stopped t play out. 105 // kInvalidArgument - `channel_id` is invalid. 106 virtual VoipResult StopPlayout(ChannelId channel_id) = 0; 107 108 protected: 109 virtual ~VoipBase() = default; 110 }; 111 112 } // namespace webrtc 113 114 #endif // API_VOIP_VOIP_BASE_H_ 115