1 /* 2 * Copyright 2004 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_CANDIDATE_H_ 12 #define API_CANDIDATE_H_ 13 14 #include <limits.h> 15 #include <stdint.h> 16 17 #include <algorithm> 18 #include <string> 19 20 #include "absl/strings/string_view.h" 21 #include "rtc_base/checks.h" 22 #include "rtc_base/network_constants.h" 23 #include "rtc_base/socket_address.h" 24 #include "rtc_base/system/rtc_export.h" 25 26 namespace cricket { 27 28 // TURN servers are limited to 32 in accordance with 29 // https://w3c.github.io/webrtc-pc/#dom-rtcconfiguration-iceservers 30 static constexpr size_t kMaxTurnServers = 32; 31 32 // Candidate for ICE based connection discovery. 33 // TODO(phoglund): remove things in here that are not needed in the public API. 34 35 class RTC_EXPORT Candidate { 36 public: 37 Candidate(); 38 // TODO(pthatcher): Match the ordering and param list as per RFC 5245 39 // candidate-attribute syntax. http://tools.ietf.org/html/rfc5245#section-15.1 40 Candidate(int component, 41 absl::string_view protocol, 42 const rtc::SocketAddress& address, 43 uint32_t priority, 44 absl::string_view username, 45 absl::string_view password, 46 absl::string_view type, 47 uint32_t generation, 48 absl::string_view foundation, 49 uint16_t network_id = 0, 50 uint16_t network_cost = 0); 51 Candidate(const Candidate&); 52 ~Candidate(); 53 id()54 const std::string& id() const { return id_; } set_id(absl::string_view id)55 void set_id(absl::string_view id) { Assign(id_, id); } 56 component()57 int component() const { return component_; } set_component(int component)58 void set_component(int component) { component_ = component; } 59 protocol()60 const std::string& protocol() const { return protocol_; } set_protocol(absl::string_view protocol)61 void set_protocol(absl::string_view protocol) { Assign(protocol_, protocol); } 62 63 // The protocol used to talk to relay. relay_protocol()64 const std::string& relay_protocol() const { return relay_protocol_; } set_relay_protocol(absl::string_view protocol)65 void set_relay_protocol(absl::string_view protocol) { 66 Assign(relay_protocol_, protocol); 67 } 68 address()69 const rtc::SocketAddress& address() const { return address_; } set_address(const rtc::SocketAddress & address)70 void set_address(const rtc::SocketAddress& address) { address_ = address; } 71 priority()72 uint32_t priority() const { return priority_; } set_priority(const uint32_t priority)73 void set_priority(const uint32_t priority) { priority_ = priority; } 74 75 // TODO(pthatcher): Remove once Chromium's jingle/glue/utils.cc 76 // doesn't use it. 77 // Maps old preference (which was 0.0-1.0) to match priority (which 78 // is 0-2^32-1) to to match RFC 5245, section 4.1.2.1. Also see 79 // https://docs.google.com/a/google.com/document/d/ 80 // 1iNQDiwDKMh0NQOrCqbj3DKKRT0Dn5_5UJYhmZO-t7Uc/edit preference()81 float preference() const { 82 // The preference value is clamped to two decimal precision. 83 return static_cast<float>(((priority_ >> 24) * 100 / 127) / 100.0); 84 } 85 86 // TODO(pthatcher): Remove once Chromium's jingle/glue/utils.cc 87 // doesn't use it. set_preference(float preference)88 void set_preference(float preference) { 89 // Limiting priority to UINT_MAX when value exceeds uint32_t max. 90 // This can happen for e.g. when preference = 3. 91 uint64_t prio_val = static_cast<uint64_t>(preference * 127) << 24; 92 priority_ = static_cast<uint32_t>( 93 std::min(prio_val, static_cast<uint64_t>(UINT_MAX))); 94 } 95 96 // TODO(honghaiz): Change to usernameFragment or ufrag. username()97 const std::string& username() const { return username_; } set_username(absl::string_view username)98 void set_username(absl::string_view username) { Assign(username_, username); } 99 password()100 const std::string& password() const { return password_; } set_password(absl::string_view password)101 void set_password(absl::string_view password) { Assign(password_, password); } 102 type()103 const std::string& type() const { return type_; } set_type(absl::string_view type)104 void set_type(absl::string_view type) { Assign(type_, type); } 105 network_name()106 const std::string& network_name() const { return network_name_; } set_network_name(absl::string_view network_name)107 void set_network_name(absl::string_view network_name) { 108 Assign(network_name_, network_name); 109 } 110 network_type()111 rtc::AdapterType network_type() const { return network_type_; } set_network_type(rtc::AdapterType network_type)112 void set_network_type(rtc::AdapterType network_type) { 113 network_type_ = network_type; 114 } 115 underlying_type_for_vpn()116 rtc::AdapterType underlying_type_for_vpn() const { 117 return underlying_type_for_vpn_; 118 } set_underlying_type_for_vpn(rtc::AdapterType network_type)119 void set_underlying_type_for_vpn(rtc::AdapterType network_type) { 120 underlying_type_for_vpn_ = network_type; 121 } 122 123 // Candidates in a new generation replace those in the old generation. generation()124 uint32_t generation() const { return generation_; } set_generation(uint32_t generation)125 void set_generation(uint32_t generation) { generation_ = generation; } 126 127 // `network_cost` measures the cost/penalty of using this candidate. A network 128 // cost of 0 indicates this candidate can be used freely. A value of 129 // rtc::kNetworkCostMax indicates it should be used only as the last resort. set_network_cost(uint16_t network_cost)130 void set_network_cost(uint16_t network_cost) { 131 RTC_DCHECK_LE(network_cost, rtc::kNetworkCostMax); 132 network_cost_ = network_cost; 133 } network_cost()134 uint16_t network_cost() const { return network_cost_; } 135 136 // An ID assigned to the network hosting the candidate. network_id()137 uint16_t network_id() const { return network_id_; } set_network_id(uint16_t network_id)138 void set_network_id(uint16_t network_id) { network_id_ = network_id; } 139 foundation()140 const std::string& foundation() const { return foundation_; } set_foundation(absl::string_view foundation)141 void set_foundation(absl::string_view foundation) { 142 Assign(foundation_, foundation); 143 } 144 related_address()145 const rtc::SocketAddress& related_address() const { return related_address_; } set_related_address(const rtc::SocketAddress & related_address)146 void set_related_address(const rtc::SocketAddress& related_address) { 147 related_address_ = related_address; 148 } tcptype()149 const std::string& tcptype() const { return tcptype_; } set_tcptype(absl::string_view tcptype)150 void set_tcptype(absl::string_view tcptype) { Assign(tcptype_, tcptype); } 151 152 // The name of the transport channel of this candidate. 153 // TODO(phoglund): remove. transport_name()154 const std::string& transport_name() const { return transport_name_; } set_transport_name(absl::string_view transport_name)155 void set_transport_name(absl::string_view transport_name) { 156 Assign(transport_name_, transport_name); 157 } 158 159 // The URL of the ICE server which this candidate is gathered from. url()160 const std::string& url() const { return url_; } set_url(absl::string_view url)161 void set_url(absl::string_view url) { Assign(url_, url); } 162 163 // Determines whether this candidate is equivalent to the given one. 164 bool IsEquivalent(const Candidate& c) const; 165 166 // Determines whether this candidate can be considered equivalent to the 167 // given one when looking for a matching candidate to remove. 168 bool MatchesForRemoval(const Candidate& c) const; 169 ToString()170 std::string ToString() const { return ToStringInternal(false); } 171 ToSensitiveString()172 std::string ToSensitiveString() const { return ToStringInternal(true); } 173 174 uint32_t GetPriority(uint32_t type_preference, 175 int network_adapter_preference, 176 int relay_preference) const; 177 178 bool operator==(const Candidate& o) const; 179 bool operator!=(const Candidate& o) const; 180 181 // Returns a sanitized copy configured by the given booleans. If 182 // `use_host_address` is true, the returned copy has its IP removed from 183 // `address()`, which leads `address()` to be a hostname address. If 184 // `filter_related_address`, the returned copy has its related address reset 185 // to the wildcard address (i.e. 0.0.0.0 for IPv4 and :: for IPv6). Note that 186 // setting both booleans to false returns an identical copy to the original 187 // candidate. 188 Candidate ToSanitizedCopy(bool use_hostname_address, 189 bool filter_related_address) const; 190 191 private: 192 // TODO(bugs.webrtc.org/13220): With C++17, we get a std::string assignment 193 // operator accepting any object implicitly convertible to std::string_view, 194 // and then we don't need this workaround. 195 static void Assign(std::string& s, absl::string_view view); 196 std::string ToStringInternal(bool sensitive) const; 197 198 std::string id_; 199 int component_; 200 std::string protocol_; 201 std::string relay_protocol_; 202 rtc::SocketAddress address_; 203 uint32_t priority_; 204 std::string username_; 205 std::string password_; 206 std::string type_; 207 std::string network_name_; 208 rtc::AdapterType network_type_; 209 rtc::AdapterType underlying_type_for_vpn_; 210 uint32_t generation_; 211 std::string foundation_; 212 rtc::SocketAddress related_address_; 213 std::string tcptype_; 214 std::string transport_name_; 215 uint16_t network_id_; 216 uint16_t network_cost_; 217 std::string url_; 218 }; 219 220 } // namespace cricket 221 222 #endif // API_CANDIDATE_H_ 223