3 * Copyright 2004--2005, Google Inc.
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
8 * 1. Redistributions of source code must retain the above copyright notice,
9 * this list of conditions and the following disclaimer.
10 * 2. Redistributions in binary form must reproduce the above copyright notice,
11 * this list of conditions and the following disclaimer in the documentation
12 * and/or other materials provided with the distribution.
13 * 3. The name of the author may not be used to endorse or promote products
14 * derived from this software without specific prior written permission.
16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
17 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
18 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
19 * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
20 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
22 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
23 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
24 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
25 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28 #ifndef TALK_P2P_BASE_PORT_H_
29 #define TALK_P2P_BASE_PORT_H_
36 #include "talk/p2p/base/candidate.h"
37 #include "talk/p2p/base/packetsocketfactory.h"
38 #include "talk/p2p/base/portinterface.h"
39 #include "talk/p2p/base/stun.h"
40 #include "talk/p2p/base/stunrequest.h"
41 #include "talk/p2p/base/transport.h"
42 #include "webrtc/base/asyncpacketsocket.h"
43 #include "webrtc/base/network.h"
44 #include "webrtc/base/proxyinfo.h"
45 #include "webrtc/base/ratetracker.h"
46 #include "webrtc/base/sigslot.h"
47 #include "webrtc/base/socketaddress.h"
48 #include "webrtc/base/thread.h"
53 class ConnectionRequest;
55 extern const char LOCAL_PORT_TYPE[];
56 extern const char STUN_PORT_TYPE[];
57 extern const char PRFLX_PORT_TYPE[];
58 extern const char RELAY_PORT_TYPE[];
60 extern const char UDP_PROTOCOL_NAME[];
61 extern const char TCP_PROTOCOL_NAME[];
62 extern const char SSLTCP_PROTOCOL_NAME[];
64 // RFC 6544, TCP candidate encoding rules.
65 extern const int DISCARD_PORT;
66 extern const char TCPTYPE_ACTIVE_STR[];
67 extern const char TCPTYPE_PASSIVE_STR[];
68 extern const char TCPTYPE_SIMOPEN_STR[];
70 // The length of time we wait before timing out readability on a connection.
71 const uint32 CONNECTION_READ_TIMEOUT = 30 * 1000; // 30 seconds
73 // The length of time we wait before timing out writability on a connection.
74 const uint32 CONNECTION_WRITE_TIMEOUT = 15 * 1000; // 15 seconds
76 // The length of time we wait before we become unwritable.
77 const uint32 CONNECTION_WRITE_CONNECT_TIMEOUT = 5 * 1000; // 5 seconds
79 // The number of pings that must fail to respond before we become unwritable.
80 const uint32 CONNECTION_WRITE_CONNECT_FAILURES = 5;
82 // This is the length of time that we wait for a ping response to come back.
83 const int CONNECTION_RESPONSE_TIMEOUT = 5 * 1000; // 5 seconds
86 RELAY_GTURN, // Legacy google relay service.
87 RELAY_TURN // Standard (TURN) relay service.
90 enum IcePriorityValue {
91 // The reason we are choosing Relay preference 2 is because, we can run
92 // Relay from client to server on UDP/TCP/TLS. To distinguish the transport
93 // protocol, we prefer UDP over TCP over TLS.
94 // For UDP ICE_TYPE_PREFERENCE_RELAY will be 2.
95 // For TCP ICE_TYPE_PREFERENCE_RELAY will be 1.
96 // For TLS ICE_TYPE_PREFERENCE_RELAY will be 0.
97 // Check turnport.cc for setting these values.
98 ICE_TYPE_PREFERENCE_RELAY = 2,
99 ICE_TYPE_PREFERENCE_HOST_TCP = 90,
100 ICE_TYPE_PREFERENCE_SRFLX = 100,
101 ICE_TYPE_PREFERENCE_PRFLX = 110,
102 ICE_TYPE_PREFERENCE_HOST = 126
105 const char* ProtoToString(ProtocolType proto);
106 bool StringToProto(const char* value, ProtocolType* proto);
108 struct ProtocolAddress {
109 rtc::SocketAddress address;
113 ProtocolAddress(const rtc::SocketAddress& a, ProtocolType p)
114 : address(a), proto(p), secure(false) { }
115 ProtocolAddress(const rtc::SocketAddress& a, ProtocolType p, bool sec)
116 : address(a), proto(p), secure(sec) { }
119 typedef std::set<rtc::SocketAddress> ServerAddresses;
121 // Represents a local communication mechanism that can be used to create
122 // connections to similar mechanisms of the other client. Subclasses of this
123 // one add support for specific mechanisms like local UDP ports.
124 class Port : public PortInterface, public rtc::MessageHandler,
125 public sigslot::has_slots<> {
127 Port(rtc::Thread* thread, rtc::PacketSocketFactory* factory,
128 rtc::Network* network, const rtc::IPAddress& ip,
129 const std::string& username_fragment, const std::string& password);
130 Port(rtc::Thread* thread, const std::string& type,
131 rtc::PacketSocketFactory* factory,
132 rtc::Network* network, const rtc::IPAddress& ip,
133 int min_port, int max_port, const std::string& username_fragment,
134 const std::string& password);
137 virtual const std::string& Type() const { return type_; }
138 virtual rtc::Network* Network() const { return network_; }
140 // This method will set the flag which enables standard ICE/STUN procedures
141 // in STUN connectivity checks. Currently this method does
142 // 1. Add / Verify MI attribute in STUN binding requests.
143 // 2. Username attribute in STUN binding request will be RFRAF:LFRAG,
144 // as opposed to RFRAGLFRAG.
145 virtual void SetIceProtocolType(IceProtocolType protocol) {
146 ice_protocol_ = protocol;
148 virtual IceProtocolType IceProtocol() const { return ice_protocol_; }
150 // Methods to set/get ICE role and tiebreaker values.
151 IceRole GetIceRole() const { return ice_role_; }
152 void SetIceRole(IceRole role) { ice_role_ = role; }
154 void SetIceTiebreaker(uint64 tiebreaker) { tiebreaker_ = tiebreaker; }
155 uint64 IceTiebreaker() const { return tiebreaker_; }
157 virtual bool SharedSocket() const { return shared_socket_; }
158 void ResetSharedSocket() { shared_socket_ = false; }
160 // The thread on which this port performs its I/O.
161 rtc::Thread* thread() { return thread_; }
163 // The factory used to create the sockets of this port.
164 rtc::PacketSocketFactory* socket_factory() const { return factory_; }
165 void set_socket_factory(rtc::PacketSocketFactory* factory) {
169 // For debugging purposes.
170 const std::string& content_name() const { return content_name_; }
171 void set_content_name(const std::string& content_name) {
172 content_name_ = content_name;
175 int component() const { return component_; }
176 void set_component(int component) { component_ = component; }
178 bool send_retransmit_count_attribute() const {
179 return send_retransmit_count_attribute_;
181 void set_send_retransmit_count_attribute(bool enable) {
182 send_retransmit_count_attribute_ = enable;
185 // Identifies the generation that this port was created in.
186 uint32 generation() { return generation_; }
187 void set_generation(uint32 generation) { generation_ = generation; }
189 // ICE requires a single username/password per content/media line. So the
190 // |ice_username_fragment_| of the ports that belongs to the same content will
191 // be the same. However this causes a small complication with our relay
192 // server, which expects different username for RTP and RTCP.
194 // To resolve this problem, we implemented the username_fragment(),
195 // which returns a different username (calculated from
196 // |ice_username_fragment_|) for RTCP in the case of ICEPROTO_GOOGLE. And the
197 // username_fragment() simply returns |ice_username_fragment_| when running
198 // in ICEPROTO_RFC5245.
200 // As a result the ICEPROTO_GOOGLE will use different usernames for RTP and
201 // RTCP. And the ICEPROTO_RFC5245 will use same username for both RTP and
203 const std::string username_fragment() const;
204 const std::string& password() const { return password_; }
206 // Fired when candidates are discovered by the port. When all candidates
207 // are discovered that belong to port SignalAddressReady is fired.
208 sigslot::signal2<Port*, const Candidate&> SignalCandidateReady;
210 // Provides all of the above information in one handy object.
211 virtual const std::vector<Candidate>& Candidates() const {
215 // SignalPortComplete is sent when port completes the task of candidates
217 sigslot::signal1<Port*> SignalPortComplete;
218 // This signal sent when port fails to allocate candidates and this port
219 // can't be used in establishing the connections. When port is in shared mode
220 // and port fails to allocate one of the candidates, port shouldn't send
221 // this signal as other candidates might be usefull in establishing the
223 sigslot::signal1<Port*> SignalPortError;
225 // Returns a map containing all of the connections of this port, keyed by the
227 typedef std::map<rtc::SocketAddress, Connection*> AddressMap;
228 const AddressMap& connections() { return connections_; }
230 // Returns the connection to the given address or NULL if none exists.
231 virtual Connection* GetConnection(
232 const rtc::SocketAddress& remote_addr);
234 // Called each time a connection is created.
235 sigslot::signal2<Port*, Connection*> SignalConnectionCreated;
237 // In a shared socket mode each port which shares the socket will decide
238 // to accept the packet based on the |remote_addr|. Currently only UDP
239 // port implemented this method.
240 // TODO(mallinath) - Make it pure virtual.
241 virtual bool HandleIncomingPacket(
242 rtc::AsyncPacketSocket* socket, const char* data, size_t size,
243 const rtc::SocketAddress& remote_addr,
244 const rtc::PacketTime& packet_time) {
249 // Sends a response message (normal or error) to the given request. One of
250 // these methods should be called as a response to SignalUnknownAddress.
251 // NOTE: You MUST call CreateConnection BEFORE SendBindingResponse.
252 virtual void SendBindingResponse(StunMessage* request,
253 const rtc::SocketAddress& addr);
254 virtual void SendBindingErrorResponse(
255 StunMessage* request, const rtc::SocketAddress& addr,
256 int error_code, const std::string& reason);
258 void set_proxy(const std::string& user_agent,
259 const rtc::ProxyInfo& proxy) {
260 user_agent_ = user_agent;
263 const std::string& user_agent() { return user_agent_; }
264 const rtc::ProxyInfo& proxy() { return proxy_; }
266 virtual void EnablePortPackets();
268 // Called if the port has no connections and is no longer useful.
271 virtual void OnMessage(rtc::Message *pmsg);
273 // Debugging description of this port
274 virtual std::string ToString() const;
275 rtc::IPAddress& ip() { return ip_; }
276 int min_port() { return min_port_; }
277 int max_port() { return max_port_; }
279 // Timeout shortening function to speed up unit tests.
280 void set_timeout_delay(int delay) { timeout_delay_ = delay; }
282 // This method will return local and remote username fragements from the
283 // stun username attribute if present.
284 bool ParseStunUsername(const StunMessage* stun_msg,
285 std::string* local_username,
286 std::string* remote_username,
287 IceProtocolType* remote_protocol_type) const;
288 void CreateStunUsername(const std::string& remote_username,
289 std::string* stun_username_attr_str) const;
291 bool MaybeIceRoleConflict(const rtc::SocketAddress& addr,
292 IceMessage* stun_msg,
293 const std::string& remote_ufrag);
295 // Called when the socket is currently able to send.
296 void OnReadyToSend();
298 // Called when the Connection discovers a local peer reflexive candidate.
299 // Returns the index of the new local candidate.
300 size_t AddPrflxCandidate(const Candidate& local);
302 // Returns if RFC 5245 ICE protocol is used.
303 bool IsStandardIce() const;
305 // Returns if Google ICE protocol is used.
306 bool IsGoogleIce() const;
308 // Returns if Hybrid ICE protocol is used.
309 bool IsHybridIce() const;
313 MSG_CHECKTIMEOUT = 0,
317 void set_type(const std::string& type) { type_ = type; }
319 void AddAddress(const rtc::SocketAddress& address,
320 const rtc::SocketAddress& base_address,
321 const rtc::SocketAddress& related_address,
322 const std::string& protocol, const std::string& tcptype,
323 const std::string& type, uint32 type_preference,
324 uint32 relay_preference, bool final);
326 // Adds the given connection to the list. (Deleting removes them.)
327 void AddConnection(Connection* conn);
329 // Called when a packet is received from an unknown address that is not
330 // currently a connection. If this is an authenticated STUN binding request,
331 // then we will signal the client.
332 void OnReadPacket(const char* data, size_t size,
333 const rtc::SocketAddress& addr,
336 // If the given data comprises a complete and correct STUN message then the
337 // return value is true, otherwise false. If the message username corresponds
338 // with this port's username fragment, msg will contain the parsed STUN
339 // message. Otherwise, the function may send a STUN response internally.
340 // remote_username contains the remote fragment of the STUN username.
341 bool GetStunMessage(const char* data, size_t size,
342 const rtc::SocketAddress& addr,
343 IceMessage** out_msg, std::string* out_username);
345 // Checks if the address in addr is compatible with the port's ip.
346 bool IsCompatibleAddress(const rtc::SocketAddress& addr);
348 // Returns default DSCP value.
349 rtc::DiffServCodePoint DefaultDscpValue() const {
350 // No change from what MediaChannel set.
351 return rtc::DSCP_NO_CHANGE;
356 // Called when one of our connections deletes itself.
357 void OnConnectionDestroyed(Connection* conn);
359 // Checks if this port is useless, and hence, should be destroyed.
362 rtc::Thread* thread_;
363 rtc::PacketSocketFactory* factory_;
365 bool send_retransmit_count_attribute_;
366 rtc::Network* network_;
370 std::string content_name_;
373 // In order to establish a connection to this Port (so that real data can be
374 // sent through), the other side must send us a STUN binding request that is
375 // authenticated with this username_fragment and password.
376 // PortAllocatorSession will provide these username_fragment and password.
378 // Note: we should always use username_fragment() instead of using
379 // |ice_username_fragment_| directly. For the details see the comment on
380 // username_fragment().
381 std::string ice_username_fragment_;
382 std::string password_;
383 std::vector<Candidate> candidates_;
384 AddressMap connections_;
386 bool enable_port_packets_;
387 IceProtocolType ice_protocol_;
391 // Information to use when going through a proxy.
392 std::string user_agent_;
393 rtc::ProxyInfo proxy_;
395 friend class Connection;
398 // Represents a communication link between a port on the local client and a
399 // port on the remote client.
400 class Connection : public rtc::MessageHandler,
401 public sigslot::has_slots<> {
403 // States are from RFC 5245. http://tools.ietf.org/html/rfc5245#section-5.7.4
405 STATE_WAITING = 0, // Check has not been performed, Waiting pair on CL.
406 STATE_INPROGRESS, // Check has been sent, transaction is in progress.
407 STATE_SUCCEEDED, // Check already done, produced a successful result.
408 STATE_FAILED // Check for this connection failed.
411 virtual ~Connection();
413 // The local port where this connection sends and receives packets.
414 Port* port() { return port_; }
415 const Port* port() const { return port_; }
417 // Returns the description of the local port
418 virtual const Candidate& local_candidate() const;
420 // Returns the description of the remote port to which we communicate.
421 const Candidate& remote_candidate() const { return remote_candidate_; }
423 // Returns the pair priority.
424 uint64 priority() const;
427 STATE_READ_INIT = 0, // we have yet to receive a ping
428 STATE_READABLE = 1, // we have received pings recently
429 STATE_READ_TIMEOUT = 2, // we haven't received pings in a while
432 ReadState read_state() const { return read_state_; }
433 bool readable() const { return read_state_ == STATE_READABLE; }
436 STATE_WRITABLE = 0, // we have received ping responses recently
437 STATE_WRITE_UNRELIABLE = 1, // we have had a few ping failures
438 STATE_WRITE_INIT = 2, // we have yet to receive a ping response
439 STATE_WRITE_TIMEOUT = 3, // we have had a large number of ping failures
442 WriteState write_state() const { return write_state_; }
443 bool writable() const { return write_state_ == STATE_WRITABLE; }
445 // Determines whether the connection has finished connecting. This can only
446 // be false for TCP connections.
447 bool connected() const { return connected_; }
449 // Estimate of the round-trip time over this connection.
450 uint32 rtt() const { return rtt_; }
452 size_t sent_total_bytes();
453 size_t sent_bytes_second();
454 size_t recv_total_bytes();
455 size_t recv_bytes_second();
456 sigslot::signal1<Connection*> SignalStateChange;
458 // Sent when the connection has decided that it is no longer of value. It
459 // will delete itself immediately after this call.
460 sigslot::signal1<Connection*> SignalDestroyed;
462 // The connection can send and receive packets asynchronously. This matches
463 // the interface of AsyncPacketSocket, which may use UDP or TCP under the
465 virtual int Send(const void* data, size_t size,
466 const rtc::PacketOptions& options) = 0;
468 // Error if Send() returns < 0
469 virtual int GetError() = 0;
471 sigslot::signal4<Connection*, const char*, size_t,
472 const rtc::PacketTime&> SignalReadPacket;
474 sigslot::signal1<Connection*> SignalReadyToSend;
476 // Called when a packet is received on this connection.
477 void OnReadPacket(const char* data, size_t size,
478 const rtc::PacketTime& packet_time);
480 // Called when the socket is currently able to send.
481 void OnReadyToSend();
483 // Called when a connection is determined to be no longer useful to us. We
484 // still keep it around in case the other side wants to use it. But we can
485 // safely stop pinging on it and we can allow it to time out if the other
486 // side stops using it as well.
487 bool pruned() const { return pruned_; }
490 bool use_candidate_attr() const { return use_candidate_attr_; }
491 void set_use_candidate_attr(bool enable);
493 void set_remote_ice_mode(IceMode mode) {
494 remote_ice_mode_ = mode;
497 // Makes the connection go away.
500 // Checks that the state of this connection is up-to-date. The argument is
501 // the current time, which is compared against various timeouts.
502 void UpdateState(uint32 now);
504 // Called when this connection should try checking writability again.
505 uint32 last_ping_sent() const { return last_ping_sent_; }
506 void Ping(uint32 now);
508 // Called whenever a valid ping is received on this connection. This is
509 // public because the connection intercepts the first ping for us.
510 uint32 last_ping_received() const { return last_ping_received_; }
513 // Debugging description of this connection
514 std::string ToString() const;
515 std::string ToSensitiveString() const;
517 bool reported() const { return reported_; }
518 void set_reported(bool reported) { reported_ = reported;}
520 // This flag will be set if this connection is the chosen one for media
521 // transmission. This connection will send STUN ping with USE-CANDIDATE
523 sigslot::signal1<Connection*> SignalUseCandidate;
524 // Invoked when Connection receives STUN error response with 487 code.
525 void HandleRoleConflictFromPeer();
527 State state() const { return state_; }
529 IceMode remote_ice_mode() const { return remote_ice_mode_; }
532 // Constructs a new connection to the given remote port.
533 Connection(Port* port, size_t index, const Candidate& candidate);
535 // Called back when StunRequestManager has a stun packet to send
536 void OnSendStunPacket(const void* data, size_t size, StunRequest* req);
538 // Callbacks from ConnectionRequest
539 void OnConnectionRequestResponse(ConnectionRequest* req,
540 StunMessage* response);
541 void OnConnectionRequestErrorResponse(ConnectionRequest* req,
542 StunMessage* response);
543 void OnConnectionRequestTimeout(ConnectionRequest* req);
545 // Changes the state and signals if necessary.
546 void set_read_state(ReadState value);
547 void set_write_state(WriteState value);
548 void set_state(State state);
549 void set_connected(bool value);
551 // Checks if this connection is useless, and hence, should be destroyed.
554 void OnMessage(rtc::Message *pmsg);
557 size_t local_candidate_index_;
558 Candidate remote_candidate_;
559 ReadState read_state_;
560 WriteState write_state_;
563 // By default |use_candidate_attr_| flag will be true,
564 // as we will be using agrressive nomination.
565 // But when peer is ice-lite, this flag "must" be initialized to false and
566 // turn on when connection becomes "best connection".
567 bool use_candidate_attr_;
568 IceMode remote_ice_mode_;
569 StunRequestManager requests_;
571 uint32 last_ping_sent_; // last time we sent a ping to the other side
572 uint32 last_ping_received_; // last time we received a ping from the other
574 uint32 last_data_received_;
575 uint32 last_ping_response_received_;
576 std::vector<uint32> pings_since_last_response_;
578 rtc::RateTracker recv_rate_tracker_;
579 rtc::RateTracker send_rate_tracker_;
582 void MaybeAddPrflxCandidate(ConnectionRequest* request,
583 StunMessage* response);
589 friend class ConnectionRequest;
592 // ProxyConnection defers all the interesting work to the port
593 class ProxyConnection : public Connection {
595 ProxyConnection(Port* port, size_t index, const Candidate& candidate);
597 virtual int Send(const void* data, size_t size,
598 const rtc::PacketOptions& options);
599 virtual int GetError() { return error_; }
605 } // namespace cricket
607 #endif // TALK_P2P_BASE_PORT_H_