blob: d5dc29e78267b61ee34b893d00582c8fdbdbaeba [file] [log] [blame]
Jonas Oreland09c452e2019-11-20 08:01:021/*
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
21namespace cricket {
22
23struct IceFieldTrials; // Forward declaration to avoid circular dependency.
24
25struct 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 Orelandb5aa0a82019-12-03 08:59:1135 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 Oreland09c452e2019-11-20 08:01:0240 };
41
42 IceControllerEvent(const Type& _type) // NOLINT: runtime/explicit
43 : type(_type) {}
44 std::string ToString() const;
45
46 Type type;
Jonas Orelandb5aa0a82019-12-03 08:59:1147 int recheck_delay_ms = 0;
Jonas Oreland09c452e2019-11-20 08:01:0248};
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 Oreland49864b72020-06-05 12:55:3554// - which connection to forget learned state on
Jonas Oreland09c452e2019-11-20 08:01:0255//
Jonas Oreland49864b72020-06-05 12:55:3556// 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 Oreland09c452e2019-11-20 08:01:0261//
Jonas Oreland49864b72020-06-05 12:55:3562// 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 Oreland09c452e2019-11-20 08:01:0268// (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
73class 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 Orelandb5aa0a82019-12-03 08:59:1180 // An optional recheck event for when a Switch() should be attempted again.
81 absl::optional<IceControllerEvent> recheck_event;
Jonas Oreland49864b72020-06-05 12:55:3582
83 // A vector with connection to run ForgetLearnedState on.
84 std::vector<const Connection*> connections_to_forget_state_on;
Jonas Oreland09c452e2019-11-20 08:01:0285 };
86
Jonas Oreland43336002020-03-26 19:59:0387 // 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 Oreland43336002020-03-26 19:59:0392 // Connection that we should (optionally) ping.
93 const absl::optional<const Connection*> connection;
94
Jonas Orelandfa097a22020-03-27 14:12:5295 // 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 Oreland43336002020-03-26 19:59:03102 const int recheck_delay_ms = 0;
103 };
Jonas Oreland2f3c0192020-03-26 11:59:44104
Jonas Oreland09c452e2019-11-20 08:01:02105 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 Oreland2f3c0192020-03-26 11:59:44122 virtual PingResult SelectConnectionToPing(int64_t last_ping_sent_ms) = 0;
Jonas Oreland09c452e2019-11-20 08:01:02123
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_