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