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