ice_transport_internal.h

/*

 *  Copyright 2016 The WebRTC Project Authors. All rights reserved.

 *  Use of this source code is governed by a BSD-style license

 *  that can be found in the LICENSE file in the root of the source

 *  tree. An additional intellectual property rights grant can be found

 *  in the file PATENTS.  All contributing project authors may

 *  be found in the AUTHORS file in the root of the source tree.

*/

#ifndef P2P_BASE_ICE_TRANSPORT_INTERNAL_H_

#define P2P_BASE_ICE_TRANSPORT_INTERNAL_H_

#include <stdint.h>

#include <optional>

#include <string>

#include <utility>

#include <vector>

#include "absl/strings/string_view.h"

#include "api/candidate.h"

#include "api/rtc_error.h"

#include "api/transport/enums.h"

#include "p2p/base/connection.h"

#include "p2p/base/packet_transport_internal.h"

#include "p2p/base/port.h"

#include "p2p/base/stun_dictionary.h"

#include "p2p/base/transport_description.h"

#include "rtc_base/network_constants.h"

#include "rtc_base/system/rtc_export.h"

#include "rtc_base/third_party/sigslot/sigslot.h"

#include "rtc_base/time_utils.h"

namespace cricket {

struct IceTransportStats {

  CandidateStatsList candidate_stats_list;

  ConnectionInfos connection_infos;

  // Number of times the selected candidate pair has changed

  // Initially 0 and 1 once the first candidate pair has been selected.

  // The counter is increase also when "unselecting" a connection.

  uint32_t selected_candidate_pair_changes = 0;

  // Bytes/packets sent/received.

  // note: Is not the same as sum(connection_infos.bytes_sent)

  // as connections are created and destroyed while the ICE transport

  // is alive.

  uint64_t bytes_sent = 0;

  uint64_t bytes_received = 0;

  uint64_t packets_sent = 0;

  uint64_t packets_received = 0;

  IceRole ice_role = ICEROLE_UNKNOWN;

  std::string ice_local_username_fragment;

  webrtc::IceTransportState ice_state = webrtc::IceTransportState::kNew;

};

typedef std::vector<Candidate> Candidates;

enum IceConnectionState {

  kIceConnectionConnecting = 0,

  kIceConnectionFailed,

  kIceConnectionConnected,  // Writable, but still checking one or more

                            // connections

  kIceConnectionCompleted,

};

// TODO(deadbeef): Unify with PeerConnectionInterface::IceConnectionState

// once /talk/ and /webrtc/ are combined, and also switch to ENUM_NAME naming

// style.

enum IceGatheringState {

  kIceGatheringNew = 0,

  kIceGatheringGathering,

  kIceGatheringComplete,

};

enum ContinualGatheringPolicy {

  // All port allocator sessions will stop after a writable connection is found.

  GATHER_ONCE = 0,

  // The most recent port allocator session will keep on running.

  GATHER_CONTINUALLY,

};

// ICE Nomination mode.

enum class NominationMode {

  REGULAR,         // Nominate once per ICE restart (Not implemented yet).

  AGGRESSIVE,      // Nominate every connection except that it will behave as if

                   // REGULAR when the remote is an ICE-LITE endpoint.

  SEMI_AGGRESSIVE  // Our current implementation of the nomination algorithm.

                   // The details are described in P2PTransportChannel.

};

// Utility method that checks if various required Candidate fields are filled in

// and contain valid values. If conditions are not met, an RTCError with the

// appropriated error number and description is returned. If the configuration

// is valid RTCError::OK() is returned.

webrtc::RTCError VerifyCandidate(const Candidate& cand);

// Runs through a list of cricket::Candidate instances and calls VerifyCandidate

// for each one, stopping on the first error encounted and returning that error

// value if so. On success returns RTCError::OK().

webrtc::RTCError VerifyCandidates(const Candidates& candidates);

// Information about ICE configuration.

// TODO(deadbeef): Use std::optional to represent unset values, instead of

// -1.

//

// TODO(bugs.webrtc.org/15609): Define a public API for this.

struct RTC_EXPORT IceConfig {

  // The ICE connection receiving timeout value in milliseconds.

  std::optional<int> receiving_timeout;

  // Time interval in milliseconds to ping a backup connection when the ICE

  // channel is strongly connected.

  std::optional<int> backup_connection_ping_interval;

  ContinualGatheringPolicy continual_gathering_policy = GATHER_ONCE;

  bool gather_continually() const {

    return continual_gathering_policy == GATHER_CONTINUALLY;

  // Whether we should prioritize Relay/Relay candidate when nothing

  // is writable yet.

  bool prioritize_most_likely_candidate_pairs = false;

  // Writable connections are pinged at a slower rate once stablized.

  std::optional<int> stable_writable_connection_ping_interval;

  // If set to true, this means the ICE transport should presume TURN-to-TURN

  // candidate pairs will succeed, even before a binding response is received.

  bool presume_writable_when_fully_relayed = false;

  // If true, after the ICE transport type (as the candidate filter used by the

  // port allocator) is changed such that new types of ICE candidates are

  // allowed by the new filter, e.g. from CF_RELAY to CF_ALL, candidates that

  // have been gathered by the ICE transport but filtered out and not signaled

  // to the upper layers, will be surfaced.

  bool surface_ice_candidates_on_ice_transport_type_changed = false;

  // Interval to check on all networks and to perform ICE regathering on any

  // active network having no connection on it.

  std::optional<int> regather_on_failed_networks_interval;

  // The time period in which we will not switch the selected connection

  // when a new connection becomes receiving but the selected connection is not

  // in case that the selected connection may become receiving soon.

  std::optional<int> receiving_switching_delay;

  // TODO(honghaiz): Change the default to regular nomination.

  // Default nomination mode if the remote does not support renomination.

  NominationMode default_nomination_mode = NominationMode::SEMI_AGGRESSIVE;

  // The interval in milliseconds at which ICE checks (STUN pings) will be sent

  // for a candidate pair when it is both writable and receiving (strong

  // connectivity). This parameter overrides the default value given by

  // `STRONG_PING_INTERVAL` in p2ptransport.h if set.

  std::optional<int> ice_check_interval_strong_connectivity;

  // The interval in milliseconds at which ICE checks (STUN pings) will be sent

  // for a candidate pair when it is either not writable or not receiving (weak

  // connectivity). This parameter overrides the default value given by

  // `WEAK_PING_INTERVAL` in p2ptransport.h if set.

  std::optional<int> ice_check_interval_weak_connectivity;

  // ICE checks (STUN pings) will not be sent at higher rate (lower interval)

  // than this, no matter what other settings there are.

  // Measure in milliseconds.

//

  // Note that this parameter overrides both the above check intervals for

  // candidate pairs with strong or weak connectivity, if either of the above

  // interval is shorter than the min interval.

  std::optional<int> ice_check_min_interval;

  // The min time period for which a candidate pair must wait for response to

  // connectivity checks before it becomes unwritable. This parameter

  // overrides the default value given by `CONNECTION_WRITE_CONNECT_TIMEOUT`

  // in port.h if set, when determining the writability of a candidate pair.

  std::optional<int> ice_unwritable_timeout;

  // The min number of connectivity checks that a candidate pair must sent

  // without receiving response before it becomes unwritable. This parameter

  // overrides the default value given by `CONNECTION_WRITE_CONNECT_FAILURES` in

  // port.h if set, when determining the writability of a candidate pair.

  std::optional<int> ice_unwritable_min_checks;

  // The min time period for which a candidate pair must wait for response to

  // connectivity checks it becomes inactive. This parameter overrides the

  // default value given by `CONNECTION_WRITE_TIMEOUT` in port.h if set, when

  // determining the writability of a candidate pair.

  std::optional<int> ice_inactive_timeout;

  // The interval in milliseconds at which STUN candidates will resend STUN

  // binding requests to keep NAT bindings open.

  std::optional<int> stun_keepalive_interval;

  std::optional<rtc::AdapterType> network_preference;

  webrtc::VpnPreference vpn_preference = webrtc::VpnPreference::kDefault;

  IceConfig();

  IceConfig(int receiving_timeout_ms,

            int backup_connection_ping_interval,

            ContinualGatheringPolicy gathering_policy,

            bool prioritize_most_likely_candidate_pairs,

            int stable_writable_connection_ping_interval_ms,

            bool presume_writable_when_fully_relayed,

            int regather_on_failed_networks_interval_ms,

            int receiving_switching_delay_ms);

  ~IceConfig();

  // Helper getters for parameters with implementation-specific default value.

  // By convention, parameters with default value are represented by

  // std::optional and setting a parameter to null restores its default value.

  int receiving_timeout_or_default() const;

  int backup_connection_ping_interval_or_default() const;

  int stable_writable_connection_ping_interval_or_default() const;

  int regather_on_failed_networks_interval_or_default() const;

  int receiving_switching_delay_or_default() const;

  int ice_check_interval_strong_connectivity_or_default() const;

  int ice_check_interval_weak_connectivity_or_default() const;

  int ice_check_min_interval_or_default() const;

  int ice_unwritable_timeout_or_default() const;

  int ice_unwritable_min_checks_or_default() const;

  int ice_inactive_timeout_or_default() const;

  int stun_keepalive_interval_or_default() const;

};

// TODO(zhihuang): Replace this with

// PeerConnectionInterface::IceConnectionState.

enum class IceTransportState {

  STATE_INIT,

  STATE_CONNECTING,  // Will enter this state once a connection is created

  STATE_COMPLETED,

  STATE_FAILED

};

// IceTransportInternal is an internal abstract class that does ICE.

// Once the public interface is supported,

// (https://www.w3.org/TR/webrtc/#rtcicetransport)

// the IceTransportInterface will be split from this class.

//

// TODO(bugs.webrtc.org/15609): Define a public API for this.

class RTC_EXPORT IceTransportInternal : public rtc::PacketTransportInternal {

 public:

  IceTransportInternal();

  ~IceTransportInternal() override;

  // TODO(bugs.webrtc.org/9308): Remove GetState once all uses have been

  // migrated to GetIceTransportState.

  virtual IceTransportState GetState() const = 0;

  virtual webrtc::IceTransportState GetIceTransportState() const = 0;

  virtual int component() const = 0;

  virtual IceRole GetIceRole() const = 0;

  virtual void SetIceRole(IceRole role) = 0;

  // Default implementation in order to allow downstream usage deletion.

  // TODO: bugs.webrtc.org/42224914 - Remove when all downstream overrides are

  // gone.

  virtual void SetIceTiebreaker(uint64_t tiebreaker) { RTC_CHECK_NOTREACHED(); }

  virtual void SetIceCredentials(absl::string_view ice_ufrag,

                                 absl::string_view ice_pwd);

  virtual void SetRemoteIceCredentials(absl::string_view ice_ufrag,

                                       absl::string_view ice_pwd);

  // The ufrag and pwd in `ice_params` must be set

  // before candidate gathering can start.

  virtual void SetIceParameters(const IceParameters& ice_params) = 0;

  virtual void SetRemoteIceParameters(const IceParameters& ice_params) = 0;

  virtual void SetRemoteIceMode(IceMode mode) = 0;

  virtual void SetIceConfig(const IceConfig& config) = 0;

  // Start gathering candidates if not already started, or if an ICE restart

  // occurred.

  virtual void MaybeStartGathering() = 0;

  virtual void AddRemoteCandidate(const Candidate& candidate) = 0;

  virtual void RemoveRemoteCandidate(const Candidate& candidate) = 0;

  virtual void RemoveAllRemoteCandidates() = 0;

  virtual IceGatheringState gathering_state() const = 0;

  // Returns the current stats for this connection.

  virtual bool GetStats(IceTransportStats* ice_transport_stats) = 0;

  // Returns RTT estimate over the currently active connection, or an empty

  // std::optional if there is none.

  virtual std::optional<int> GetRttEstimate() = 0;

  // TODO(qingsi): Remove this method once Chrome does not depend on it anymore.

  virtual const Connection* selected_connection() const = 0;

  // Returns the selected candidate pair, or an empty std::optional if there is

  // none.

  virtual std::optional<const CandidatePair> GetSelectedCandidatePair()

      const = 0;

  virtual std::optional<std::reference_wrapper<StunDictionaryWriter>>

  GetDictionaryWriter() {

    return std::nullopt;

  void AddGatheringStateCallback(

      const void* removal_tag,

      absl::AnyInvocable<void(IceTransportInternal*)> callback);

  void RemoveGatheringStateCallback(const void* removal_tag);

  // Handles sending and receiving of candidates.

  sigslot::signal2<IceTransportInternal*, const Candidate&>

      SignalCandidateGathered;

  void SetCandidateErrorCallback(

      absl::AnyInvocable<void(IceTransportInternal*,

                              const IceCandidateErrorEvent&)> callback) {

    RTC_DCHECK(!candidate_error_callback_);

    candidate_error_callback_ = std::move(callback);

  void SetCandidatesRemovedCallback(

      absl::AnyInvocable<void(IceTransportInternal*, const Candidates&)>

          callback) {

    RTC_DCHECK(!candidates_removed_callback_);

    candidates_removed_callback_ = std::move(callback);

  // Deprecated by PacketTransportInternal::SignalNetworkRouteChanged.

  // This signal occurs when there is a change in the way that packets are

  // being routed, i.e. to a different remote location. The candidate

  // indicates where and how we are currently sending media.

  // TODO(zhihuang): Update the Chrome remoting to use the new

  // SignalNetworkRouteChanged.

  sigslot::signal2<IceTransportInternal*, const Candidate&> SignalRouteChange;

  void SetCandidatePairChangeCallback(

      absl::AnyInvocable<void(const cricket::CandidatePairChangeEvent&)>

          callback) {

    RTC_DCHECK(!candidate_pair_change_callback_);

    candidate_pair_change_callback_ = std::move(callback);

  // Invoked when there is conflict in the ICE role between local and remote

  // agents.

  sigslot::signal1<IceTransportInternal*> SignalRoleConflict;

  // Emitted whenever the transport state changed.

  // TODO(bugs.webrtc.org/9308): Remove once all uses have migrated to the new

  // IceTransportState.

  sigslot::signal1<IceTransportInternal*> SignalStateChanged;

  // Emitted whenever the new standards-compliant transport state changed.

  sigslot::signal1<IceTransportInternal*> SignalIceTransportStateChanged;

  // Invoked when the transport is being destroyed.

  sigslot::signal1<IceTransportInternal*> SignalDestroyed;

  // Invoked when remote dictionary has been updated,

  // i.e. modifications to attributes from remote ice agent has

  // reflected in our StunDictionaryView.

  template <typename F>

  void AddDictionaryViewUpdatedCallback(const void* tag, F&& callback) {

    dictionary_view_updated_callback_list_.AddReceiver(

        tag, std::forward<F>(callback));

  void RemoveDictionaryViewUpdatedCallback(const void* tag) {

    dictionary_view_updated_callback_list_.RemoveReceivers(tag);

  // Invoked when local dictionary has been synchronized,

  // i.e. remote ice agent has reported acknowledged updates from us.

  template <typename F>

  void AddDictionaryWriterSyncedCallback(const void* tag, F&& callback) {

    dictionary_writer_synced_callback_list_.AddReceiver(

        tag, std::forward<F>(callback));

  void RemoveDictionaryWriterSyncedCallback(const void* tag) {

    dictionary_writer_synced_callback_list_.RemoveReceivers(tag);

 protected:

  void SendGatheringStateEvent() {

    gathering_state_callback_list_.Send(this);

  webrtc::CallbackList<IceTransportInternal*,

                       const StunDictionaryView&,

                       rtc::ArrayView<uint16_t>>

      dictionary_view_updated_callback_list_;

  webrtc::CallbackList<IceTransportInternal*, const StunDictionaryWriter&>

      dictionary_writer_synced_callback_list_;

  webrtc::CallbackList<IceTransportInternal*> gathering_state_callback_list_;

  absl::AnyInvocable<void(IceTransportInternal*, const IceCandidateErrorEvent&)>

      candidate_error_callback_;

  absl::AnyInvocable<void(IceTransportInternal*, const Candidates&)>

      candidates_removed_callback_;

  absl::AnyInvocable<void(const cricket::CandidatePairChangeEvent&)>

      candidate_pair_change_callback_;

};

}  // namespace cricket

#endif  // P2P_BASE_ICE_TRANSPORT_INTERNAL_H_

Source code

Revision control

Copy as Markdown

Other Tools