henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 1 | /* |
| 2 | * Copyright 2012 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 | |
Steve Anton | 10542f2 | 2019-01-11 17:11:00 | [diff] [blame] | 11 | #ifndef P2P_BASE_PORT_INTERFACE_H_ |
| 12 | #define P2P_BASE_PORT_INTERFACE_H_ |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 13 | |
Harald Alvestrand | 9a953b2 | 2024-01-26 07:11:50 | [diff] [blame] | 14 | #include <memory> |
Florent Castelli | 8037fc6 | 2024-08-29 13:00:40 | [diff] [blame] | 15 | #include <optional> |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 16 | #include <string> |
Lahiru Ginnaliya Gamathige | 3ba7beb | 2021-02-01 10:06:11 | [diff] [blame] | 17 | #include <utility> |
Steve Anton | 6c38cc7 | 2017-11-29 18:25:58 | [diff] [blame] | 18 | #include <vector> |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 19 | |
Ali Tofigh | ea5a944 | 2022-06-14 13:20:15 | [diff] [blame] | 20 | #include "absl/strings/string_view.h" |
Taylor Brandstetter | 6e2e7ce | 2017-12-19 18:26:23 | [diff] [blame] | 21 | #include "api/candidate.h" |
Philipp Hancke | 833ec4d | 2024-04-10 00:35:41 | [diff] [blame] | 22 | #include "api/field_trials_view.h" |
Harald Alvestrand | 9a953b2 | 2024-01-26 07:11:50 | [diff] [blame] | 23 | #include "api/packet_socket_factory.h" |
Philipp Hancke | 833ec4d | 2024-04-10 00:35:41 | [diff] [blame] | 24 | #include "api/task_queue/task_queue_base.h" |
Steve Anton | 10542f2 | 2019-01-11 17:11:00 | [diff] [blame] | 25 | #include "p2p/base/transport_description.h" |
| 26 | #include "rtc_base/async_packet_socket.h" |
Lahiru Ginnaliya Gamathige | 3ba7beb | 2021-02-01 10:06:11 | [diff] [blame] | 27 | #include "rtc_base/callback_list.h" |
Steve Anton | 10542f2 | 2019-01-11 17:11:00 | [diff] [blame] | 28 | #include "rtc_base/socket_address.h" |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 29 | |
| 30 | namespace rtc { |
| 31 | class Network; |
| 32 | struct PacketOptions; |
Yves Gerey | 665174f | 2018-06-19 13:03:05 | [diff] [blame] | 33 | } // namespace rtc |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 34 | |
| 35 | namespace cricket { |
| 36 | class Connection; |
| 37 | class IceMessage; |
| 38 | class StunMessage; |
Qingsi Wang | 72a43a1 | 2018-02-21 00:03:18 | [diff] [blame] | 39 | class StunStats; |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 40 | |
| 41 | enum ProtocolType { |
| 42 | PROTO_UDP, |
| 43 | PROTO_TCP, |
hnsl | 277b250 | 2016-12-13 13:17:23 | [diff] [blame] | 44 | PROTO_SSLTCP, // Pseudo-TLS. |
| 45 | PROTO_TLS, |
| 46 | PROTO_LAST = PROTO_TLS |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 47 | }; |
| 48 | |
| 49 | // Defines the interface for a port, which represents a local communication |
| 50 | // mechanism that can be used to create connections to similar mechanisms of |
| 51 | // the other client. Various types of ports will implement this interface. |
| 52 | class PortInterface { |
| 53 | public: |
Steve Anton | 1cf1b7d | 2017-10-30 17:00:15 | [diff] [blame] | 54 | virtual ~PortInterface(); |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 55 | |
Tommi | 6417bbf | 2024-03-11 15:54:12 | [diff] [blame] | 56 | virtual webrtc::IceCandidateType Type() const = 0; |
Niels Möller | e0c6bdf | 2022-03-24 14:18:02 | [diff] [blame] | 57 | virtual const rtc::Network* Network() const = 0; |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 58 | |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 59 | // Methods to set/get ICE role and tiebreaker values. |
| 60 | virtual void SetIceRole(IceRole role) = 0; |
| 61 | virtual IceRole GetIceRole() const = 0; |
| 62 | |
Manashi Sarkar | 6071f04 | 2024-05-31 09:28:48 | [diff] [blame] | 63 | virtual void SetIceTiebreaker(uint64_t tiebreaker) = 0; |
Peter Boström | 0c4e06b | 2015-10-07 10:23:21 | [diff] [blame] | 64 | virtual uint64_t IceTiebreaker() const = 0; |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 65 | |
| 66 | virtual bool SharedSocket() const = 0; |
| 67 | |
Ali Tofigh | 58ecd42 | 2022-06-23 11:43:02 | [diff] [blame] | 68 | virtual bool SupportsProtocol(absl::string_view protocol) const = 0; |
Honghai Zhang | f9945b2 | 2015-12-15 20:20:13 | [diff] [blame] | 69 | |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 70 | // PrepareAddress will attempt to get an address for this port that other |
| 71 | // clients can send to. It may take some time before the address is ready. |
| 72 | // Once it is ready, we will send SignalAddressReady. If errors are |
| 73 | // preventing the port from getting an address, it may send |
| 74 | // SignalAddressError. |
| 75 | virtual void PrepareAddress() = 0; |
| 76 | |
| 77 | // Returns the connection to the given address or NULL if none exists. |
Yves Gerey | 665174f | 2018-06-19 13:03:05 | [diff] [blame] | 78 | virtual Connection* GetConnection(const rtc::SocketAddress& remote_addr) = 0; |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 79 | |
| 80 | // Creates a new connection to the given address. |
| 81 | enum CandidateOrigin { ORIGIN_THIS_PORT, ORIGIN_OTHER_PORT, ORIGIN_MESSAGE }; |
Yves Gerey | 665174f | 2018-06-19 13:03:05 | [diff] [blame] | 82 | virtual Connection* CreateConnection(const Candidate& remote_candidate, |
| 83 | CandidateOrigin origin) = 0; |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 84 | |
| 85 | // Functions on the underlying socket(s). |
| 86 | virtual int SetOption(rtc::Socket::Option opt, int value) = 0; |
| 87 | virtual int GetOption(rtc::Socket::Option opt, int* value) = 0; |
| 88 | virtual int GetError() = 0; |
| 89 | |
Honghai Zhang | b9e7b4a | 2016-07-01 03:52:02 | [diff] [blame] | 90 | virtual ProtocolType GetProtocol() const = 0; |
| 91 | |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 92 | virtual const std::vector<Candidate>& Candidates() const = 0; |
| 93 | |
| 94 | // Sends the given packet to the given address, provided that the address is |
| 95 | // that of a connection or an address that has sent to us already. |
Yves Gerey | 665174f | 2018-06-19 13:03:05 | [diff] [blame] | 96 | virtual int SendTo(const void* data, |
| 97 | size_t size, |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 98 | const rtc::SocketAddress& addr, |
Yves Gerey | 665174f | 2018-06-19 13:03:05 | [diff] [blame] | 99 | const rtc::PacketOptions& options, |
| 100 | bool payload) = 0; |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 101 | |
| 102 | // Indicates that we received a successful STUN binding request from an |
| 103 | // address that doesn't correspond to any current connection. To turn this |
| 104 | // into a real connection, call CreateConnection. |
Yves Gerey | 665174f | 2018-06-19 13:03:05 | [diff] [blame] | 105 | sigslot::signal6<PortInterface*, |
| 106 | const rtc::SocketAddress&, |
| 107 | ProtocolType, |
| 108 | IceMessage*, |
| 109 | const std::string&, |
| 110 | bool> |
| 111 | SignalUnknownAddress; |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 112 | |
| 113 | // Sends a response message (normal or error) to the given request. One of |
| 114 | // these methods should be called as a response to SignalUnknownAddress. |
Tommi | 278b19d | 2022-04-12 12:03:40 | [diff] [blame] | 115 | virtual void SendBindingErrorResponse(StunMessage* message, |
Yves Gerey | 665174f | 2018-06-19 13:03:05 | [diff] [blame] | 116 | const rtc::SocketAddress& addr, |
| 117 | int error_code, |
Ali Tofigh | de2ac5a | 2022-06-30 09:58:26 | [diff] [blame] | 118 | absl::string_view reason) = 0; |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 119 | |
| 120 | // Signaled when this port decides to delete itself because it no longer has |
| 121 | // any usefulness. |
Lahiru Ginnaliya Gamathige | 3ba7beb | 2021-02-01 10:06:11 | [diff] [blame] | 122 | virtual void SubscribePortDestroyed( |
| 123 | std::function<void(PortInterface*)> callback) = 0; |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 124 | |
| 125 | // Signaled when Port discovers ice role conflict with the peer. |
| 126 | sigslot::signal1<PortInterface*> SignalRoleConflict; |
| 127 | |
| 128 | // Normally, packets arrive through a connection (or they result signaling of |
| 129 | // unknown address). Calling this method turns off delivery of packets |
| 130 | // through their respective connection and instead delivers every packet |
| 131 | // through this port. |
| 132 | virtual void EnablePortPackets() = 0; |
Yves Gerey | 665174f | 2018-06-19 13:03:05 | [diff] [blame] | 133 | sigslot:: |
| 134 | signal4<PortInterface*, const char*, size_t, const rtc::SocketAddress&> |
| 135 | SignalReadPacket; |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 136 | |
stefan | c1aeaf0 | 2015-10-15 14:26:07 | [diff] [blame] | 137 | // Emitted each time a packet is sent on this port. |
Stefan Holmer | 55674ff | 2016-01-14 14:49:16 | [diff] [blame] | 138 | sigslot::signal1<const rtc::SentPacket&> SignalSentPacket; |
stefan | c1aeaf0 | 2015-10-15 14:26:07 | [diff] [blame] | 139 | |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 140 | virtual std::string ToString() const = 0; |
| 141 | |
Florent Castelli | 8037fc6 | 2024-08-29 13:00:40 | [diff] [blame] | 142 | virtual void GetStunStats(std::optional<StunStats>* stats) = 0; |
Qingsi Wang | 72a43a1 | 2018-02-21 00:03:18 | [diff] [blame] | 143 | |
Harald Alvestrand | 9a953b2 | 2024-01-26 07:11:50 | [diff] [blame] | 144 | // Removes and deletes a connection object. `DestroyConnection` will |
| 145 | // delete the connection object directly whereas `DestroyConnectionAsync` |
| 146 | // defers the `delete` operation to when the call stack has been unwound. |
| 147 | // Async may be needed when deleting a connection object from within a |
| 148 | // callback. |
| 149 | virtual void DestroyConnection(Connection* conn) = 0; |
| 150 | |
| 151 | virtual void DestroyConnectionAsync(Connection* conn) = 0; |
| 152 | |
| 153 | // The thread on which this port performs its I/O. |
| 154 | virtual webrtc::TaskQueueBase* thread() = 0; |
| 155 | |
| 156 | // The factory used to create the sockets of this port. |
| 157 | virtual rtc::PacketSocketFactory* socket_factory() const = 0; |
Harald Alvestrand | 9a953b2 | 2024-01-26 07:11:50 | [diff] [blame] | 158 | |
| 159 | // Identifies the generation that this port was created in. |
| 160 | virtual uint32_t generation() const = 0; |
| 161 | virtual void set_generation(uint32_t generation) = 0; |
| 162 | virtual bool send_retransmit_count_attribute() const = 0; |
| 163 | // For debugging purposes. |
| 164 | virtual const std::string& content_name() const = 0; |
| 165 | |
| 166 | // Called when the Connection discovers a local peer reflexive candidate. |
| 167 | virtual void AddPrflxCandidate(const Candidate& local) = 0; |
| 168 | |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 169 | protected: |
Steve Anton | 1cf1b7d | 2017-10-30 17:00:15 | [diff] [blame] | 170 | PortInterface(); |
Harald Alvestrand | 9a953b2 | 2024-01-26 07:11:50 | [diff] [blame] | 171 | virtual void UpdateNetworkCost() = 0; |
| 172 | |
| 173 | // Returns DSCP value packets generated by the port itself should use. |
| 174 | virtual rtc::DiffServCodePoint StunDscpValue() const = 0; |
| 175 | |
| 176 | // If the given data comprises a complete and correct STUN message then the |
| 177 | // return value is true, otherwise false. If the message username corresponds |
| 178 | // with this port's username fragment, msg will contain the parsed STUN |
| 179 | // message. Otherwise, the function may send a STUN response internally. |
| 180 | // remote_username contains the remote fragment of the STUN username. |
| 181 | virtual bool GetStunMessage(const char* data, |
| 182 | size_t size, |
| 183 | const rtc::SocketAddress& addr, |
| 184 | std::unique_ptr<IceMessage>* out_msg, |
| 185 | std::string* out_username) = 0; |
| 186 | |
| 187 | // This method will return local and remote username fragements from the |
| 188 | // stun username attribute if present. |
| 189 | virtual bool ParseStunUsername(const StunMessage* stun_msg, |
| 190 | std::string* local_username, |
| 191 | std::string* remote_username) const = 0; |
| 192 | virtual std::string CreateStunUsername( |
| 193 | absl::string_view remote_username) const = 0; |
| 194 | |
| 195 | virtual bool MaybeIceRoleConflict(const rtc::SocketAddress& addr, |
| 196 | IceMessage* stun_msg, |
| 197 | absl::string_view remote_ufrag) = 0; |
| 198 | |
| 199 | virtual int16_t network_cost() const = 0; |
| 200 | |
| 201 | // Connection and Port are entangled; functions exposed to Port only |
| 202 | // should not be public. |
| 203 | friend class Connection; |
henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 | [diff] [blame] | 204 | }; |
| 205 | |
| 206 | } // namespace cricket |
| 207 | |
Steve Anton | 10542f2 | 2019-01-11 17:11:00 | [diff] [blame] | 208 | #endif // P2P_BASE_PORT_INTERFACE_H_ |