1 /* 2 * Copyright (c) 2018 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_TRANSPORT_NETWORK_CONTROL_H_ 12 #define API_TRANSPORT_NETWORK_CONTROL_H_ 13 #include <stdint.h> 14 15 #include <memory> 16 17 #include "absl/base/attributes.h" 18 #include "api/field_trials_view.h" 19 #include "api/rtc_event_log/rtc_event_log.h" 20 #include "api/transport/network_types.h" 21 22 namespace webrtc { 23 24 class TargetTransferRateObserver { 25 public: 26 virtual ~TargetTransferRateObserver() = default; 27 // Called to indicate target transfer rate as well as giving information about 28 // the current estimate of network parameters. 29 virtual void OnTargetTransferRate(TargetTransferRate) = 0; 30 // Called to provide updates to the expected target rate in case it changes 31 // before the first call to OnTargetTransferRate. OnStartRateUpdate(DataRate)32 virtual void OnStartRateUpdate(DataRate) {} 33 }; 34 35 // Configuration sent to factory create function. The parameters here are 36 // optional to use for a network controller implementation. 37 struct NetworkControllerConfig { 38 // The initial constraints to start with, these can be changed at any later 39 // time by calls to OnTargetRateConstraints. Note that the starting rate 40 // has to be set initially to provide a starting state for the network 41 // controller, even though the field is marked as optional. 42 TargetRateConstraints constraints; 43 // Initial stream specific configuration, these are changed at any later time 44 // by calls to OnStreamsConfig. 45 StreamsConfig stream_based_config; 46 47 // Optional override of configuration of WebRTC internals. Using nullptr here 48 // indicates that the field trial API will be used. 49 const FieldTrialsView* key_value_config = nullptr; 50 // Optional override of event log. 51 RtcEventLog* event_log = nullptr; 52 }; 53 54 // NetworkControllerInterface is implemented by network controllers. A network 55 // controller is a class that uses information about network state and traffic 56 // to estimate network parameters such as round trip time and bandwidth. Network 57 // controllers does not guarantee thread safety, the interface must be used in a 58 // non-concurrent fashion. 59 class NetworkControllerInterface { 60 public: 61 virtual ~NetworkControllerInterface() = default; 62 63 // Called when network availabilty changes. 64 ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnNetworkAvailability( 65 NetworkAvailability) = 0; 66 // Called when the receiving or sending endpoint changes address. 67 ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnNetworkRouteChange( 68 NetworkRouteChange) = 0; 69 // Called periodically with a periodicy as specified by 70 // NetworkControllerFactoryInterface::GetProcessInterval. 71 ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnProcessInterval( 72 ProcessInterval) = 0; 73 // Called when remotely calculated bitrate is received. 74 ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnRemoteBitrateReport( 75 RemoteBitrateReport) = 0; 76 // Called round trip time has been calculated by protocol specific mechanisms. 77 ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnRoundTripTimeUpdate( 78 RoundTripTimeUpdate) = 0; 79 // Called when a packet is sent on the network. 80 ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnSentPacket( 81 SentPacket) = 0; 82 // Called when a packet is received from the remote client. 83 ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnReceivedPacket( 84 ReceivedPacket) = 0; 85 // Called when the stream specific configuration has been updated. 86 ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnStreamsConfig( 87 StreamsConfig) = 0; 88 // Called when target transfer rate constraints has been changed. 89 ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnTargetRateConstraints( 90 TargetRateConstraints) = 0; 91 // Called when a protocol specific calculation of packet loss has been made. 92 ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnTransportLossReport( 93 TransportLossReport) = 0; 94 // Called with per packet feedback regarding receive time. 95 ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnTransportPacketsFeedback( 96 TransportPacketsFeedback) = 0; 97 // Called with network state estimate updates. 98 ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnNetworkStateEstimate( 99 NetworkStateEstimate) = 0; 100 }; 101 102 // NetworkControllerFactoryInterface is an interface for creating a network 103 // controller. 104 class NetworkControllerFactoryInterface { 105 public: 106 virtual ~NetworkControllerFactoryInterface() = default; 107 108 // Used to create a new network controller, requires an observer to be 109 // provided to handle callbacks. 110 virtual std::unique_ptr<NetworkControllerInterface> Create( 111 NetworkControllerConfig config) = 0; 112 // Returns the interval by which the network controller expects 113 // OnProcessInterval calls. 114 virtual TimeDelta GetProcessInterval() const = 0; 115 }; 116 117 // Under development, subject to change without notice. 118 class NetworkStateEstimator { 119 public: 120 // Gets the current best estimate according to the estimator. 121 virtual absl::optional<NetworkStateEstimate> GetCurrentEstimate() = 0; 122 // Called with per packet feedback regarding receive time. 123 // Used when the NetworkStateEstimator runs in the sending endpoint. 124 virtual void OnTransportPacketsFeedback(const TransportPacketsFeedback&) = 0; 125 // Called with per packet feedback regarding receive time. 126 // Used when the NetworkStateEstimator runs in the receiving endpoint. OnReceivedPacket(const PacketResult &)127 virtual void OnReceivedPacket(const PacketResult&) {} 128 // Called when the receiving or sending endpoint changes address. 129 virtual void OnRouteChange(const NetworkRouteChange&) = 0; 130 virtual ~NetworkStateEstimator() = default; 131 }; 132 class NetworkStateEstimatorFactory { 133 public: 134 virtual std::unique_ptr<NetworkStateEstimator> Create( 135 const FieldTrialsView* key_value_config) = 0; 136 virtual ~NetworkStateEstimatorFactory() = default; 137 }; 138 } // namespace webrtc 139 140 #endif // API_TRANSPORT_NETWORK_CONTROL_H_ 141