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