1 /* 2 * Copyright 2019 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 P2P_BASE_ICE_CONTROLLER_INTERFACE_H_ 12 #define P2P_BASE_ICE_CONTROLLER_INTERFACE_H_ 13 14 #include <string> 15 #include <utility> 16 #include <vector> 17 18 #include "absl/types/optional.h" 19 #include "p2p/base/connection.h" 20 #include "p2p/base/ice_switch_reason.h" 21 #include "p2p/base/ice_transport_internal.h" 22 23 namespace cricket { 24 25 struct IceFieldTrials; // Forward declaration to avoid circular dependency. 26 27 struct IceRecheckEvent { IceRecheckEventIceRecheckEvent28 IceRecheckEvent(IceSwitchReason _reason, int _recheck_delay_ms) 29 : reason(_reason), recheck_delay_ms(_recheck_delay_ms) {} 30 31 std::string ToString() const; 32 33 IceSwitchReason reason; 34 int recheck_delay_ms; 35 }; 36 37 // Defines the interface for a module that control 38 // - which connection to ping 39 // - which connection to use 40 // - which connection to prune 41 // - which connection to forget learned state on 42 // 43 // The P2PTransportChannel owns (creates and destroys) Connections, 44 // but P2PTransportChannel gives const pointers to the the IceController using 45 // `AddConnection`, i.e the IceController should not call any non-const methods 46 // on a Connection but signal back in the interface if any mutable function 47 // shall be called. 48 // 49 // Current these are limited to: 50 // Connection::Ping - returned in PingResult 51 // Connection::Prune - retuned in PruneConnections 52 // Connection::ForgetLearnedState - return in SwitchResult 53 // 54 // The IceController shall keep track of all connections added 55 // (and not destroyed) and give them back using the connections()-function- 56 // 57 // When a Connection gets destroyed 58 // - signals on Connection::SignalDestroyed 59 // - P2PTransportChannel calls IceController::OnConnectionDestroyed 60 class IceControllerInterface { 61 public: 62 // This represents the result of a switch call. 63 struct SwitchResult { 64 // Connection that we should (optionally) switch to. 65 absl::optional<const Connection*> connection; 66 67 // An optional recheck event for when a Switch() should be attempted again. 68 absl::optional<IceRecheckEvent> recheck_event; 69 70 // A vector with connection to run ForgetLearnedState on. 71 std::vector<const Connection*> connections_to_forget_state_on; 72 }; 73 74 // This represents the result of a call to SelectConnectionToPing. 75 struct PingResult { PingResultPingResult76 PingResult(const Connection* conn, int _recheck_delay_ms) 77 : connection(conn ? absl::optional<const Connection*>(conn) 78 : absl::nullopt), 79 recheck_delay_ms(_recheck_delay_ms) {} 80 81 // Connection that we should (optionally) ping. 82 const absl::optional<const Connection*> connection; 83 84 // The delay before P2PTransportChannel shall call SelectConnectionToPing() 85 // again. 86 // 87 // Since the IceController determines which connection to ping and 88 // only returns one connection at a time, the recheck_delay_ms does not have 89 // any obvious implication on bitrate for pings. E.g the recheck_delay_ms 90 // will be shorter if there are more connections available. 91 const int recheck_delay_ms = 0; 92 }; 93 94 virtual ~IceControllerInterface() = default; 95 96 // These setters are called when the state of P2PTransportChannel is mutated. 97 virtual void SetIceConfig(const IceConfig& config) = 0; 98 virtual void SetSelectedConnection(const Connection* selected_connection) = 0; 99 virtual void AddConnection(const Connection* connection) = 0; 100 virtual void OnConnectionDestroyed(const Connection* connection) = 0; 101 102 // These are all connections that has been added and not destroyed. 103 virtual rtc::ArrayView<const Connection*> connections() const = 0; 104 105 // Is there a pingable connection ? 106 // This function is used to boot-strap pinging, after this returns true 107 // SelectConnectionToPing() will be called periodically. 108 virtual bool HasPingableConnection() const = 0; 109 110 // Select a connection to Ping, or nullptr if none. 111 virtual PingResult SelectConnectionToPing(int64_t last_ping_sent_ms) = 0; 112 113 // Compute the "STUN_ATTR_USE_CANDIDATE" for `conn`. 114 virtual bool GetUseCandidateAttr(const Connection* conn, 115 NominationMode mode, 116 IceMode remote_ice_mode) const = 0; 117 118 // These methods is only added to not have to change all unit tests 119 // that simulate pinging by marking a connection pinged. 120 virtual const Connection* FindNextPingableConnection() = 0; 121 virtual void MarkConnectionPinged(const Connection* con) = 0; 122 123 // Check if we should switch to `connection`. 124 // This method is called for IceSwitchReasons that can switch directly 125 // i.e without resorting. 126 virtual SwitchResult ShouldSwitchConnection(IceSwitchReason reason, 127 const Connection* connection) = 0; 128 129 // Sort connections and check if we should switch. 130 virtual SwitchResult SortAndSwitchConnection(IceSwitchReason reason) = 0; 131 132 // Prune connections. 133 virtual std::vector<const Connection*> PruneConnections() = 0; 134 }; 135 136 } // namespace cricket 137 138 #endif // P2P_BASE_ICE_CONTROLLER_INTERFACE_H_ 139