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 11 // This file contains the PeerConnection interface as defined in 12 // https://w3c.github.io/webrtc-pc/#peer-to-peer-connections 13 // 14 // The PeerConnectionFactory class provides factory methods to create 15 // PeerConnection, MediaStream and MediaStreamTrack objects. 16 // 17 // The following steps are needed to setup a typical call using WebRTC: 18 // 19 // 1. Create a PeerConnectionFactoryInterface. Check constructors for more 20 // information about input parameters. 21 // 22 // 2. Create a PeerConnection object. Provide a configuration struct which 23 // points to STUN and/or TURN servers used to generate ICE candidates, and 24 // provide an object that implements the PeerConnectionObserver interface, 25 // which is used to receive callbacks from the PeerConnection. 26 // 27 // 3. Create local MediaStreamTracks using the PeerConnectionFactory and add 28 // them to PeerConnection by calling AddTrack (or legacy method, AddStream). 29 // 30 // 4. Create an offer, call SetLocalDescription with it, serialize it, and send 31 // it to the remote peer 32 // 33 // 5. Once an ICE candidate has been gathered, the PeerConnection will call the 34 // observer function OnIceCandidate. The candidates must also be serialized and 35 // sent to the remote peer. 36 // 37 // 6. Once an answer is received from the remote peer, call 38 // SetRemoteDescription with the remote answer. 39 // 40 // 7. Once a remote candidate is received from the remote peer, provide it to 41 // the PeerConnection by calling AddIceCandidate. 42 // 43 // The receiver of a call (assuming the application is "call"-based) can decide 44 // to accept or reject the call; this decision will be taken by the application, 45 // not the PeerConnection. 46 // 47 // If the application decides to accept the call, it should: 48 // 49 // 1. Create PeerConnectionFactoryInterface if it doesn't exist. 50 // 51 // 2. Create a new PeerConnection. 52 // 53 // 3. Provide the remote offer to the new PeerConnection object by calling 54 // SetRemoteDescription. 55 // 56 // 4. Generate an answer to the remote offer by calling CreateAnswer and send it 57 // back to the remote peer. 58 // 59 // 5. Provide the local answer to the new PeerConnection by calling 60 // SetLocalDescription with the answer. 61 // 62 // 6. Provide the remote ICE candidates by calling AddIceCandidate. 63 // 64 // 7. Once a candidate has been gathered, the PeerConnection will call the 65 // observer function OnIceCandidate. Send these candidates to the remote peer. 66 67 #ifndef API_PEER_CONNECTION_INTERFACE_H_ 68 #define API_PEER_CONNECTION_INTERFACE_H_ 69 70 #include <stdio.h> 71 72 #include <memory> 73 #include <string> 74 #include <vector> 75 76 #include "api/async_resolver_factory.h" 77 #include "api/audio/audio_mixer.h" 78 #include "api/audio_codecs/audio_decoder_factory.h" 79 #include "api/audio_codecs/audio_encoder_factory.h" 80 #include "api/audio_options.h" 81 #include "api/call/call_factory_interface.h" 82 #include "api/crypto/crypto_options.h" 83 #include "api/data_channel_interface.h" 84 #include "api/dtls_transport_interface.h" 85 #include "api/fec_controller.h" 86 #include "api/ice_transport_interface.h" 87 #include "api/jsep.h" 88 #include "api/media_stream_interface.h" 89 #include "api/neteq/neteq_factory.h" 90 #include "api/network_state_predictor.h" 91 #include "api/packet_socket_factory.h" 92 #include "api/rtc_error.h" 93 #include "api/rtc_event_log/rtc_event_log_factory_interface.h" 94 #include "api/rtc_event_log_output.h" 95 #include "api/rtp_receiver_interface.h" 96 #include "api/rtp_sender_interface.h" 97 #include "api/rtp_transceiver_interface.h" 98 #include "api/sctp_transport_interface.h" 99 #include "api/set_remote_description_observer_interface.h" 100 #include "api/stats/rtc_stats_collector_callback.h" 101 #include "api/stats_types.h" 102 #include "api/task_queue/task_queue_factory.h" 103 #include "api/transport/bitrate_settings.h" 104 #include "api/transport/enums.h" 105 #include "api/transport/media/media_transport_interface.h" 106 #include "api/transport/network_control.h" 107 #include "api/transport/webrtc_key_value_config.h" 108 #include "api/turn_customizer.h" 109 #include "media/base/media_config.h" 110 #include "media/base/media_engine.h" 111 // TODO(bugs.webrtc.org/7447): We plan to provide a way to let applications 112 // inject a PacketSocketFactory and/or NetworkManager, and not expose 113 // PortAllocator in the PeerConnection api. 114 #include "p2p/base/port_allocator.h" // nogncheck 115 #include "rtc_base/network.h" 116 #include "rtc_base/rtc_certificate.h" 117 #include "rtc_base/rtc_certificate_generator.h" 118 #include "rtc_base/socket_address.h" 119 #include "rtc_base/ssl_certificate.h" 120 #include "rtc_base/ssl_stream_adapter.h" 121 #include "rtc_base/system/rtc_export.h" 122 123 namespace rtc { 124 class Thread; 125 } // namespace rtc 126 127 namespace webrtc { 128 129 // MediaStream container interface. 130 class StreamCollectionInterface : public rtc::RefCountInterface { 131 public: 132 // TODO(ronghuawu): Update the function names to c++ style, e.g. find -> Find. 133 virtual size_t count() = 0; 134 virtual MediaStreamInterface* at(size_t index) = 0; 135 virtual MediaStreamInterface* find(const std::string& label) = 0; 136 virtual MediaStreamTrackInterface* FindAudioTrack(const std::string& id) = 0; 137 virtual MediaStreamTrackInterface* FindVideoTrack(const std::string& id) = 0; 138 139 protected: 140 // Dtor protected as objects shouldn't be deleted via this interface. 141 ~StreamCollectionInterface() override = default; 142 }; 143 144 class StatsObserver : public rtc::RefCountInterface { 145 public: 146 virtual void OnComplete(const StatsReports& reports) = 0; 147 148 protected: 149 ~StatsObserver() override = default; 150 }; 151 152 enum class SdpSemantics { kPlanB, kUnifiedPlan }; 153 154 class RTC_EXPORT PeerConnectionInterface : public rtc::RefCountInterface { 155 public: 156 // See https://w3c.github.io/webrtc-pc/#dom-rtcsignalingstate 157 enum SignalingState { 158 kStable, 159 kHaveLocalOffer, 160 kHaveLocalPrAnswer, 161 kHaveRemoteOffer, 162 kHaveRemotePrAnswer, 163 kClosed, 164 }; 165 166 // See https://w3c.github.io/webrtc-pc/#dom-rtcicegatheringstate 167 enum IceGatheringState { 168 kIceGatheringNew, 169 kIceGatheringGathering, 170 kIceGatheringComplete 171 }; 172 173 // See https://w3c.github.io/webrtc-pc/#dom-rtcpeerconnectionstate 174 enum class PeerConnectionState { 175 kNew, 176 kConnecting, 177 kConnected, 178 kDisconnected, 179 kFailed, 180 kClosed, 181 }; 182 183 // See https://w3c.github.io/webrtc-pc/#dom-rtciceconnectionstate 184 enum IceConnectionState { 185 kIceConnectionNew, 186 kIceConnectionChecking, 187 kIceConnectionConnected, 188 kIceConnectionCompleted, 189 kIceConnectionFailed, 190 kIceConnectionDisconnected, 191 kIceConnectionClosed, 192 kIceConnectionMax, 193 }; 194 195 // TLS certificate policy. 196 enum TlsCertPolicy { 197 // For TLS based protocols, ensure the connection is secure by not 198 // circumventing certificate validation. 199 kTlsCertPolicySecure, 200 // For TLS based protocols, disregard security completely by skipping 201 // certificate validation. This is insecure and should never be used unless 202 // security is irrelevant in that particular context. 203 kTlsCertPolicyInsecureNoCheck, 204 }; 205 206 struct RTC_EXPORT IceServer { 207 IceServer(); 208 IceServer(const IceServer&); 209 ~IceServer(); 210 211 // TODO(jbauch): Remove uri when all code using it has switched to urls. 212 // List of URIs associated with this server. Valid formats are described 213 // in RFC7064 and RFC7065, and more may be added in the future. The "host" 214 // part of the URI may contain either an IP address or a hostname. 215 std::string uri; 216 std::vector<std::string> urls; 217 std::string username; 218 std::string password; 219 TlsCertPolicy tls_cert_policy = kTlsCertPolicySecure; 220 // If the URIs in |urls| only contain IP addresses, this field can be used 221 // to indicate the hostname, which may be necessary for TLS (using the SNI 222 // extension). If |urls| itself contains the hostname, this isn't 223 // necessary. 224 std::string hostname; 225 // List of protocols to be used in the TLS ALPN extension. 226 std::vector<std::string> tls_alpn_protocols; 227 // List of elliptic curves to be used in the TLS elliptic curves extension. 228 std::vector<std::string> tls_elliptic_curves; 229 230 bool operator==(const IceServer& o) const { 231 return uri == o.uri && urls == o.urls && username == o.username && 232 password == o.password && tls_cert_policy == o.tls_cert_policy && 233 hostname == o.hostname && 234 tls_alpn_protocols == o.tls_alpn_protocols && 235 tls_elliptic_curves == o.tls_elliptic_curves; 236 } 237 bool operator!=(const IceServer& o) const { return !(*this == o); } 238 }; 239 typedef std::vector<IceServer> IceServers; 240 241 enum IceTransportsType { 242 // TODO(pthatcher): Rename these kTransporTypeXXX, but update 243 // Chromium at the same time. 244 kNone, 245 kRelay, 246 kNoHost, 247 kAll 248 }; 249 250 // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-24#section-4.1.1 251 enum BundlePolicy { 252 kBundlePolicyBalanced, 253 kBundlePolicyMaxBundle, 254 kBundlePolicyMaxCompat 255 }; 256 257 // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-24#section-4.1.1 258 enum RtcpMuxPolicy { 259 kRtcpMuxPolicyNegotiate, 260 kRtcpMuxPolicyRequire, 261 }; 262 263 enum TcpCandidatePolicy { 264 kTcpCandidatePolicyEnabled, 265 kTcpCandidatePolicyDisabled 266 }; 267 268 enum CandidateNetworkPolicy { 269 kCandidateNetworkPolicyAll, 270 kCandidateNetworkPolicyLowCost 271 }; 272 273 enum ContinualGatheringPolicy { GATHER_ONCE, GATHER_CONTINUALLY }; 274 275 enum class RTCConfigurationType { 276 // A configuration that is safer to use, despite not having the best 277 // performance. Currently this is the default configuration. 278 kSafe, 279 // An aggressive configuration that has better performance, although it 280 // may be riskier and may need extra support in the application. 281 kAggressive 282 }; 283 284 // TODO(hbos): Change into class with private data and public getters. 285 // TODO(nisse): In particular, accessing fields directly from an 286 // application is brittle, since the organization mirrors the 287 // organization of the implementation, which isn't stable. So we 288 // need getters and setters at least for fields which applications 289 // are interested in. 290 struct RTC_EXPORT RTCConfiguration { 291 // This struct is subject to reorganization, both for naming 292 // consistency, and to group settings to match where they are used 293 // in the implementation. To do that, we need getter and setter 294 // methods for all settings which are of interest to applications, 295 // Chrome in particular. 296 297 RTCConfiguration(); 298 RTCConfiguration(const RTCConfiguration&); 299 explicit RTCConfiguration(RTCConfigurationType type); 300 ~RTCConfiguration(); 301 302 bool operator==(const RTCConfiguration& o) const; 303 bool operator!=(const RTCConfiguration& o) const; 304 dscpRTCConfiguration305 bool dscp() const { return media_config.enable_dscp; } set_dscpRTCConfiguration306 void set_dscp(bool enable) { media_config.enable_dscp = enable; } 307 cpu_adaptationRTCConfiguration308 bool cpu_adaptation() const { 309 return media_config.video.enable_cpu_adaptation; 310 } set_cpu_adaptationRTCConfiguration311 void set_cpu_adaptation(bool enable) { 312 media_config.video.enable_cpu_adaptation = enable; 313 } 314 suspend_below_min_bitrateRTCConfiguration315 bool suspend_below_min_bitrate() const { 316 return media_config.video.suspend_below_min_bitrate; 317 } set_suspend_below_min_bitrateRTCConfiguration318 void set_suspend_below_min_bitrate(bool enable) { 319 media_config.video.suspend_below_min_bitrate = enable; 320 } 321 prerenderer_smoothingRTCConfiguration322 bool prerenderer_smoothing() const { 323 return media_config.video.enable_prerenderer_smoothing; 324 } set_prerenderer_smoothingRTCConfiguration325 void set_prerenderer_smoothing(bool enable) { 326 media_config.video.enable_prerenderer_smoothing = enable; 327 } 328 experiment_cpu_load_estimatorRTCConfiguration329 bool experiment_cpu_load_estimator() const { 330 return media_config.video.experiment_cpu_load_estimator; 331 } set_experiment_cpu_load_estimatorRTCConfiguration332 void set_experiment_cpu_load_estimator(bool enable) { 333 media_config.video.experiment_cpu_load_estimator = enable; 334 } 335 audio_rtcp_report_interval_msRTCConfiguration336 int audio_rtcp_report_interval_ms() const { 337 return media_config.audio.rtcp_report_interval_ms; 338 } set_audio_rtcp_report_interval_msRTCConfiguration339 void set_audio_rtcp_report_interval_ms(int audio_rtcp_report_interval_ms) { 340 media_config.audio.rtcp_report_interval_ms = 341 audio_rtcp_report_interval_ms; 342 } 343 video_rtcp_report_interval_msRTCConfiguration344 int video_rtcp_report_interval_ms() const { 345 return media_config.video.rtcp_report_interval_ms; 346 } set_video_rtcp_report_interval_msRTCConfiguration347 void set_video_rtcp_report_interval_ms(int video_rtcp_report_interval_ms) { 348 media_config.video.rtcp_report_interval_ms = 349 video_rtcp_report_interval_ms; 350 } 351 352 static const int kUndefined = -1; 353 // Default maximum number of packets in the audio jitter buffer. 354 static const int kAudioJitterBufferMaxPackets = 200; 355 // ICE connection receiving timeout for aggressive configuration. 356 static const int kAggressiveIceConnectionReceivingTimeout = 1000; 357 358 //////////////////////////////////////////////////////////////////////// 359 // The below few fields mirror the standard RTCConfiguration dictionary: 360 // https://w3c.github.io/webrtc-pc/#rtcconfiguration-dictionary 361 //////////////////////////////////////////////////////////////////////// 362 363 // TODO(pthatcher): Rename this ice_servers, but update Chromium 364 // at the same time. 365 IceServers servers; 366 // TODO(pthatcher): Rename this ice_transport_type, but update 367 // Chromium at the same time. 368 IceTransportsType type = kAll; 369 BundlePolicy bundle_policy = kBundlePolicyBalanced; 370 RtcpMuxPolicy rtcp_mux_policy = kRtcpMuxPolicyRequire; 371 std::vector<rtc::scoped_refptr<rtc::RTCCertificate>> certificates; 372 int ice_candidate_pool_size = 0; 373 374 ////////////////////////////////////////////////////////////////////////// 375 // The below fields correspond to constraints from the deprecated 376 // constraints interface for constructing a PeerConnection. 377 // 378 // absl::optional fields can be "missing", in which case the implementation 379 // default will be used. 380 ////////////////////////////////////////////////////////////////////////// 381 382 // If set to true, don't gather IPv6 ICE candidates. 383 // TODO(deadbeef): Remove this? IPv6 support has long stopped being 384 // experimental 385 bool disable_ipv6 = false; 386 387 // If set to true, don't gather IPv6 ICE candidates on Wi-Fi. 388 // Only intended to be used on specific devices. Certain phones disable IPv6 389 // when the screen is turned off and it would be better to just disable the 390 // IPv6 ICE candidates on Wi-Fi in those cases. 391 bool disable_ipv6_on_wifi = false; 392 393 // By default, the PeerConnection will use a limited number of IPv6 network 394 // interfaces, in order to avoid too many ICE candidate pairs being created 395 // and delaying ICE completion. 396 // 397 // Can be set to INT_MAX to effectively disable the limit. 398 int max_ipv6_networks = cricket::kDefaultMaxIPv6Networks; 399 400 // Exclude link-local network interfaces 401 // from consideration for gathering ICE candidates. 402 bool disable_link_local_networks = false; 403 404 // If set to true, use RTP data channels instead of SCTP. 405 // TODO(deadbeef): Remove this. We no longer commit to supporting RTP data 406 // channels, though some applications are still working on moving off of 407 // them. 408 bool enable_rtp_data_channel = false; 409 410 // Minimum bitrate at which screencast video tracks will be encoded at. 411 // This means adding padding bits up to this bitrate, which can help 412 // when switching from a static scene to one with motion. 413 absl::optional<int> screencast_min_bitrate; 414 415 // Use new combined audio/video bandwidth estimation? 416 absl::optional<bool> combined_audio_video_bwe; 417 418 // TODO(bugs.webrtc.org/9891) - Move to crypto_options 419 // Can be used to disable DTLS-SRTP. This should never be done, but can be 420 // useful for testing purposes, for example in setting up a loopback call 421 // with a single PeerConnection. 422 absl::optional<bool> enable_dtls_srtp; 423 424 ///////////////////////////////////////////////// 425 // The below fields are not part of the standard. 426 ///////////////////////////////////////////////// 427 428 // Can be used to disable TCP candidate generation. 429 TcpCandidatePolicy tcp_candidate_policy = kTcpCandidatePolicyEnabled; 430 431 // Can be used to avoid gathering candidates for a "higher cost" network, 432 // if a lower cost one exists. For example, if both Wi-Fi and cellular 433 // interfaces are available, this could be used to avoid using the cellular 434 // interface. 435 CandidateNetworkPolicy candidate_network_policy = 436 kCandidateNetworkPolicyAll; 437 438 // The maximum number of packets that can be stored in the NetEq audio 439 // jitter buffer. Can be reduced to lower tolerated audio latency. 440 int audio_jitter_buffer_max_packets = kAudioJitterBufferMaxPackets; 441 442 // Whether to use the NetEq "fast mode" which will accelerate audio quicker 443 // if it falls behind. 444 bool audio_jitter_buffer_fast_accelerate = false; 445 446 // The minimum delay in milliseconds for the audio jitter buffer. 447 int audio_jitter_buffer_min_delay_ms = 0; 448 449 // Whether the audio jitter buffer adapts the delay to retransmitted 450 // packets. 451 bool audio_jitter_buffer_enable_rtx_handling = false; 452 453 // Timeout in milliseconds before an ICE candidate pair is considered to be 454 // "not receiving", after which a lower priority candidate pair may be 455 // selected. 456 int ice_connection_receiving_timeout = kUndefined; 457 458 // Interval in milliseconds at which an ICE "backup" candidate pair will be 459 // pinged. This is a candidate pair which is not actively in use, but may 460 // be switched to if the active candidate pair becomes unusable. 461 // 462 // This is relevant mainly to Wi-Fi/cell handoff; the application may not 463 // want this backup cellular candidate pair pinged frequently, since it 464 // consumes data/battery. 465 int ice_backup_candidate_pair_ping_interval = kUndefined; 466 467 // Can be used to enable continual gathering, which means new candidates 468 // will be gathered as network interfaces change. Note that if continual 469 // gathering is used, the candidate removal API should also be used, to 470 // avoid an ever-growing list of candidates. 471 ContinualGatheringPolicy continual_gathering_policy = GATHER_ONCE; 472 473 // If set to true, candidate pairs will be pinged in order of most likely 474 // to work (which means using a TURN server, generally), rather than in 475 // standard priority order. 476 bool prioritize_most_likely_ice_candidate_pairs = false; 477 478 // Implementation defined settings. A public member only for the benefit of 479 // the implementation. Applications must not access it directly, and should 480 // instead use provided accessor methods, e.g., set_cpu_adaptation. 481 struct cricket::MediaConfig media_config; 482 483 // If set to true, only one preferred TURN allocation will be used per 484 // network interface. UDP is preferred over TCP and IPv6 over IPv4. This 485 // can be used to cut down on the number of candidate pairings. 486 // Deprecated. TODO(webrtc:11026) Remove this flag once the downstream 487 // dependency is removed. 488 bool prune_turn_ports = false; 489 490 // The policy used to prune turn port. 491 PortPrunePolicy turn_port_prune_policy = NO_PRUNE; 492 GetTurnPortPrunePolicyRTCConfiguration493 PortPrunePolicy GetTurnPortPrunePolicy() const { 494 return prune_turn_ports ? PRUNE_BASED_ON_PRIORITY 495 : turn_port_prune_policy; 496 } 497 498 // If set to true, this means the ICE transport should presume TURN-to-TURN 499 // candidate pairs will succeed, even before a binding response is received. 500 // This can be used to optimize the initial connection time, since the DTLS 501 // handshake can begin immediately. 502 bool presume_writable_when_fully_relayed = false; 503 504 // If true, "renomination" will be added to the ice options in the transport 505 // description. 506 // See: https://tools.ietf.org/html/draft-thatcher-ice-renomination-00 507 bool enable_ice_renomination = false; 508 509 // If true, the ICE role is re-determined when the PeerConnection sets a 510 // local transport description that indicates an ICE restart. 511 // 512 // This is standard RFC5245 ICE behavior, but causes unnecessary role 513 // thrashing, so an application may wish to avoid it. This role 514 // re-determining was removed in ICEbis (ICE v2). 515 bool redetermine_role_on_ice_restart = true; 516 517 // This flag is only effective when |continual_gathering_policy| is 518 // GATHER_CONTINUALLY. 519 // 520 // If true, after the ICE transport type is changed such that new types of 521 // ICE candidates are allowed by the new transport type, e.g. from 522 // IceTransportsType::kRelay to IceTransportsType::kAll, candidates that 523 // have been gathered by the ICE transport but not matching the previous 524 // transport type and as a result not observed by PeerConnectionObserver, 525 // will be surfaced to the observer. 526 bool surface_ice_candidates_on_ice_transport_type_changed = false; 527 528 // The following fields define intervals in milliseconds at which ICE 529 // connectivity checks are sent. 530 // 531 // We consider ICE is "strongly connected" for an agent when there is at 532 // least one candidate pair that currently succeeds in connectivity check 533 // from its direction i.e. sending a STUN ping and receives a STUN ping 534 // response, AND all candidate pairs have sent a minimum number of pings for 535 // connectivity (this number is implementation-specific). Otherwise, ICE is 536 // considered in "weak connectivity". 537 // 538 // Note that the above notion of strong and weak connectivity is not defined 539 // in RFC 5245, and they apply to our current ICE implementation only. 540 // 541 // 1) ice_check_interval_strong_connectivity defines the interval applied to 542 // ALL candidate pairs when ICE is strongly connected, and it overrides the 543 // default value of this interval in the ICE implementation; 544 // 2) ice_check_interval_weak_connectivity defines the counterpart for ALL 545 // pairs when ICE is weakly connected, and it overrides the default value of 546 // this interval in the ICE implementation; 547 // 3) ice_check_min_interval defines the minimal interval (equivalently the 548 // maximum rate) that overrides the above two intervals when either of them 549 // is less. 550 absl::optional<int> ice_check_interval_strong_connectivity; 551 absl::optional<int> ice_check_interval_weak_connectivity; 552 absl::optional<int> ice_check_min_interval; 553 554 // The min time period for which a candidate pair must wait for response to 555 // connectivity checks before it becomes unwritable. This parameter 556 // overrides the default value in the ICE implementation if set. 557 absl::optional<int> ice_unwritable_timeout; 558 559 // The min number of connectivity checks that a candidate pair must sent 560 // without receiving response before it becomes unwritable. This parameter 561 // overrides the default value in the ICE implementation if set. 562 absl::optional<int> ice_unwritable_min_checks; 563 564 // The min time period for which a candidate pair must wait for response to 565 // connectivity checks it becomes inactive. This parameter overrides the 566 // default value in the ICE implementation if set. 567 absl::optional<int> ice_inactive_timeout; 568 569 // The interval in milliseconds at which STUN candidates will resend STUN 570 // binding requests to keep NAT bindings open. 571 absl::optional<int> stun_candidate_keepalive_interval; 572 573 // Optional TurnCustomizer. 574 // With this class one can modify outgoing TURN messages. 575 // The object passed in must remain valid until PeerConnection::Close() is 576 // called. 577 webrtc::TurnCustomizer* turn_customizer = nullptr; 578 579 // Preferred network interface. 580 // A candidate pair on a preferred network has a higher precedence in ICE 581 // than one on an un-preferred network, regardless of priority or network 582 // cost. 583 absl::optional<rtc::AdapterType> network_preference; 584 585 // Configure the SDP semantics used by this PeerConnection. Note that the 586 // WebRTC 1.0 specification requires kUnifiedPlan semantics. The 587 // RtpTransceiver API is only available with kUnifiedPlan semantics. 588 // 589 // kPlanB will cause PeerConnection to create offers and answers with at 590 // most one audio and one video m= section with multiple RtpSenders and 591 // RtpReceivers specified as multiple a=ssrc lines within the section. This 592 // will also cause PeerConnection to ignore all but the first m= section of 593 // the same media type. 594 // 595 // kUnifiedPlan will cause PeerConnection to create offers and answers with 596 // multiple m= sections where each m= section maps to one RtpSender and one 597 // RtpReceiver (an RtpTransceiver), either both audio or both video. This 598 // will also cause PeerConnection to ignore all but the first a=ssrc lines 599 // that form a Plan B stream. 600 // 601 // For users who wish to send multiple audio/video streams and need to stay 602 // interoperable with legacy WebRTC implementations or use legacy APIs, 603 // specify kPlanB. 604 // 605 // For all other users, specify kUnifiedPlan. 606 SdpSemantics sdp_semantics = SdpSemantics::kPlanB; 607 608 // TODO(bugs.webrtc.org/9891) - Move to crypto_options or remove. 609 // Actively reset the SRTP parameters whenever the DTLS transports 610 // underneath are reset for every offer/answer negotiation. 611 // This is only intended to be a workaround for crbug.com/835958 612 // WARNING: This would cause RTP/RTCP packets decryption failure if not used 613 // correctly. This flag will be deprecated soon. Do not rely on it. 614 bool active_reset_srtp_params = false; 615 616 // DEPRECATED. Do not use. This option is ignored by peer connection. 617 // TODO(webrtc:9719): Delete this option. 618 bool use_media_transport = false; 619 620 // DEPRECATED. Do not use. This option is ignored by peer connection. 621 // TODO(webrtc:9719): Delete this option. 622 bool use_media_transport_for_data_channels = false; 623 624 // If MediaTransportFactory is provided in PeerConnectionFactory, this flag 625 // informs PeerConnection that it should use the DatagramTransportInterface 626 // for packets instead DTLS. It's invalid to set it to |true| if the 627 // MediaTransportFactory wasn't provided. 628 absl::optional<bool> use_datagram_transport; 629 630 // If MediaTransportFactory is provided in PeerConnectionFactory, this flag 631 // informs PeerConnection that it should use the DatagramTransport's 632 // implementation of DataChannelTransportInterface for data channels instead 633 // of SCTP-DTLS. 634 absl::optional<bool> use_datagram_transport_for_data_channels; 635 636 // If true, this PeerConnection will only use datagram transport for data 637 // channels when receiving an incoming offer that includes datagram 638 // transport parameters. It will not request use of a datagram transport 639 // when it creates the initial, outgoing offer. 640 // This setting only applies when |use_datagram_transport_for_data_channels| 641 // is true. 642 absl::optional<bool> use_datagram_transport_for_data_channels_receive_only; 643 644 // Defines advanced optional cryptographic settings related to SRTP and 645 // frame encryption for native WebRTC. Setting this will overwrite any 646 // settings set in PeerConnectionFactory (which is deprecated). 647 absl::optional<CryptoOptions> crypto_options; 648 649 // Configure if we should include the SDP attribute extmap-allow-mixed in 650 // our offer. Although we currently do support this, it's not included in 651 // our offer by default due to a previous bug that caused the SDP parser to 652 // abort parsing if this attribute was present. This is fixed in Chrome 71. 653 // TODO(webrtc:9985): Change default to true once sufficient time has 654 // passed. 655 bool offer_extmap_allow_mixed = false; 656 657 // TURN logging identifier. 658 // This identifier is added to a TURN allocation 659 // and it intended to be used to be able to match client side 660 // logs with TURN server logs. It will not be added if it's an empty string. 661 std::string turn_logging_id; 662 663 // Added to be able to control rollout of this feature. 664 bool enable_implicit_rollback = false; 665 666 // Whether network condition based codec switching is allowed. 667 absl::optional<bool> allow_codec_switching; 668 669 // 670 // Don't forget to update operator== if adding something. 671 // 672 }; 673 674 // See: https://www.w3.org/TR/webrtc/#idl-def-rtcofferansweroptions 675 struct RTCOfferAnswerOptions { 676 static const int kUndefined = -1; 677 static const int kMaxOfferToReceiveMedia = 1; 678 679 // The default value for constraint offerToReceiveX:true. 680 static const int kOfferToReceiveMediaTrue = 1; 681 682 // These options are left as backwards compatibility for clients who need 683 // "Plan B" semantics. Clients who have switched to "Unified Plan" semantics 684 // should use the RtpTransceiver API (AddTransceiver) instead. 685 // 686 // offer_to_receive_X set to 1 will cause a media description to be 687 // generated in the offer, even if no tracks of that type have been added. 688 // Values greater than 1 are treated the same. 689 // 690 // If set to 0, the generated directional attribute will not include the 691 // "recv" direction (meaning it will be "sendonly" or "inactive". 692 int offer_to_receive_video = kUndefined; 693 int offer_to_receive_audio = kUndefined; 694 695 bool voice_activity_detection = true; 696 bool ice_restart = false; 697 698 // If true, will offer to BUNDLE audio/video/data together. Not to be 699 // confused with RTCP mux (multiplexing RTP and RTCP together). 700 bool use_rtp_mux = true; 701 702 // If true, "a=packetization:<payload_type> raw" attribute will be offered 703 // in the SDP for all video payload and accepted in the answer if offered. 704 bool raw_packetization_for_video = false; 705 706 // This will apply to all video tracks with a Plan B SDP offer/answer. 707 int num_simulcast_layers = 1; 708 709 // If true: Use SDP format from draft-ietf-mmusic-scdp-sdp-03 710 // If false: Use SDP format from draft-ietf-mmusic-sdp-sdp-26 or later 711 bool use_obsolete_sctp_sdp = false; 712 713 RTCOfferAnswerOptions() = default; 714 RTCOfferAnswerOptionsRTCOfferAnswerOptions715 RTCOfferAnswerOptions(int offer_to_receive_video, 716 int offer_to_receive_audio, 717 bool voice_activity_detection, 718 bool ice_restart, 719 bool use_rtp_mux) 720 : offer_to_receive_video(offer_to_receive_video), 721 offer_to_receive_audio(offer_to_receive_audio), 722 voice_activity_detection(voice_activity_detection), 723 ice_restart(ice_restart), 724 use_rtp_mux(use_rtp_mux) {} 725 }; 726 727 // Used by GetStats to decide which stats to include in the stats reports. 728 // |kStatsOutputLevelStandard| includes the standard stats for Javascript API; 729 // |kStatsOutputLevelDebug| includes both the standard stats and additional 730 // stats for debugging purposes. 731 enum StatsOutputLevel { 732 kStatsOutputLevelStandard, 733 kStatsOutputLevelDebug, 734 }; 735 736 // Accessor methods to active local streams. 737 // This method is not supported with kUnifiedPlan semantics. Please use 738 // GetSenders() instead. 739 virtual rtc::scoped_refptr<StreamCollectionInterface> local_streams() = 0; 740 741 // Accessor methods to remote streams. 742 // This method is not supported with kUnifiedPlan semantics. Please use 743 // GetReceivers() instead. 744 virtual rtc::scoped_refptr<StreamCollectionInterface> remote_streams() = 0; 745 746 // Add a new MediaStream to be sent on this PeerConnection. 747 // Note that a SessionDescription negotiation is needed before the 748 // remote peer can receive the stream. 749 // 750 // This has been removed from the standard in favor of a track-based API. So, 751 // this is equivalent to simply calling AddTrack for each track within the 752 // stream, with the one difference that if "stream->AddTrack(...)" is called 753 // later, the PeerConnection will automatically pick up the new track. Though 754 // this functionality will be deprecated in the future. 755 // 756 // This method is not supported with kUnifiedPlan semantics. Please use 757 // AddTrack instead. 758 virtual bool AddStream(MediaStreamInterface* stream) = 0; 759 760 // Remove a MediaStream from this PeerConnection. 761 // Note that a SessionDescription negotiation is needed before the 762 // remote peer is notified. 763 // 764 // This method is not supported with kUnifiedPlan semantics. Please use 765 // RemoveTrack instead. 766 virtual void RemoveStream(MediaStreamInterface* stream) = 0; 767 768 // Add a new MediaStreamTrack to be sent on this PeerConnection, and return 769 // the newly created RtpSender. The RtpSender will be associated with the 770 // streams specified in the |stream_ids| list. 771 // 772 // Errors: 773 // - INVALID_PARAMETER: |track| is null, has a kind other than audio or video, 774 // or a sender already exists for the track. 775 // - INVALID_STATE: The PeerConnection is closed. 776 virtual RTCErrorOr<rtc::scoped_refptr<RtpSenderInterface>> AddTrack( 777 rtc::scoped_refptr<MediaStreamTrackInterface> track, 778 const std::vector<std::string>& stream_ids) = 0; 779 780 // Remove an RtpSender from this PeerConnection. 781 // Returns true on success. 782 // TODO(steveanton): Replace with signature that returns RTCError. 783 virtual bool RemoveTrack(RtpSenderInterface* sender) = 0; 784 785 // Plan B semantics: Removes the RtpSender from this PeerConnection. 786 // Unified Plan semantics: Stop sending on the RtpSender and mark the 787 // corresponding RtpTransceiver direction as no longer sending. 788 // 789 // Errors: 790 // - INVALID_PARAMETER: |sender| is null or (Plan B only) the sender is not 791 // associated with this PeerConnection. 792 // - INVALID_STATE: PeerConnection is closed. 793 // TODO(bugs.webrtc.org/9534): Rename to RemoveTrack once the other signature 794 // is removed. 795 virtual RTCError RemoveTrackNew( 796 rtc::scoped_refptr<RtpSenderInterface> sender); 797 798 // AddTransceiver creates a new RtpTransceiver and adds it to the set of 799 // transceivers. Adding a transceiver will cause future calls to CreateOffer 800 // to add a media description for the corresponding transceiver. 801 // 802 // The initial value of |mid| in the returned transceiver is null. Setting a 803 // new session description may change it to a non-null value. 804 // 805 // https://w3c.github.io/webrtc-pc/#dom-rtcpeerconnection-addtransceiver 806 // 807 // Optionally, an RtpTransceiverInit structure can be specified to configure 808 // the transceiver from construction. If not specified, the transceiver will 809 // default to having a direction of kSendRecv and not be part of any streams. 810 // 811 // These methods are only available when Unified Plan is enabled (see 812 // RTCConfiguration). 813 // 814 // Common errors: 815 // - INTERNAL_ERROR: The configuration does not have Unified Plan enabled. 816 817 // Adds a transceiver with a sender set to transmit the given track. The kind 818 // of the transceiver (and sender/receiver) will be derived from the kind of 819 // the track. 820 // Errors: 821 // - INVALID_PARAMETER: |track| is null. 822 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>> 823 AddTransceiver(rtc::scoped_refptr<MediaStreamTrackInterface> track) = 0; 824 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>> 825 AddTransceiver(rtc::scoped_refptr<MediaStreamTrackInterface> track, 826 const RtpTransceiverInit& init) = 0; 827 828 // Adds a transceiver with the given kind. Can either be MEDIA_TYPE_AUDIO or 829 // MEDIA_TYPE_VIDEO. 830 // Errors: 831 // - INVALID_PARAMETER: |media_type| is not MEDIA_TYPE_AUDIO or 832 // MEDIA_TYPE_VIDEO. 833 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>> 834 AddTransceiver(cricket::MediaType media_type) = 0; 835 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>> 836 AddTransceiver(cricket::MediaType media_type, 837 const RtpTransceiverInit& init) = 0; 838 839 // Creates a sender without a track. Can be used for "early media"/"warmup" 840 // use cases, where the application may want to negotiate video attributes 841 // before a track is available to send. 842 // 843 // The standard way to do this would be through "addTransceiver", but we 844 // don't support that API yet. 845 // 846 // |kind| must be "audio" or "video". 847 // 848 // |stream_id| is used to populate the msid attribute; if empty, one will 849 // be generated automatically. 850 // 851 // This method is not supported with kUnifiedPlan semantics. Please use 852 // AddTransceiver instead. 853 virtual rtc::scoped_refptr<RtpSenderInterface> CreateSender( 854 const std::string& kind, 855 const std::string& stream_id) = 0; 856 857 // If Plan B semantics are specified, gets all RtpSenders, created either 858 // through AddStream, AddTrack, or CreateSender. All senders of a specific 859 // media type share the same media description. 860 // 861 // If Unified Plan semantics are specified, gets the RtpSender for each 862 // RtpTransceiver. 863 virtual std::vector<rtc::scoped_refptr<RtpSenderInterface>> GetSenders() 864 const = 0; 865 866 // If Plan B semantics are specified, gets all RtpReceivers created when a 867 // remote description is applied. All receivers of a specific media type share 868 // the same media description. It is also possible to have a media description 869 // with no associated RtpReceivers, if the directional attribute does not 870 // indicate that the remote peer is sending any media. 871 // 872 // If Unified Plan semantics are specified, gets the RtpReceiver for each 873 // RtpTransceiver. 874 virtual std::vector<rtc::scoped_refptr<RtpReceiverInterface>> GetReceivers() 875 const = 0; 876 877 // Get all RtpTransceivers, created either through AddTransceiver, AddTrack or 878 // by a remote description applied with SetRemoteDescription. 879 // 880 // Note: This method is only available when Unified Plan is enabled (see 881 // RTCConfiguration). 882 virtual std::vector<rtc::scoped_refptr<RtpTransceiverInterface>> 883 GetTransceivers() const = 0; 884 885 // The legacy non-compliant GetStats() API. This correspond to the 886 // callback-based version of getStats() in JavaScript. The returned metrics 887 // are UNDOCUMENTED and many of them rely on implementation-specific details. 888 // The goal is to DELETE THIS VERSION but we can't today because it is heavily 889 // relied upon by third parties. See https://crbug.com/822696. 890 // 891 // This version is wired up into Chrome. Any stats implemented are 892 // automatically exposed to the Web Platform. This has BYPASSED the Chrome 893 // release processes for years and lead to cross-browser incompatibility 894 // issues and web application reliance on Chrome-only behavior. 895 // 896 // This API is in "maintenance mode", serious regressions should be fixed but 897 // adding new stats is highly discouraged. 898 // 899 // TODO(hbos): Deprecate and remove this when third parties have migrated to 900 // the spec-compliant GetStats() API. https://crbug.com/822696 901 virtual bool GetStats(StatsObserver* observer, 902 MediaStreamTrackInterface* track, // Optional 903 StatsOutputLevel level) = 0; 904 // The spec-compliant GetStats() API. This correspond to the promise-based 905 // version of getStats() in JavaScript. Implementation status is described in 906 // api/stats/rtcstats_objects.h. For more details on stats, see spec: 907 // https://w3c.github.io/webrtc-pc/#dom-rtcpeerconnection-getstats 908 // TODO(hbos): Takes shared ownership, use rtc::scoped_refptr<> instead. This 909 // requires stop overriding the current version in third party or making third 910 // party calls explicit to avoid ambiguity during switch. Make the future 911 // version abstract as soon as third party projects implement it. 912 virtual void GetStats(RTCStatsCollectorCallback* callback) = 0; 913 // Spec-compliant getStats() performing the stats selection algorithm with the 914 // sender. https://w3c.github.io/webrtc-pc/#dom-rtcrtpsender-getstats 915 virtual void GetStats( 916 rtc::scoped_refptr<RtpSenderInterface> selector, 917 rtc::scoped_refptr<RTCStatsCollectorCallback> callback) = 0; 918 // Spec-compliant getStats() performing the stats selection algorithm with the 919 // receiver. https://w3c.github.io/webrtc-pc/#dom-rtcrtpreceiver-getstats 920 virtual void GetStats( 921 rtc::scoped_refptr<RtpReceiverInterface> selector, 922 rtc::scoped_refptr<RTCStatsCollectorCallback> callback) = 0; 923 // Clear cached stats in the RTCStatsCollector. 924 // Exposed for testing while waiting for automatic cache clear to work. 925 // https://bugs.webrtc.org/8693 ClearStatsCache()926 virtual void ClearStatsCache() {} 927 928 // Create a data channel with the provided config, or default config if none 929 // is provided. Note that an offer/answer negotiation is still necessary 930 // before the data channel can be used. 931 // 932 // Also, calling CreateDataChannel is the only way to get a data "m=" section 933 // in SDP, so it should be done before CreateOffer is called, if the 934 // application plans to use data channels. 935 virtual rtc::scoped_refptr<DataChannelInterface> CreateDataChannel( 936 const std::string& label, 937 const DataChannelInit* config) = 0; 938 939 // Returns the more recently applied description; "pending" if it exists, and 940 // otherwise "current". See below. 941 virtual const SessionDescriptionInterface* local_description() const = 0; 942 virtual const SessionDescriptionInterface* remote_description() const = 0; 943 944 // A "current" description the one currently negotiated from a complete 945 // offer/answer exchange. 946 virtual const SessionDescriptionInterface* current_local_description() 947 const = 0; 948 virtual const SessionDescriptionInterface* current_remote_description() 949 const = 0; 950 951 // A "pending" description is one that's part of an incomplete offer/answer 952 // exchange (thus, either an offer or a pranswer). Once the offer/answer 953 // exchange is finished, the "pending" description will become "current". 954 virtual const SessionDescriptionInterface* pending_local_description() 955 const = 0; 956 virtual const SessionDescriptionInterface* pending_remote_description() 957 const = 0; 958 959 // Tells the PeerConnection that ICE should be restarted. This triggers a need 960 // for negotiation and subsequent CreateOffer() calls will act as if 961 // RTCOfferAnswerOptions::ice_restart is true. 962 // https://w3c.github.io/webrtc-pc/#dom-rtcpeerconnection-restartice 963 // TODO(hbos): Remove default implementation when downstream projects 964 // implement this. 965 virtual void RestartIce() = 0; 966 967 // Create a new offer. 968 // The CreateSessionDescriptionObserver callback will be called when done. 969 virtual void CreateOffer(CreateSessionDescriptionObserver* observer, 970 const RTCOfferAnswerOptions& options) = 0; 971 972 // Create an answer to an offer. 973 // The CreateSessionDescriptionObserver callback will be called when done. 974 virtual void CreateAnswer(CreateSessionDescriptionObserver* observer, 975 const RTCOfferAnswerOptions& options) = 0; 976 977 // Sets the local session description. 978 // The PeerConnection takes the ownership of |desc| even if it fails. 979 // The |observer| callback will be called when done. 980 // TODO(deadbeef): Change |desc| to be a unique_ptr, to make it clear 981 // that this method always takes ownership of it. 982 virtual void SetLocalDescription(SetSessionDescriptionObserver* observer, 983 SessionDescriptionInterface* desc) = 0; 984 // Implicitly creates an offer or answer (depending on the current signaling 985 // state) and performs SetLocalDescription() with the newly generated session 986 // description. 987 // TODO(hbos): Make pure virtual when implemented by downstream projects. SetLocalDescription(SetSessionDescriptionObserver * observer)988 virtual void SetLocalDescription(SetSessionDescriptionObserver* observer) {} 989 // Sets the remote session description. 990 // The PeerConnection takes the ownership of |desc| even if it fails. 991 // The |observer| callback will be called when done. 992 // TODO(hbos): Remove when Chrome implements the new signature. SetRemoteDescription(SetSessionDescriptionObserver * observer,SessionDescriptionInterface * desc)993 virtual void SetRemoteDescription(SetSessionDescriptionObserver* observer, 994 SessionDescriptionInterface* desc) {} 995 virtual void SetRemoteDescription( 996 std::unique_ptr<SessionDescriptionInterface> desc, 997 rtc::scoped_refptr<SetRemoteDescriptionObserverInterface> observer) = 0; 998 999 virtual PeerConnectionInterface::RTCConfiguration GetConfiguration() = 0; 1000 1001 // Sets the PeerConnection's global configuration to |config|. 1002 // 1003 // The members of |config| that may be changed are |type|, |servers|, 1004 // |ice_candidate_pool_size| and |prune_turn_ports| (though the candidate 1005 // pool size can't be changed after the first call to SetLocalDescription). 1006 // Note that this means the BUNDLE and RTCP-multiplexing policies cannot be 1007 // changed with this method. 1008 // 1009 // Any changes to STUN/TURN servers or ICE candidate policy will affect the 1010 // next gathering phase, and cause the next call to createOffer to generate 1011 // new ICE credentials, as described in JSEP. This also occurs when 1012 // |prune_turn_ports| changes, for the same reasoning. 1013 // 1014 // If an error occurs, returns false and populates |error| if non-null: 1015 // - INVALID_MODIFICATION if |config| contains a modified parameter other 1016 // than one of the parameters listed above. 1017 // - INVALID_RANGE if |ice_candidate_pool_size| is out of range. 1018 // - SYNTAX_ERROR if parsing an ICE server URL failed. 1019 // - INVALID_PARAMETER if a TURN server is missing |username| or |password|. 1020 // - INTERNAL_ERROR if an unexpected error occurred. 1021 // 1022 // TODO(nisse): Make this pure virtual once all Chrome subclasses of 1023 // PeerConnectionInterface implement it. 1024 virtual RTCError SetConfiguration( 1025 const PeerConnectionInterface::RTCConfiguration& config); 1026 1027 // Provides a remote candidate to the ICE Agent. 1028 // A copy of the |candidate| will be created and added to the remote 1029 // description. So the caller of this method still has the ownership of the 1030 // |candidate|. 1031 // TODO(hbos): The spec mandates chaining this operation onto the operations 1032 // chain; deprecate and remove this version in favor of the callback-based 1033 // signature. 1034 virtual bool AddIceCandidate(const IceCandidateInterface* candidate) = 0; 1035 // TODO(hbos): Remove default implementation once implemented by downstream 1036 // projects. AddIceCandidate(std::unique_ptr<IceCandidateInterface> candidate,std::function<void (RTCError)> callback)1037 virtual void AddIceCandidate(std::unique_ptr<IceCandidateInterface> candidate, 1038 std::function<void(RTCError)> callback) {} 1039 1040 // Removes a group of remote candidates from the ICE agent. Needed mainly for 1041 // continual gathering, to avoid an ever-growing list of candidates as 1042 // networks come and go. 1043 virtual bool RemoveIceCandidates( 1044 const std::vector<cricket::Candidate>& candidates) = 0; 1045 1046 // 0 <= min <= current <= max should hold for set parameters. 1047 struct BitrateParameters { 1048 BitrateParameters(); 1049 ~BitrateParameters(); 1050 1051 absl::optional<int> min_bitrate_bps; 1052 absl::optional<int> current_bitrate_bps; 1053 absl::optional<int> max_bitrate_bps; 1054 }; 1055 1056 // SetBitrate limits the bandwidth allocated for all RTP streams sent by 1057 // this PeerConnection. Other limitations might affect these limits and 1058 // are respected (for example "b=AS" in SDP). 1059 // 1060 // Setting |current_bitrate_bps| will reset the current bitrate estimate 1061 // to the provided value. 1062 virtual RTCError SetBitrate(const BitrateSettings& bitrate); 1063 1064 // TODO(nisse): Deprecated - use version above. These two default 1065 // implementations require subclasses to implement one or the other 1066 // of the methods. 1067 virtual RTCError SetBitrate(const BitrateParameters& bitrate_parameters); 1068 1069 // Enable/disable playout of received audio streams. Enabled by default. Note 1070 // that even if playout is enabled, streams will only be played out if the 1071 // appropriate SDP is also applied. Setting |playout| to false will stop 1072 // playout of the underlying audio device but starts a task which will poll 1073 // for audio data every 10ms to ensure that audio processing happens and the 1074 // audio statistics are updated. 1075 // TODO(henrika): deprecate and remove this. SetAudioPlayout(bool playout)1076 virtual void SetAudioPlayout(bool playout) {} 1077 1078 // Enable/disable recording of transmitted audio streams. Enabled by default. 1079 // Note that even if recording is enabled, streams will only be recorded if 1080 // the appropriate SDP is also applied. 1081 // TODO(henrika): deprecate and remove this. SetAudioRecording(bool recording)1082 virtual void SetAudioRecording(bool recording) {} 1083 1084 // Looks up the DtlsTransport associated with a MID value. 1085 // In the Javascript API, DtlsTransport is a property of a sender, but 1086 // because the PeerConnection owns the DtlsTransport in this implementation, 1087 // it is better to look them up on the PeerConnection. 1088 virtual rtc::scoped_refptr<DtlsTransportInterface> LookupDtlsTransportByMid( 1089 const std::string& mid) = 0; 1090 1091 // Returns the SCTP transport, if any. 1092 virtual rtc::scoped_refptr<SctpTransportInterface> GetSctpTransport() 1093 const = 0; 1094 1095 // Returns the current SignalingState. 1096 virtual SignalingState signaling_state() = 0; 1097 1098 // Returns an aggregate state of all ICE *and* DTLS transports. 1099 // This is left in place to avoid breaking native clients who expect our old, 1100 // nonstandard behavior. 1101 // TODO(jonasolsson): deprecate and remove this. 1102 virtual IceConnectionState ice_connection_state() = 0; 1103 1104 // Returns an aggregated state of all ICE transports. 1105 virtual IceConnectionState standardized_ice_connection_state() = 0; 1106 1107 // Returns an aggregated state of all ICE and DTLS transports. 1108 virtual PeerConnectionState peer_connection_state() = 0; 1109 1110 virtual IceGatheringState ice_gathering_state() = 0; 1111 1112 // Returns the current state of canTrickleIceCandidates per 1113 // https://w3c.github.io/webrtc-pc/#attributes-1 can_trickle_ice_candidates()1114 virtual absl::optional<bool> can_trickle_ice_candidates() { 1115 // TODO(crbug.com/708484): Remove default implementation. 1116 return absl::nullopt; 1117 } 1118 1119 // Start RtcEventLog using an existing output-sink. Takes ownership of 1120 // |output| and passes it on to Call, which will take the ownership. If the 1121 // operation fails the output will be closed and deallocated. The event log 1122 // will send serialized events to the output object every |output_period_ms|. 1123 // Applications using the event log should generally make their own trade-off 1124 // regarding the output period. A long period is generally more efficient, 1125 // with potential drawbacks being more bursty thread usage, and more events 1126 // lost in case the application crashes. If the |output_period_ms| argument is 1127 // omitted, webrtc selects a default deemed to be workable in most cases. 1128 virtual bool StartRtcEventLog(std::unique_ptr<RtcEventLogOutput> output, 1129 int64_t output_period_ms) = 0; 1130 virtual bool StartRtcEventLog(std::unique_ptr<RtcEventLogOutput> output) = 0; 1131 1132 // Stops logging the RtcEventLog. 1133 virtual void StopRtcEventLog() = 0; 1134 1135 // Terminates all media, closes the transports, and in general releases any 1136 // resources used by the PeerConnection. This is an irreversible operation. 1137 // 1138 // Note that after this method completes, the PeerConnection will no longer 1139 // use the PeerConnectionObserver interface passed in on construction, and 1140 // thus the observer object can be safely destroyed. 1141 virtual void Close() = 0; 1142 1143 protected: 1144 // Dtor protected as objects shouldn't be deleted via this interface. 1145 ~PeerConnectionInterface() override = default; 1146 }; 1147 1148 // PeerConnection callback interface, used for RTCPeerConnection events. 1149 // Application should implement these methods. 1150 class PeerConnectionObserver { 1151 public: 1152 virtual ~PeerConnectionObserver() = default; 1153 1154 // Triggered when the SignalingState changed. 1155 virtual void OnSignalingChange( 1156 PeerConnectionInterface::SignalingState new_state) = 0; 1157 1158 // Triggered when media is received on a new stream from remote peer. OnAddStream(rtc::scoped_refptr<MediaStreamInterface> stream)1159 virtual void OnAddStream(rtc::scoped_refptr<MediaStreamInterface> stream) {} 1160 1161 // Triggered when a remote peer closes a stream. OnRemoveStream(rtc::scoped_refptr<MediaStreamInterface> stream)1162 virtual void OnRemoveStream(rtc::scoped_refptr<MediaStreamInterface> stream) { 1163 } 1164 1165 // Triggered when a remote peer opens a data channel. 1166 virtual void OnDataChannel( 1167 rtc::scoped_refptr<DataChannelInterface> data_channel) = 0; 1168 1169 // Triggered when renegotiation is needed. For example, an ICE restart 1170 // has begun. 1171 virtual void OnRenegotiationNeeded() = 0; 1172 1173 // Called any time the legacy IceConnectionState changes. 1174 // 1175 // Note that our ICE states lag behind the standard slightly. The most 1176 // notable differences include the fact that "failed" occurs after 15 1177 // seconds, not 30, and this actually represents a combination ICE + DTLS 1178 // state, so it may be "failed" if DTLS fails while ICE succeeds. 1179 // 1180 // TODO(jonasolsson): deprecate and remove this. OnIceConnectionChange(PeerConnectionInterface::IceConnectionState new_state)1181 virtual void OnIceConnectionChange( 1182 PeerConnectionInterface::IceConnectionState new_state) {} 1183 1184 // Called any time the standards-compliant IceConnectionState changes. OnStandardizedIceConnectionChange(PeerConnectionInterface::IceConnectionState new_state)1185 virtual void OnStandardizedIceConnectionChange( 1186 PeerConnectionInterface::IceConnectionState new_state) {} 1187 1188 // Called any time the PeerConnectionState changes. OnConnectionChange(PeerConnectionInterface::PeerConnectionState new_state)1189 virtual void OnConnectionChange( 1190 PeerConnectionInterface::PeerConnectionState new_state) {} 1191 1192 // Called any time the IceGatheringState changes. 1193 virtual void OnIceGatheringChange( 1194 PeerConnectionInterface::IceGatheringState new_state) = 0; 1195 1196 // A new ICE candidate has been gathered. 1197 virtual void OnIceCandidate(const IceCandidateInterface* candidate) = 0; 1198 1199 // Gathering of an ICE candidate failed. 1200 // See https://w3c.github.io/webrtc-pc/#event-icecandidateerror 1201 // |host_candidate| is a stringified socket address. OnIceCandidateError(const std::string & host_candidate,const std::string & url,int error_code,const std::string & error_text)1202 virtual void OnIceCandidateError(const std::string& host_candidate, 1203 const std::string& url, 1204 int error_code, 1205 const std::string& error_text) {} 1206 1207 // Gathering of an ICE candidate failed. 1208 // See https://w3c.github.io/webrtc-pc/#event-icecandidateerror OnIceCandidateError(const std::string & address,int port,const std::string & url,int error_code,const std::string & error_text)1209 virtual void OnIceCandidateError(const std::string& address, 1210 int port, 1211 const std::string& url, 1212 int error_code, 1213 const std::string& error_text) {} 1214 1215 // Ice candidates have been removed. 1216 // TODO(honghaiz): Make this a pure virtual method when all its subclasses 1217 // implement it. OnIceCandidatesRemoved(const std::vector<cricket::Candidate> & candidates)1218 virtual void OnIceCandidatesRemoved( 1219 const std::vector<cricket::Candidate>& candidates) {} 1220 1221 // Called when the ICE connection receiving status changes. OnIceConnectionReceivingChange(bool receiving)1222 virtual void OnIceConnectionReceivingChange(bool receiving) {} 1223 1224 // Called when the selected candidate pair for the ICE connection changes. OnIceSelectedCandidatePairChanged(const cricket::CandidatePairChangeEvent & event)1225 virtual void OnIceSelectedCandidatePairChanged( 1226 const cricket::CandidatePairChangeEvent& event) {} 1227 1228 // This is called when a receiver and its track are created. 1229 // TODO(zhihuang): Make this pure virtual when all subclasses implement it. 1230 // Note: This is called with both Plan B and Unified Plan semantics. Unified 1231 // Plan users should prefer OnTrack, OnAddTrack is only called as backwards 1232 // compatibility (and is called in the exact same situations as OnTrack). OnAddTrack(rtc::scoped_refptr<RtpReceiverInterface> receiver,const std::vector<rtc::scoped_refptr<MediaStreamInterface>> & streams)1233 virtual void OnAddTrack( 1234 rtc::scoped_refptr<RtpReceiverInterface> receiver, 1235 const std::vector<rtc::scoped_refptr<MediaStreamInterface>>& streams) {} 1236 1237 // This is called when signaling indicates a transceiver will be receiving 1238 // media from the remote endpoint. This is fired during a call to 1239 // SetRemoteDescription. The receiving track can be accessed by: 1240 // |transceiver->receiver()->track()| and its associated streams by 1241 // |transceiver->receiver()->streams()|. 1242 // Note: This will only be called if Unified Plan semantics are specified. 1243 // This behavior is specified in section 2.2.8.2.5 of the "Set the 1244 // RTCSessionDescription" algorithm: 1245 // https://w3c.github.io/webrtc-pc/#set-description OnTrack(rtc::scoped_refptr<RtpTransceiverInterface> transceiver)1246 virtual void OnTrack( 1247 rtc::scoped_refptr<RtpTransceiverInterface> transceiver) {} 1248 1249 // Called when signaling indicates that media will no longer be received on a 1250 // track. 1251 // With Plan B semantics, the given receiver will have been removed from the 1252 // PeerConnection and the track muted. 1253 // With Unified Plan semantics, the receiver will remain but the transceiver 1254 // will have changed direction to either sendonly or inactive. 1255 // https://w3c.github.io/webrtc-pc/#process-remote-track-removal 1256 // TODO(hbos,deadbeef): Make pure virtual when all subclasses implement it. OnRemoveTrack(rtc::scoped_refptr<RtpReceiverInterface> receiver)1257 virtual void OnRemoveTrack( 1258 rtc::scoped_refptr<RtpReceiverInterface> receiver) {} 1259 1260 // Called when an interesting usage is detected by WebRTC. 1261 // An appropriate action is to add information about the context of the 1262 // PeerConnection and write the event to some kind of "interesting events" 1263 // log function. 1264 // The heuristics for defining what constitutes "interesting" are 1265 // implementation-defined. OnInterestingUsage(int usage_pattern)1266 virtual void OnInterestingUsage(int usage_pattern) {} 1267 }; 1268 1269 // PeerConnectionDependencies holds all of PeerConnections dependencies. 1270 // A dependency is distinct from a configuration as it defines significant 1271 // executable code that can be provided by a user of the API. 1272 // 1273 // All new dependencies should be added as a unique_ptr to allow the 1274 // PeerConnection object to be the definitive owner of the dependencies 1275 // lifetime making injection safer. 1276 struct RTC_EXPORT PeerConnectionDependencies final { 1277 explicit PeerConnectionDependencies(PeerConnectionObserver* observer_in); 1278 // This object is not copyable or assignable. 1279 PeerConnectionDependencies(const PeerConnectionDependencies&) = delete; 1280 PeerConnectionDependencies& operator=(const PeerConnectionDependencies&) = 1281 delete; 1282 // This object is only moveable. 1283 PeerConnectionDependencies(PeerConnectionDependencies&&); 1284 PeerConnectionDependencies& operator=(PeerConnectionDependencies&&) = default; 1285 ~PeerConnectionDependencies(); 1286 // Mandatory dependencies 1287 PeerConnectionObserver* observer = nullptr; 1288 // Optional dependencies 1289 // TODO(bugs.webrtc.org/7447): remove port allocator once downstream is 1290 // updated. For now, you can only set one of allocator and 1291 // packet_socket_factory, not both. 1292 std::unique_ptr<cricket::PortAllocator> allocator; 1293 std::unique_ptr<rtc::PacketSocketFactory> packet_socket_factory; 1294 std::unique_ptr<webrtc::AsyncResolverFactory> async_resolver_factory; 1295 std::unique_ptr<webrtc::IceTransportFactory> ice_transport_factory; 1296 std::unique_ptr<rtc::RTCCertificateGeneratorInterface> cert_generator; 1297 std::unique_ptr<rtc::SSLCertificateVerifier> tls_cert_verifier; 1298 std::unique_ptr<webrtc::VideoBitrateAllocatorFactory> 1299 video_bitrate_allocator_factory; 1300 }; 1301 1302 // PeerConnectionFactoryDependencies holds all of the PeerConnectionFactory 1303 // dependencies. All new dependencies should be added here instead of 1304 // overloading the function. This simplifies dependency injection and makes it 1305 // clear which are mandatory and optional. If possible please allow the peer 1306 // connection factory to take ownership of the dependency by adding a unique_ptr 1307 // to this structure. 1308 struct RTC_EXPORT PeerConnectionFactoryDependencies final { 1309 PeerConnectionFactoryDependencies(); 1310 // This object is not copyable or assignable. 1311 PeerConnectionFactoryDependencies(const PeerConnectionFactoryDependencies&) = 1312 delete; 1313 PeerConnectionFactoryDependencies& operator=( 1314 const PeerConnectionFactoryDependencies&) = delete; 1315 // This object is only moveable. 1316 PeerConnectionFactoryDependencies(PeerConnectionFactoryDependencies&&); 1317 PeerConnectionFactoryDependencies& operator=( 1318 PeerConnectionFactoryDependencies&&) = default; 1319 ~PeerConnectionFactoryDependencies(); 1320 1321 // Optional dependencies 1322 rtc::Thread* network_thread = nullptr; 1323 rtc::Thread* worker_thread = nullptr; 1324 rtc::Thread* signaling_thread = nullptr; 1325 std::unique_ptr<TaskQueueFactory> task_queue_factory; 1326 std::unique_ptr<cricket::MediaEngineInterface> media_engine; 1327 std::unique_ptr<CallFactoryInterface> call_factory; 1328 std::unique_ptr<RtcEventLogFactoryInterface> event_log_factory; 1329 std::unique_ptr<FecControllerFactoryInterface> fec_controller_factory; 1330 std::unique_ptr<NetworkStatePredictorFactoryInterface> 1331 network_state_predictor_factory; 1332 std::unique_ptr<NetworkControllerFactoryInterface> network_controller_factory; 1333 std::unique_ptr<MediaTransportFactory> media_transport_factory; 1334 std::unique_ptr<NetEqFactory> neteq_factory; 1335 std::unique_ptr<WebRtcKeyValueConfig> trials; 1336 }; 1337 1338 // PeerConnectionFactoryInterface is the factory interface used for creating 1339 // PeerConnection, MediaStream and MediaStreamTrack objects. 1340 // 1341 // The simplest method for obtaiing one, CreatePeerConnectionFactory will 1342 // create the required libjingle threads, socket and network manager factory 1343 // classes for networking if none are provided, though it requires that the 1344 // application runs a message loop on the thread that called the method (see 1345 // explanation below) 1346 // 1347 // If an application decides to provide its own threads and/or implementation 1348 // of networking classes, it should use the alternate 1349 // CreatePeerConnectionFactory method which accepts threads as input, and use 1350 // the CreatePeerConnection version that takes a PortAllocator as an argument. 1351 class RTC_EXPORT PeerConnectionFactoryInterface 1352 : public rtc::RefCountInterface { 1353 public: 1354 class Options { 1355 public: Options()1356 Options() {} 1357 1358 // If set to true, created PeerConnections won't enforce any SRTP 1359 // requirement, allowing unsecured media. Should only be used for 1360 // testing/debugging. 1361 bool disable_encryption = false; 1362 1363 // Deprecated. The only effect of setting this to true is that 1364 // CreateDataChannel will fail, which is not that useful. 1365 bool disable_sctp_data_channels = false; 1366 1367 // If set to true, any platform-supported network monitoring capability 1368 // won't be used, and instead networks will only be updated via polling. 1369 // 1370 // This only has an effect if a PeerConnection is created with the default 1371 // PortAllocator implementation. 1372 bool disable_network_monitor = false; 1373 1374 // Sets the network types to ignore. For instance, calling this with 1375 // ADAPTER_TYPE_ETHERNET | ADAPTER_TYPE_LOOPBACK will ignore Ethernet and 1376 // loopback interfaces. 1377 int network_ignore_mask = rtc::kDefaultNetworkIgnoreMask; 1378 1379 // Sets the maximum supported protocol version. The highest version 1380 // supported by both ends will be used for the connection, i.e. if one 1381 // party supports DTLS 1.0 and the other DTLS 1.2, DTLS 1.0 will be used. 1382 rtc::SSLProtocolVersion ssl_max_version = rtc::SSL_PROTOCOL_DTLS_12; 1383 1384 // Sets crypto related options, e.g. enabled cipher suites. 1385 CryptoOptions crypto_options = CryptoOptions::NoGcm(); 1386 }; 1387 1388 // Set the options to be used for subsequently created PeerConnections. 1389 virtual void SetOptions(const Options& options) = 0; 1390 1391 // The preferred way to create a new peer connection. Simply provide the 1392 // configuration and a PeerConnectionDependencies structure. 1393 // TODO(benwright): Make pure virtual once downstream mock PC factory classes 1394 // are updated. 1395 virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection( 1396 const PeerConnectionInterface::RTCConfiguration& configuration, 1397 PeerConnectionDependencies dependencies); 1398 1399 // Deprecated; |allocator| and |cert_generator| may be null, in which case 1400 // default implementations will be used. 1401 // 1402 // |observer| must not be null. 1403 // 1404 // Note that this method does not take ownership of |observer|; it's the 1405 // responsibility of the caller to delete it. It can be safely deleted after 1406 // Close has been called on the returned PeerConnection, which ensures no 1407 // more observer callbacks will be invoked. 1408 virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection( 1409 const PeerConnectionInterface::RTCConfiguration& configuration, 1410 std::unique_ptr<cricket::PortAllocator> allocator, 1411 std::unique_ptr<rtc::RTCCertificateGeneratorInterface> cert_generator, 1412 PeerConnectionObserver* observer); 1413 1414 // Returns the capabilities of an RTP sender of type |kind|. 1415 // If for some reason you pass in MEDIA_TYPE_DATA, returns an empty structure. 1416 // TODO(orphis): Make pure virtual when all subclasses implement it. 1417 virtual RtpCapabilities GetRtpSenderCapabilities( 1418 cricket::MediaType kind) const; 1419 1420 // Returns the capabilities of an RTP receiver of type |kind|. 1421 // If for some reason you pass in MEDIA_TYPE_DATA, returns an empty structure. 1422 // TODO(orphis): Make pure virtual when all subclasses implement it. 1423 virtual RtpCapabilities GetRtpReceiverCapabilities( 1424 cricket::MediaType kind) const; 1425 1426 virtual rtc::scoped_refptr<MediaStreamInterface> CreateLocalMediaStream( 1427 const std::string& stream_id) = 0; 1428 1429 // Creates an AudioSourceInterface. 1430 // |options| decides audio processing settings. 1431 virtual rtc::scoped_refptr<AudioSourceInterface> CreateAudioSource( 1432 const cricket::AudioOptions& options) = 0; 1433 1434 // Creates a new local VideoTrack. The same |source| can be used in several 1435 // tracks. 1436 virtual rtc::scoped_refptr<VideoTrackInterface> CreateVideoTrack( 1437 const std::string& label, 1438 VideoTrackSourceInterface* source) = 0; 1439 1440 // Creates an new AudioTrack. At the moment |source| can be null. 1441 virtual rtc::scoped_refptr<AudioTrackInterface> CreateAudioTrack( 1442 const std::string& label, 1443 AudioSourceInterface* source) = 0; 1444 1445 // Starts AEC dump using existing file. Takes ownership of |file| and passes 1446 // it on to VoiceEngine (via other objects) immediately, which will take 1447 // the ownerhip. If the operation fails, the file will be closed. 1448 // A maximum file size in bytes can be specified. When the file size limit is 1449 // reached, logging is stopped automatically. If max_size_bytes is set to a 1450 // value <= 0, no limit will be used, and logging will continue until the 1451 // StopAecDump function is called. 1452 // TODO(webrtc:6463): Delete default implementation when downstream mocks 1453 // classes are updated. StartAecDump(FILE * file,int64_t max_size_bytes)1454 virtual bool StartAecDump(FILE* file, int64_t max_size_bytes) { 1455 return false; 1456 } 1457 1458 // Stops logging the AEC dump. 1459 virtual void StopAecDump() = 0; 1460 1461 protected: 1462 // Dtor and ctor protected as objects shouldn't be created or deleted via 1463 // this interface. PeerConnectionFactoryInterface()1464 PeerConnectionFactoryInterface() {} 1465 ~PeerConnectionFactoryInterface() override = default; 1466 }; 1467 1468 // CreateModularPeerConnectionFactory is implemented in the "peerconnection" 1469 // build target, which doesn't pull in the implementations of every module 1470 // webrtc may use. 1471 // 1472 // If an application knows it will only require certain modules, it can reduce 1473 // webrtc's impact on its binary size by depending only on the "peerconnection" 1474 // target and the modules the application requires, using 1475 // CreateModularPeerConnectionFactory. For example, if an application 1476 // only uses WebRTC for audio, it can pass in null pointers for the 1477 // video-specific interfaces, and omit the corresponding modules from its 1478 // build. 1479 // 1480 // If |network_thread| or |worker_thread| are null, the PeerConnectionFactory 1481 // will create the necessary thread internally. If |signaling_thread| is null, 1482 // the PeerConnectionFactory will use the thread on which this method is called 1483 // as the signaling thread, wrapping it in an rtc::Thread object if needed. 1484 RTC_EXPORT rtc::scoped_refptr<PeerConnectionFactoryInterface> 1485 CreateModularPeerConnectionFactory( 1486 PeerConnectionFactoryDependencies dependencies); 1487 1488 } // namespace webrtc 1489 1490 #endif // API_PEER_CONNECTION_INTERFACE_H_ 1491