blob: 7a2ac12e41968cd34d0c52b14d5fe5da660a7724 [file] [log] [blame]
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001/*
kjellanderb24317b2016-02-10 07:54:43 -08002 * Copyright 2012 The WebRTC project authors. All Rights Reserved.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00003 *
kjellanderb24317b2016-02-10 07:54:43 -08004 * 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.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00009 */
10
11// This file contains the PeerConnection interface as defined in
Steve Antonab6ea6b2018-02-26 14:23:09 -080012// https://w3c.github.io/webrtc-pc/#peer-to-peer-connections
henrike@webrtc.org28e20752013-07-10 00:45:36 +000013//
deadbeefb10f32f2017-02-08 01:38:21 -080014// 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//
henrike@webrtc.org28e20752013-07-10 00:45:36 +000019// 1. Create a PeerConnectionFactoryInterface. Check constructors for more
20// information about input parameters.
deadbeefb10f32f2017-02-08 01:38:21 -080021//
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
henrike@webrtc.org28e20752013-07-10 00:45:36 +000034// observer function OnIceCandidate. The candidates must also be serialized and
35// sent to the remote peer.
deadbeefb10f32f2017-02-08 01:38:21 -080036//
henrike@webrtc.org28e20752013-07-10 00:45:36 +000037// 6. Once an answer is received from the remote peer, call
deadbeefb10f32f2017-02-08 01:38:21 -080038// SetRemoteDescription with the remote answer.
39//
henrike@webrtc.org28e20752013-07-10 00:45:36 +000040// 7. Once a remote candidate is received from the remote peer, provide it to
deadbeefb10f32f2017-02-08 01:38:21 -080041// 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//
henrike@webrtc.org28e20752013-07-10 00:45:36 +000049// 1. Create PeerConnectionFactoryInterface if it doesn't exist.
deadbeefb10f32f2017-02-08 01:38:21 -080050//
henrike@webrtc.org28e20752013-07-10 00:45:36 +000051// 2. Create a new PeerConnection.
deadbeefb10f32f2017-02-08 01:38:21 -080052//
henrike@webrtc.org28e20752013-07-10 00:45:36 +000053// 3. Provide the remote offer to the new PeerConnection object by calling
deadbeefb10f32f2017-02-08 01:38:21 -080054// SetRemoteDescription.
55//
henrike@webrtc.org28e20752013-07-10 00:45:36 +000056// 4. Generate an answer to the remote offer by calling CreateAnswer and send it
57// back to the remote peer.
deadbeefb10f32f2017-02-08 01:38:21 -080058//
henrike@webrtc.org28e20752013-07-10 00:45:36 +000059// 5. Provide the local answer to the new PeerConnection by calling
deadbeefb10f32f2017-02-08 01:38:21 -080060// 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.
henrike@webrtc.org28e20752013-07-10 00:45:36 +000066
Steve Anton10542f22019-01-11 09:11:00 -080067#ifndef API_PEER_CONNECTION_INTERFACE_H_
68#define API_PEER_CONNECTION_INTERFACE_H_
henrike@webrtc.org28e20752013-07-10 00:45:36 +000069
Harald Alvestrandf33f7a22021-05-09 14:58:57 +000070#include <stdint.h>
Niels Möllere8e4dc42019-06-11 14:04:16 +020071#include <stdio.h>
72
Harald Alvestrandf33f7a22021-05-09 14:58:57 +000073#include <functional>
kwibergd1fe2812016-04-27 06:47:29 -070074#include <memory>
henrike@webrtc.org28e20752013-07-10 00:45:36 +000075#include <string>
76#include <vector>
77
Harald Alvestrandf33f7a22021-05-09 14:58:57 +000078#include "absl/base/attributes.h"
Harald Alvestrand31b03e92021-11-02 10:54:38 +000079#include "absl/strings/string_view.h"
Harald Alvestrandf33f7a22021-05-09 14:58:57 +000080#include "absl/types/optional.h"
Henrik Boström4c1e7cc2020-06-11 12:26:53 +020081#include "api/adaptation/resource.h"
Harald Alvestrand0ccfbd22021-04-08 07:25:04 +000082#include "api/async_dns_resolver.h"
Steve Anton10542f22019-01-11 09:11:00 -080083#include "api/async_resolver_factory.h"
Niels Möllerd377f042018-02-13 15:03:43 +010084#include "api/audio/audio_mixer.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020085#include "api/audio_codecs/audio_decoder_factory.h"
86#include "api/audio_codecs/audio_encoder_factory.h"
Niels Möllera6fe2612018-01-19 11:28:54 +010087#include "api/audio_options.h"
Steve Anton10542f22019-01-11 09:11:00 -080088#include "api/call/call_factory_interface.h"
Harald Alvestrandf33f7a22021-05-09 14:58:57 +000089#include "api/candidate.h"
Steve Anton10542f22019-01-11 09:11:00 -080090#include "api/crypto/crypto_options.h"
91#include "api/data_channel_interface.h"
Niels Möllerc4e80ad2019-09-13 15:53:46 +020092#include "api/dtls_transport_interface.h"
Ying Wang0dd1b0a2018-02-20 12:50:27 +010093#include "api/fec_controller.h"
Qingsi Wang25ec8882019-11-15 12:33:05 -080094#include "api/ice_transport_interface.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020095#include "api/jsep.h"
Steve Anton10542f22019-01-11 09:11:00 -080096#include "api/media_stream_interface.h"
Harald Alvestrandf33f7a22021-05-09 14:58:57 +000097#include "api/media_types.h"
Ivo Creusenc3d1f9b2019-11-01 11:47:51 +010098#include "api/neteq/neteq_factory.h"
Ying Wang0810a7c2019-04-10 13:48:24 +020099#include "api/network_state_predictor.h"
Patrik Höglund662e31f2019-09-05 14:35:04 +0200100#include "api/packet_socket_factory.h"
Steve Anton10542f22019-01-11 09:11:00 -0800101#include "api/rtc_error.h"
Danil Chapovalovb32f2c72019-05-22 13:39:25 +0200102#include "api/rtc_event_log/rtc_event_log_factory_interface.h"
Steve Anton10542f22019-01-11 09:11:00 -0800103#include "api/rtc_event_log_output.h"
Harald Alvestrandf33f7a22021-05-09 14:58:57 +0000104#include "api/rtp_parameters.h"
Steve Anton10542f22019-01-11 09:11:00 -0800105#include "api/rtp_receiver_interface.h"
106#include "api/rtp_sender_interface.h"
107#include "api/rtp_transceiver_interface.h"
Harald Alvestrandf33f7a22021-05-09 14:58:57 +0000108#include "api/scoped_refptr.h"
Niels Möllerc4e80ad2019-09-13 15:53:46 +0200109#include "api/sctp_transport_interface.h"
Henrik Boström831ae4e2020-07-29 12:04:00 +0200110#include "api/set_local_description_observer_interface.h"
Steve Anton10542f22019-01-11 09:11:00 -0800111#include "api/set_remote_description_observer_interface.h"
112#include "api/stats/rtc_stats_collector_callback.h"
113#include "api/stats_types.h"
Danil Chapovalov9435c612019-04-01 10:33:16 +0200114#include "api/task_queue/task_queue_factory.h"
Niels Möller0c4f7be2018-05-07 14:01:37 +0200115#include "api/transport/bitrate_settings.h"
Honghai Zhangf8998cf2019-10-14 11:27:50 -0700116#include "api/transport/enums.h"
Sebastian Janssondfce03a2018-05-18 18:05:10 +0200117#include "api/transport/network_control.h"
Per Kjellander2bca0082020-08-28 09:15:15 +0200118#include "api/transport/sctp_transport_factory_interface.h"
Erik Språng662678d2019-11-15 17:18:52 +0100119#include "api/transport/webrtc_key_value_config.h"
Steve Anton10542f22019-01-11 09:11:00 -0800120#include "api/turn_customizer.h"
Harald Alvestrandf33f7a22021-05-09 14:58:57 +0000121#include "api/video/video_bitrate_allocator_factory.h"
Vojin Ilic504fc192021-05-31 14:02:28 +0200122#include "call/rtp_transport_controller_send_factory_interface.h"
Steve Anton10542f22019-01-11 09:11:00 -0800123#include "media/base/media_config.h"
Niels Möllere24557f2019-09-19 11:36:35 +0200124#include "media/base/media_engine.h"
Niels Möller8366e172018-02-14 12:20:13 +0100125// TODO(bugs.webrtc.org/7447): We plan to provide a way to let applications
126// inject a PacketSocketFactory and/or NetworkManager, and not expose
Harald Alvestrandf33f7a22021-05-09 14:58:57 +0000127// PortAllocator in the PeerConnection api. This will let us remove nogncheck.
128#include "p2p/base/port.h" // nogncheck
Steve Anton10542f22019-01-11 09:11:00 -0800129#include "p2p/base/port_allocator.h" // nogncheck
Harald Alvestrandf33f7a22021-05-09 14:58:57 +0000130#include "rtc_base/network.h"
131#include "rtc_base/network_constants.h"
Taylor Brandstetter239ac8a2020-07-31 16:07:52 -0700132#include "rtc_base/network_monitor_factory.h"
Harald Alvestrandf33f7a22021-05-09 14:58:57 +0000133#include "rtc_base/ref_count.h"
Steve Anton10542f22019-01-11 09:11:00 -0800134#include "rtc_base/rtc_certificate.h"
135#include "rtc_base/rtc_certificate_generator.h"
136#include "rtc_base/socket_address.h"
137#include "rtc_base/ssl_certificate.h"
138#include "rtc_base/ssl_stream_adapter.h"
Mirko Bonadei276827c2018-10-16 14:13:50 +0200139#include "rtc_base/system/rtc_export.h"
Harald Alvestrandf33f7a22021-05-09 14:58:57 +0000140#include "rtc_base/thread.h"
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000141
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000142namespace rtc {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000143class Thread;
Yves Gerey665174f2018-06-19 15:03:05 +0200144} // namespace rtc
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000145
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000146namespace webrtc {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000147
148// MediaStream container interface.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000149class StreamCollectionInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000150 public:
151 // TODO(ronghuawu): Update the function names to c++ style, e.g. find -> Find.
152 virtual size_t count() = 0;
153 virtual MediaStreamInterface* at(size_t index) = 0;
154 virtual MediaStreamInterface* find(const std::string& label) = 0;
Yves Gerey665174f2018-06-19 15:03:05 +0200155 virtual MediaStreamTrackInterface* FindAudioTrack(const std::string& id) = 0;
156 virtual MediaStreamTrackInterface* FindVideoTrack(const std::string& id) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000157
158 protected:
159 // Dtor protected as objects shouldn't be deleted via this interface.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200160 ~StreamCollectionInterface() override = default;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000161};
162
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000163class StatsObserver : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000164 public:
nissee8abe3e2017-01-18 05:00:34 -0800165 virtual void OnComplete(const StatsReports& reports) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000166
167 protected:
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200168 ~StatsObserver() override = default;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000169};
170
Harald Alvestrandfa67aef2021-12-08 14:30:55 +0000171enum class SdpSemantics {
172 kPlanB_DEPRECATED,
173 kPlanB [[deprecated]] = kPlanB_DEPRECATED,
174 kUnifiedPlan
175};
Steve Anton79e79602017-11-20 10:25:56 -0800176
Mirko Bonadei66e76792019-04-02 11:33:59 +0200177class RTC_EXPORT PeerConnectionInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000178 public:
Jonas Olsson635474e2018-10-18 15:58:17 +0200179 // See https://w3c.github.io/webrtc-pc/#dom-rtcsignalingstate
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000180 enum SignalingState {
181 kStable,
182 kHaveLocalOffer,
183 kHaveLocalPrAnswer,
184 kHaveRemoteOffer,
185 kHaveRemotePrAnswer,
186 kClosed,
187 };
Harald Alvestrand31b03e92021-11-02 10:54:38 +0000188 static constexpr absl::string_view AsString(SignalingState);
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000189
Jonas Olsson635474e2018-10-18 15:58:17 +0200190 // See https://w3c.github.io/webrtc-pc/#dom-rtcicegatheringstate
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000191 enum IceGatheringState {
192 kIceGatheringNew,
193 kIceGatheringGathering,
194 kIceGatheringComplete
195 };
Harald Alvestrand31b03e92021-11-02 10:54:38 +0000196 static constexpr absl::string_view AsString(IceGatheringState state);
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000197
Jonas Olsson635474e2018-10-18 15:58:17 +0200198 // See https://w3c.github.io/webrtc-pc/#dom-rtcpeerconnectionstate
199 enum class PeerConnectionState {
200 kNew,
201 kConnecting,
202 kConnected,
203 kDisconnected,
204 kFailed,
205 kClosed,
206 };
Harald Alvestrand31b03e92021-11-02 10:54:38 +0000207 static constexpr absl::string_view AsString(PeerConnectionState state);
Jonas Olsson635474e2018-10-18 15:58:17 +0200208
209 // See https://w3c.github.io/webrtc-pc/#dom-rtciceconnectionstate
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000210 enum IceConnectionState {
211 kIceConnectionNew,
212 kIceConnectionChecking,
213 kIceConnectionConnected,
214 kIceConnectionCompleted,
215 kIceConnectionFailed,
216 kIceConnectionDisconnected,
217 kIceConnectionClosed,
Guo-wei Shieh3d564c12015-08-19 16:51:15 -0700218 kIceConnectionMax,
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000219 };
Harald Alvestrand31b03e92021-11-02 10:54:38 +0000220 static constexpr absl::string_view AsString(IceConnectionState state);
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000221
hnsl04833622017-01-09 08:35:45 -0800222 // TLS certificate policy.
223 enum TlsCertPolicy {
224 // For TLS based protocols, ensure the connection is secure by not
225 // circumventing certificate validation.
226 kTlsCertPolicySecure,
227 // For TLS based protocols, disregard security completely by skipping
228 // certificate validation. This is insecure and should never be used unless
229 // security is irrelevant in that particular context.
230 kTlsCertPolicyInsecureNoCheck,
231 };
232
Mirko Bonadei051cae52019-11-12 13:01:23 +0100233 struct RTC_EXPORT IceServer {
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200234 IceServer();
235 IceServer(const IceServer&);
236 ~IceServer();
237
Joachim Bauch7c4e7452015-05-28 23:06:30 +0200238 // TODO(jbauch): Remove uri when all code using it has switched to urls.
Emad Omaradab1d2d2017-06-16 15:43:11 -0700239 // List of URIs associated with this server. Valid formats are described
240 // in RFC7064 and RFC7065, and more may be added in the future. The "host"
241 // part of the URI may contain either an IP address or a hostname.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000242 std::string uri;
Joachim Bauch7c4e7452015-05-28 23:06:30 +0200243 std::vector<std::string> urls;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000244 std::string username;
245 std::string password;
hnsl04833622017-01-09 08:35:45 -0800246 TlsCertPolicy tls_cert_policy = kTlsCertPolicySecure;
Artem Titov0e61fdd2021-07-25 21:50:14 +0200247 // If the URIs in `urls` only contain IP addresses, this field can be used
Emad Omaradab1d2d2017-06-16 15:43:11 -0700248 // to indicate the hostname, which may be necessary for TLS (using the SNI
Artem Titov0e61fdd2021-07-25 21:50:14 +0200249 // extension). If `urls` itself contains the hostname, this isn't
Emad Omaradab1d2d2017-06-16 15:43:11 -0700250 // necessary.
251 std::string hostname;
Diogo Real1dca9d52017-08-29 12:18:32 -0700252 // List of protocols to be used in the TLS ALPN extension.
253 std::vector<std::string> tls_alpn_protocols;
Diogo Real7bd1f1b2017-09-08 12:50:41 -0700254 // List of elliptic curves to be used in the TLS elliptic curves extension.
255 std::vector<std::string> tls_elliptic_curves;
hnsl04833622017-01-09 08:35:45 -0800256
deadbeefd1a38b52016-12-10 13:15:33 -0800257 bool operator==(const IceServer& o) const {
258 return uri == o.uri && urls == o.urls && username == o.username &&
Emad Omaradab1d2d2017-06-16 15:43:11 -0700259 password == o.password && tls_cert_policy == o.tls_cert_policy &&
Diogo Real1dca9d52017-08-29 12:18:32 -0700260 hostname == o.hostname &&
Diogo Real7bd1f1b2017-09-08 12:50:41 -0700261 tls_alpn_protocols == o.tls_alpn_protocols &&
Sergey Silkin9c147dd2018-09-12 10:45:38 +0000262 tls_elliptic_curves == o.tls_elliptic_curves;
deadbeefd1a38b52016-12-10 13:15:33 -0800263 }
264 bool operator!=(const IceServer& o) const { return !(*this == o); }
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000265 };
266 typedef std::vector<IceServer> IceServers;
267
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000268 enum IceTransportsType {
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000269 // TODO(pthatcher): Rename these kTransporTypeXXX, but update
270 // Chromium at the same time.
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000271 kNone,
272 kRelay,
273 kNoHost,
274 kAll
275 };
276
Steve Antonab6ea6b2018-02-26 14:23:09 -0800277 // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-24#section-4.1.1
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000278 enum BundlePolicy {
279 kBundlePolicyBalanced,
280 kBundlePolicyMaxBundle,
281 kBundlePolicyMaxCompat
282 };
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000283
Steve Antonab6ea6b2018-02-26 14:23:09 -0800284 // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-24#section-4.1.1
Peter Thatcheraf55ccc2015-05-21 07:48:41 -0700285 enum RtcpMuxPolicy {
286 kRtcpMuxPolicyNegotiate,
287 kRtcpMuxPolicyRequire,
288 };
289
Jiayang Liucac1b382015-04-30 12:35:24 -0700290 enum TcpCandidatePolicy {
291 kTcpCandidatePolicyEnabled,
292 kTcpCandidatePolicyDisabled
293 };
294
honghaiz60347052016-05-31 18:29:12 -0700295 enum CandidateNetworkPolicy {
296 kCandidateNetworkPolicyAll,
297 kCandidateNetworkPolicyLowCost
298 };
299
Yves Gerey665174f2018-06-19 15:03:05 +0200300 enum ContinualGatheringPolicy { GATHER_ONCE, GATHER_CONTINUALLY };
honghaiz1f429e32015-09-28 07:57:34 -0700301
Niels Möller73d07742021-12-02 13:58:01 +0100302 struct PortAllocatorConfig {
303 // For min_port and max_port, 0 means not specified.
304 int min_port = 0;
305 int max_port = 0;
306 uint32_t flags = 0; // Same as kDefaultPortAllocatorFlags.
307 };
308
Honghai Zhangf7ddc062016-09-01 15:34:01 -0700309 enum class RTCConfigurationType {
310 // A configuration that is safer to use, despite not having the best
311 // performance. Currently this is the default configuration.
312 kSafe,
313 // An aggressive configuration that has better performance, although it
314 // may be riskier and may need extra support in the application.
315 kAggressive
316 };
317
Henrik Boström87713d02015-08-25 09:53:21 +0200318 // TODO(hbos): Change into class with private data and public getters.
nissec36b31b2016-04-11 23:25:29 -0700319 // TODO(nisse): In particular, accessing fields directly from an
320 // application is brittle, since the organization mirrors the
321 // organization of the implementation, which isn't stable. So we
322 // need getters and setters at least for fields which applications
323 // are interested in.
Mirko Bonadeiac194142018-10-22 17:08:37 +0200324 struct RTC_EXPORT RTCConfiguration {
Niels Möller71bdda02016-03-31 12:59:59 +0200325 // This struct is subject to reorganization, both for naming
326 // consistency, and to group settings to match where they are used
327 // in the implementation. To do that, we need getter and setter
328 // methods for all settings which are of interest to applications,
329 // Chrome in particular.
330
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200331 RTCConfiguration();
332 RTCConfiguration(const RTCConfiguration&);
333 explicit RTCConfiguration(RTCConfigurationType type);
334 ~RTCConfiguration();
Honghai Zhangbfd398c2016-08-30 22:07:42 -0700335
deadbeef293e9262017-01-11 12:28:30 -0800336 bool operator==(const RTCConfiguration& o) const;
337 bool operator!=(const RTCConfiguration& o) const;
338
Niels Möller6539f692018-01-18 08:58:50 +0100339 bool dscp() const { return media_config.enable_dscp; }
nissec36b31b2016-04-11 23:25:29 -0700340 void set_dscp(bool enable) { media_config.enable_dscp = enable; }
Niels Möller71bdda02016-03-31 12:59:59 +0200341
Niels Möller6539f692018-01-18 08:58:50 +0100342 bool cpu_adaptation() const {
Niels Möller1d7ecd22018-01-18 15:25:12 +0100343 return media_config.video.enable_cpu_adaptation;
nissec36b31b2016-04-11 23:25:29 -0700344 }
Niels Möller71bdda02016-03-31 12:59:59 +0200345 void set_cpu_adaptation(bool enable) {
Niels Möller1d7ecd22018-01-18 15:25:12 +0100346 media_config.video.enable_cpu_adaptation = enable;
Niels Möller71bdda02016-03-31 12:59:59 +0200347 }
348
Niels Möller6539f692018-01-18 08:58:50 +0100349 bool suspend_below_min_bitrate() const {
nissec36b31b2016-04-11 23:25:29 -0700350 return media_config.video.suspend_below_min_bitrate;
351 }
Niels Möller71bdda02016-03-31 12:59:59 +0200352 void set_suspend_below_min_bitrate(bool enable) {
nissec36b31b2016-04-11 23:25:29 -0700353 media_config.video.suspend_below_min_bitrate = enable;
Niels Möller71bdda02016-03-31 12:59:59 +0200354 }
355
Niels Möller6539f692018-01-18 08:58:50 +0100356 bool prerenderer_smoothing() const {
Niels Möller1d7ecd22018-01-18 15:25:12 +0100357 return media_config.video.enable_prerenderer_smoothing;
nissec36b31b2016-04-11 23:25:29 -0700358 }
Niels Möller71bdda02016-03-31 12:59:59 +0200359 void set_prerenderer_smoothing(bool enable) {
Niels Möller1d7ecd22018-01-18 15:25:12 +0100360 media_config.video.enable_prerenderer_smoothing = enable;
Niels Möller71bdda02016-03-31 12:59:59 +0200361 }
362
Niels Möller6539f692018-01-18 08:58:50 +0100363 bool experiment_cpu_load_estimator() const {
364 return media_config.video.experiment_cpu_load_estimator;
365 }
366 void set_experiment_cpu_load_estimator(bool enable) {
367 media_config.video.experiment_cpu_load_estimator = enable;
368 }
Ilya Nikolaevskiy97b4ee52018-05-28 10:24:22 +0200369
Jiawei Ou55718122018-11-09 13:17:39 -0800370 int audio_rtcp_report_interval_ms() const {
371 return media_config.audio.rtcp_report_interval_ms;
372 }
373 void set_audio_rtcp_report_interval_ms(int audio_rtcp_report_interval_ms) {
374 media_config.audio.rtcp_report_interval_ms =
375 audio_rtcp_report_interval_ms;
376 }
377
378 int video_rtcp_report_interval_ms() const {
379 return media_config.video.rtcp_report_interval_ms;
380 }
381 void set_video_rtcp_report_interval_ms(int video_rtcp_report_interval_ms) {
382 media_config.video.rtcp_report_interval_ms =
383 video_rtcp_report_interval_ms;
384 }
385
Niels Möller73d07742021-12-02 13:58:01 +0100386 // Settings for the port allcoator. Applied only if the port allocator is
387 // created by PeerConnectionFactory, not if it is injected with
388 // PeerConnectionDependencies
389 int min_port() const { return port_allocator_config.min_port; }
390 void set_min_port(int port) { port_allocator_config.min_port = port; }
391 int max_port() const { return port_allocator_config.max_port; }
392 void set_max_port(int port) { port_allocator_config.max_port = port; }
393 uint32_t port_allocator_flags() { return port_allocator_config.flags; }
394 void set_port_allocator_flags(uint32_t flags) {
395 port_allocator_config.flags = flags;
396 }
397
honghaiz4edc39c2015-09-01 09:53:56 -0700398 static const int kUndefined = -1;
399 // Default maximum number of packets in the audio jitter buffer.
Jakob Ivarsson647d5e62019-03-15 10:37:31 +0100400 static const int kAudioJitterBufferMaxPackets = 200;
Honghai Zhangaecd9822016-09-02 16:58:17 -0700401 // ICE connection receiving timeout for aggressive configuration.
402 static const int kAggressiveIceConnectionReceivingTimeout = 1000;
deadbeefb10f32f2017-02-08 01:38:21 -0800403
404 ////////////////////////////////////////////////////////////////////////
405 // The below few fields mirror the standard RTCConfiguration dictionary:
Steve Antonab6ea6b2018-02-26 14:23:09 -0800406 // https://w3c.github.io/webrtc-pc/#rtcconfiguration-dictionary
deadbeefb10f32f2017-02-08 01:38:21 -0800407 ////////////////////////////////////////////////////////////////////////
408
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000409 // TODO(pthatcher): Rename this ice_servers, but update Chromium
410 // at the same time.
411 IceServers servers;
deadbeefb10f32f2017-02-08 01:38:21 -0800412 // TODO(pthatcher): Rename this ice_transport_type, but update
413 // Chromium at the same time.
414 IceTransportsType type = kAll;
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700415 BundlePolicy bundle_policy = kBundlePolicyBalanced;
zhihuang4dfb8ce2016-11-23 10:30:12 -0800416 RtcpMuxPolicy rtcp_mux_policy = kRtcpMuxPolicyRequire;
deadbeefb10f32f2017-02-08 01:38:21 -0800417 std::vector<rtc::scoped_refptr<rtc::RTCCertificate>> certificates;
418 int ice_candidate_pool_size = 0;
419
420 //////////////////////////////////////////////////////////////////////////
421 // The below fields correspond to constraints from the deprecated
422 // constraints interface for constructing a PeerConnection.
423 //
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200424 // absl::optional fields can be "missing", in which case the implementation
deadbeefb10f32f2017-02-08 01:38:21 -0800425 // default will be used.
426 //////////////////////////////////////////////////////////////////////////
427
428 // If set to true, don't gather IPv6 ICE candidates.
429 // TODO(deadbeef): Remove this? IPv6 support has long stopped being
430 // experimental
431 bool disable_ipv6 = false;
432
zhihuangb09b3f92017-03-07 14:40:51 -0800433 // If set to true, don't gather IPv6 ICE candidates on Wi-Fi.
434 // Only intended to be used on specific devices. Certain phones disable IPv6
435 // when the screen is turned off and it would be better to just disable the
436 // IPv6 ICE candidates on Wi-Fi in those cases.
437 bool disable_ipv6_on_wifi = false;
438
deadbeefd21eab32017-07-26 16:50:11 -0700439 // By default, the PeerConnection will use a limited number of IPv6 network
440 // interfaces, in order to avoid too many ICE candidate pairs being created
441 // and delaying ICE completion.
442 //
443 // Can be set to INT_MAX to effectively disable the limit.
444 int max_ipv6_networks = cricket::kDefaultMaxIPv6Networks;
445
Daniel Lazarenko2870b0a2018-01-25 10:30:22 +0100446 // Exclude link-local network interfaces
Honghai Zhangf8998cf2019-10-14 11:27:50 -0700447 // from consideration for gathering ICE candidates.
Daniel Lazarenko2870b0a2018-01-25 10:30:22 +0100448 bool disable_link_local_networks = false;
449
deadbeefb10f32f2017-02-08 01:38:21 -0800450 // Minimum bitrate at which screencast video tracks will be encoded at.
451 // This means adding padding bits up to this bitrate, which can help
452 // when switching from a static scene to one with motion.
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200453 absl::optional<int> screencast_min_bitrate;
deadbeefb10f32f2017-02-08 01:38:21 -0800454
455 // Use new combined audio/video bandwidth estimation?
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200456 absl::optional<bool> combined_audio_video_bwe;
deadbeefb10f32f2017-02-08 01:38:21 -0800457
Harald Alvestrand50b95522021-11-18 10:01:06 +0000458 // TODO(bugs.webrtc.org/9891) - Move to crypto_options
459 // Can be used to disable DTLS-SRTP. This should never be done, but can be
460 // useful for testing purposes, for example in setting up a loopback call
461 // with a single PeerConnection.
462 absl::optional<bool> enable_dtls_srtp;
463
deadbeefb10f32f2017-02-08 01:38:21 -0800464 /////////////////////////////////////////////////
465 // The below fields are not part of the standard.
466 /////////////////////////////////////////////////
467
468 // Can be used to disable TCP candidate generation.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700469 TcpCandidatePolicy tcp_candidate_policy = kTcpCandidatePolicyEnabled;
deadbeefb10f32f2017-02-08 01:38:21 -0800470
471 // Can be used to avoid gathering candidates for a "higher cost" network,
472 // if a lower cost one exists. For example, if both Wi-Fi and cellular
473 // interfaces are available, this could be used to avoid using the cellular
474 // interface.
honghaiz60347052016-05-31 18:29:12 -0700475 CandidateNetworkPolicy candidate_network_policy =
476 kCandidateNetworkPolicyAll;
deadbeefb10f32f2017-02-08 01:38:21 -0800477
478 // The maximum number of packets that can be stored in the NetEq audio
479 // jitter buffer. Can be reduced to lower tolerated audio latency.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700480 int audio_jitter_buffer_max_packets = kAudioJitterBufferMaxPackets;
deadbeefb10f32f2017-02-08 01:38:21 -0800481
482 // Whether to use the NetEq "fast mode" which will accelerate audio quicker
483 // if it falls behind.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700484 bool audio_jitter_buffer_fast_accelerate = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800485
Jakob Ivarsson10403ae2018-11-27 15:45:20 +0100486 // The minimum delay in milliseconds for the audio jitter buffer.
487 int audio_jitter_buffer_min_delay_ms = 0;
488
Jakob Ivarsson53eae872019-01-10 15:58:36 +0100489 // Whether the audio jitter buffer adapts the delay to retransmitted
490 // packets.
491 bool audio_jitter_buffer_enable_rtx_handling = false;
492
deadbeefb10f32f2017-02-08 01:38:21 -0800493 // Timeout in milliseconds before an ICE candidate pair is considered to be
494 // "not receiving", after which a lower priority candidate pair may be
495 // selected.
496 int ice_connection_receiving_timeout = kUndefined;
497
498 // Interval in milliseconds at which an ICE "backup" candidate pair will be
499 // pinged. This is a candidate pair which is not actively in use, but may
500 // be switched to if the active candidate pair becomes unusable.
501 //
502 // This is relevant mainly to Wi-Fi/cell handoff; the application may not
503 // want this backup cellular candidate pair pinged frequently, since it
504 // consumes data/battery.
505 int ice_backup_candidate_pair_ping_interval = kUndefined;
506
507 // Can be used to enable continual gathering, which means new candidates
508 // will be gathered as network interfaces change. Note that if continual
509 // gathering is used, the candidate removal API should also be used, to
510 // avoid an ever-growing list of candidates.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700511 ContinualGatheringPolicy continual_gathering_policy = GATHER_ONCE;
deadbeefb10f32f2017-02-08 01:38:21 -0800512
513 // If set to true, candidate pairs will be pinged in order of most likely
514 // to work (which means using a TURN server, generally), rather than in
515 // standard priority order.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700516 bool prioritize_most_likely_ice_candidate_pairs = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800517
Niels Möller6daa2782018-01-23 10:37:42 +0100518 // Implementation defined settings. A public member only for the benefit of
519 // the implementation. Applications must not access it directly, and should
520 // instead use provided accessor methods, e.g., set_cpu_adaptation.
nissec36b31b2016-04-11 23:25:29 -0700521 struct cricket::MediaConfig media_config;
deadbeefb10f32f2017-02-08 01:38:21 -0800522
deadbeefb10f32f2017-02-08 01:38:21 -0800523 // If set to true, only one preferred TURN allocation will be used per
524 // network interface. UDP is preferred over TCP and IPv6 over IPv4. This
525 // can be used to cut down on the number of candidate pairings.
Honghai Zhangf8998cf2019-10-14 11:27:50 -0700526 // Deprecated. TODO(webrtc:11026) Remove this flag once the downstream
527 // dependency is removed.
Honghai Zhangb9e7b4a2016-06-30 20:52:02 -0700528 bool prune_turn_ports = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800529
Honghai Zhangf8998cf2019-10-14 11:27:50 -0700530 // The policy used to prune turn port.
531 PortPrunePolicy turn_port_prune_policy = NO_PRUNE;
532
533 PortPrunePolicy GetTurnPortPrunePolicy() const {
534 return prune_turn_ports ? PRUNE_BASED_ON_PRIORITY
535 : turn_port_prune_policy;
536 }
537
Taylor Brandstettere9851112016-07-01 11:11:13 -0700538 // If set to true, this means the ICE transport should presume TURN-to-TURN
539 // candidate pairs will succeed, even before a binding response is received.
deadbeefb10f32f2017-02-08 01:38:21 -0800540 // This can be used to optimize the initial connection time, since the DTLS
541 // handshake can begin immediately.
Taylor Brandstettere9851112016-07-01 11:11:13 -0700542 bool presume_writable_when_fully_relayed = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800543
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700544 // If true, "renomination" will be added to the ice options in the transport
545 // description.
deadbeefb10f32f2017-02-08 01:38:21 -0800546 // See: https://tools.ietf.org/html/draft-thatcher-ice-renomination-00
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700547 bool enable_ice_renomination = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800548
549 // If true, the ICE role is re-determined when the PeerConnection sets a
550 // local transport description that indicates an ICE restart.
551 //
552 // This is standard RFC5245 ICE behavior, but causes unnecessary role
553 // thrashing, so an application may wish to avoid it. This role
554 // re-determining was removed in ICEbis (ICE v2).
Honghai Zhangbfd398c2016-08-30 22:07:42 -0700555 bool redetermine_role_on_ice_restart = true;
deadbeefb10f32f2017-02-08 01:38:21 -0800556
Artem Titov0e61fdd2021-07-25 21:50:14 +0200557 // This flag is only effective when `continual_gathering_policy` is
Qingsi Wang1fe119f2019-05-31 16:55:33 -0700558 // GATHER_CONTINUALLY.
559 //
560 // If true, after the ICE transport type is changed such that new types of
561 // ICE candidates are allowed by the new transport type, e.g. from
562 // IceTransportsType::kRelay to IceTransportsType::kAll, candidates that
563 // have been gathered by the ICE transport but not matching the previous
564 // transport type and as a result not observed by PeerConnectionObserver,
565 // will be surfaced to the observer.
566 bool surface_ice_candidates_on_ice_transport_type_changed = false;
567
Qingsi Wange6826d22018-03-08 14:55:14 -0800568 // The following fields define intervals in milliseconds at which ICE
569 // connectivity checks are sent.
570 //
571 // We consider ICE is "strongly connected" for an agent when there is at
572 // least one candidate pair that currently succeeds in connectivity check
573 // from its direction i.e. sending a STUN ping and receives a STUN ping
574 // response, AND all candidate pairs have sent a minimum number of pings for
575 // connectivity (this number is implementation-specific). Otherwise, ICE is
576 // considered in "weak connectivity".
577 //
578 // Note that the above notion of strong and weak connectivity is not defined
579 // in RFC 5245, and they apply to our current ICE implementation only.
580 //
581 // 1) ice_check_interval_strong_connectivity defines the interval applied to
582 // ALL candidate pairs when ICE is strongly connected, and it overrides the
583 // default value of this interval in the ICE implementation;
584 // 2) ice_check_interval_weak_connectivity defines the counterpart for ALL
585 // pairs when ICE is weakly connected, and it overrides the default value of
586 // this interval in the ICE implementation;
587 // 3) ice_check_min_interval defines the minimal interval (equivalently the
588 // maximum rate) that overrides the above two intervals when either of them
589 // is less.
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200590 absl::optional<int> ice_check_interval_strong_connectivity;
591 absl::optional<int> ice_check_interval_weak_connectivity;
592 absl::optional<int> ice_check_min_interval;
deadbeefb10f32f2017-02-08 01:38:21 -0800593
Qingsi Wang22e623a2018-03-13 10:53:57 -0700594 // The min time period for which a candidate pair must wait for response to
595 // connectivity checks before it becomes unwritable. This parameter
596 // overrides the default value in the ICE implementation if set.
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200597 absl::optional<int> ice_unwritable_timeout;
Qingsi Wang22e623a2018-03-13 10:53:57 -0700598
599 // The min number of connectivity checks that a candidate pair must sent
600 // without receiving response before it becomes unwritable. This parameter
601 // overrides the default value in the ICE implementation if set.
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200602 absl::optional<int> ice_unwritable_min_checks;
Qingsi Wang22e623a2018-03-13 10:53:57 -0700603
Jiawei Ou9d4fd5552018-12-06 23:30:17 -0800604 // The min time period for which a candidate pair must wait for response to
605 // connectivity checks it becomes inactive. This parameter overrides the
606 // default value in the ICE implementation if set.
607 absl::optional<int> ice_inactive_timeout;
608
Qingsi Wangdb53f8e2018-02-20 14:45:49 -0800609 // The interval in milliseconds at which STUN candidates will resend STUN
610 // binding requests to keep NAT bindings open.
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200611 absl::optional<int> stun_candidate_keepalive_interval;
Qingsi Wangdb53f8e2018-02-20 14:45:49 -0800612
Jonas Orelandbdcee282017-10-10 14:01:40 +0200613 // Optional TurnCustomizer.
614 // With this class one can modify outgoing TURN messages.
615 // The object passed in must remain valid until PeerConnection::Close() is
616 // called.
617 webrtc::TurnCustomizer* turn_customizer = nullptr;
618
Qingsi Wang9a5c6f82018-02-01 10:38:40 -0800619 // Preferred network interface.
620 // A candidate pair on a preferred network has a higher precedence in ICE
621 // than one on an un-preferred network, regardless of priority or network
622 // cost.
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200623 absl::optional<rtc::AdapterType> network_preference;
Qingsi Wang9a5c6f82018-02-01 10:38:40 -0800624
Steve Anton79e79602017-11-20 10:25:56 -0800625 // Configure the SDP semantics used by this PeerConnection. Note that the
626 // WebRTC 1.0 specification requires kUnifiedPlan semantics. The
627 // RtpTransceiver API is only available with kUnifiedPlan semantics.
628 //
Steve Anton79e79602017-11-20 10:25:56 -0800629 // kUnifiedPlan will cause PeerConnection to create offers and answers with
630 // multiple m= sections where each m= section maps to one RtpSender and one
Steve Antonab6ea6b2018-02-26 14:23:09 -0800631 // RtpReceiver (an RtpTransceiver), either both audio or both video. This
632 // will also cause PeerConnection to ignore all but the first a=ssrc lines
633 // that form a Plan B stream.
Steve Anton79e79602017-11-20 10:25:56 -0800634 //
Harald Alvestrandfa67aef2021-12-08 14:30:55 +0000635 // kPlanB will cause PeerConnection to create offers and answers with at
636 // most one audio and one video m= section with multiple RtpSenders and
637 // RtpReceivers specified as multiple a=ssrc lines within the section. This
638 // will also cause PeerConnection to ignore all but the first m= section of
639 // the same media type.
640 //
641 // For users who have to interwork with legacy WebRTC implementations,
642 // it is possible to specify kPlanB until the code is finally removed.
Steve Anton79e79602017-11-20 10:25:56 -0800643 //
Steve Anton3acffc32018-04-12 17:21:03 -0700644 // For all other users, specify kUnifiedPlan.
Harald Alvestrandfa67aef2021-12-08 14:30:55 +0000645 SdpSemantics sdp_semantics = SdpSemantics::kPlanB_DEPRECATED;
Steve Anton79e79602017-11-20 10:25:56 -0800646
Benjamin Wright8c27cca2018-10-25 10:16:44 -0700647 // TODO(bugs.webrtc.org/9891) - Move to crypto_options or remove.
Zhi Huangb57e1692018-06-12 11:41:11 -0700648 // Actively reset the SRTP parameters whenever the DTLS transports
649 // underneath are reset for every offer/answer negotiation.
650 // This is only intended to be a workaround for crbug.com/835958
651 // WARNING: This would cause RTP/RTCP packets decryption failure if not used
652 // correctly. This flag will be deprecated soon. Do not rely on it.
653 bool active_reset_srtp_params = false;
654
Benjamin Wright8c27cca2018-10-25 10:16:44 -0700655 // Defines advanced optional cryptographic settings related to SRTP and
656 // frame encryption for native WebRTC. Setting this will overwrite any
657 // settings set in PeerConnectionFactory (which is deprecated).
658 absl::optional<CryptoOptions> crypto_options;
659
Johannes Kron89f874e2018-11-12 10:25:48 +0100660 // Configure if we should include the SDP attribute extmap-allow-mixed in
Emil Lundmark801c9992021-01-19 13:06:32 +0100661 // our offer on session level.
662 bool offer_extmap_allow_mixed = true;
Johannes Kron89f874e2018-11-12 10:25:48 +0100663
Jonas Oreland3c028422019-08-22 16:16:35 +0200664 // TURN logging identifier.
665 // This identifier is added to a TURN allocation
666 // and it intended to be used to be able to match client side
667 // logs with TURN server logs. It will not be added if it's an empty string.
668 std::string turn_logging_id;
669
Eldar Rello5ab79e62019-10-09 18:29:44 +0300670 // Added to be able to control rollout of this feature.
671 bool enable_implicit_rollback = false;
672
philipel16cec3b2019-10-25 12:23:02 +0200673 // Whether network condition based codec switching is allowed.
674 absl::optional<bool> allow_codec_switching;
675
Harald Alvestrand62166932020-10-26 08:30:41 +0000676 // The delay before doing a usage histogram report for long-lived
677 // PeerConnections. Used for testing only.
678 absl::optional<int> report_usage_pattern_delay_ms;
Derek Bailey6c127a12021-04-15 12:42:41 -0700679
680 // The ping interval (ms) when the connection is stable and writable. This
681 // parameter overrides the default value in the ICE implementation if set.
682 absl::optional<int> stable_writable_connection_ping_interval_ms;
Jonas Orelandc8fa1ee2021-08-25 08:58:04 +0200683
684 // Whether this PeerConnection will avoid VPNs (kAvoidVpn), prefer VPNs
685 // (kPreferVpn), only work over VPN (kOnlyUseVpn) or only work over non-VPN
686 // (kNeverUseVpn) interfaces. This controls which local interfaces the
687 // PeerConnection will prefer to connect over. Since VPN detection is not
688 // perfect, adherence to this preference cannot be guaranteed.
689 VpnPreference vpn_preference = VpnPreference::kDefault;
690
Jonas Oreland2ee0e642021-08-25 15:43:02 +0200691 // List of address/length subnets that should be treated like
692 // VPN (in case webrtc fails to auto detect them).
693 std::vector<rtc::NetworkMask> vpn_list;
694
Niels Möller73d07742021-12-02 13:58:01 +0100695 PortAllocatorConfig port_allocator_config;
696
deadbeef293e9262017-01-11 12:28:30 -0800697 //
698 // Don't forget to update operator== if adding something.
699 //
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000700 };
701
deadbeefb10f32f2017-02-08 01:38:21 -0800702 // See: https://www.w3.org/TR/webrtc/#idl-def-rtcofferansweroptions
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000703 struct RTCOfferAnswerOptions {
704 static const int kUndefined = -1;
705 static const int kMaxOfferToReceiveMedia = 1;
706
707 // The default value for constraint offerToReceiveX:true.
708 static const int kOfferToReceiveMediaTrue = 1;
709
Steve Antonab6ea6b2018-02-26 14:23:09 -0800710 // These options are left as backwards compatibility for clients who need
711 // "Plan B" semantics. Clients who have switched to "Unified Plan" semantics
712 // should use the RtpTransceiver API (AddTransceiver) instead.
deadbeefb10f32f2017-02-08 01:38:21 -0800713 //
714 // offer_to_receive_X set to 1 will cause a media description to be
715 // generated in the offer, even if no tracks of that type have been added.
716 // Values greater than 1 are treated the same.
717 //
718 // If set to 0, the generated directional attribute will not include the
719 // "recv" direction (meaning it will be "sendonly" or "inactive".
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700720 int offer_to_receive_video = kUndefined;
721 int offer_to_receive_audio = kUndefined;
deadbeefb10f32f2017-02-08 01:38:21 -0800722
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700723 bool voice_activity_detection = true;
724 bool ice_restart = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800725
726 // If true, will offer to BUNDLE audio/video/data together. Not to be
727 // confused with RTCP mux (multiplexing RTP and RTCP together).
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700728 bool use_rtp_mux = true;
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000729
Mirta Dvornicic479a3c02019-06-04 15:38:50 +0200730 // If true, "a=packetization:<payload_type> raw" attribute will be offered
731 // in the SDP for all video payload and accepted in the answer if offered.
732 bool raw_packetization_for_video = false;
733
Jonas Orelandfc1acd22018-08-24 10:58:37 +0200734 // This will apply to all video tracks with a Plan B SDP offer/answer.
735 int num_simulcast_layers = 1;
736
Harald Alvestrand4aa11922019-05-14 22:00:01 +0200737 // If true: Use SDP format from draft-ietf-mmusic-scdp-sdp-03
738 // If false: Use SDP format from draft-ietf-mmusic-sdp-sdp-26 or later
739 bool use_obsolete_sctp_sdp = false;
740
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700741 RTCOfferAnswerOptions() = default;
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000742
743 RTCOfferAnswerOptions(int offer_to_receive_video,
744 int offer_to_receive_audio,
745 bool voice_activity_detection,
746 bool ice_restart,
747 bool use_rtp_mux)
748 : offer_to_receive_video(offer_to_receive_video),
749 offer_to_receive_audio(offer_to_receive_audio),
750 voice_activity_detection(voice_activity_detection),
751 ice_restart(ice_restart),
752 use_rtp_mux(use_rtp_mux) {}
753 };
754
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000755 // Used by GetStats to decide which stats to include in the stats reports.
Artem Titov0e61fdd2021-07-25 21:50:14 +0200756 // `kStatsOutputLevelStandard` includes the standard stats for Javascript API;
757 // `kStatsOutputLevelDebug` includes both the standard stats and additional
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000758 // stats for debugging purposes.
759 enum StatsOutputLevel {
760 kStatsOutputLevelStandard,
761 kStatsOutputLevelDebug,
762 };
763
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000764 // Accessor methods to active local streams.
Steve Antonab6ea6b2018-02-26 14:23:09 -0800765 // This method is not supported with kUnifiedPlan semantics. Please use
766 // GetSenders() instead.
Yves Gerey665174f2018-06-19 15:03:05 +0200767 virtual rtc::scoped_refptr<StreamCollectionInterface> local_streams() = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000768
769 // Accessor methods to remote streams.
Steve Antonab6ea6b2018-02-26 14:23:09 -0800770 // This method is not supported with kUnifiedPlan semantics. Please use
771 // GetReceivers() instead.
Yves Gerey665174f2018-06-19 15:03:05 +0200772 virtual rtc::scoped_refptr<StreamCollectionInterface> remote_streams() = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000773
774 // Add a new MediaStream to be sent on this PeerConnection.
775 // Note that a SessionDescription negotiation is needed before the
776 // remote peer can receive the stream.
deadbeefb10f32f2017-02-08 01:38:21 -0800777 //
778 // This has been removed from the standard in favor of a track-based API. So,
779 // this is equivalent to simply calling AddTrack for each track within the
780 // stream, with the one difference that if "stream->AddTrack(...)" is called
781 // later, the PeerConnection will automatically pick up the new track. Though
782 // this functionality will be deprecated in the future.
Steve Antonab6ea6b2018-02-26 14:23:09 -0800783 //
784 // This method is not supported with kUnifiedPlan semantics. Please use
785 // AddTrack instead.
perkj@webrtc.orgfd0efb62014-11-06 12:16:36 +0000786 virtual bool AddStream(MediaStreamInterface* stream) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000787
788 // Remove a MediaStream from this PeerConnection.
deadbeefb10f32f2017-02-08 01:38:21 -0800789 // Note that a SessionDescription negotiation is needed before the
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000790 // remote peer is notified.
Steve Antonab6ea6b2018-02-26 14:23:09 -0800791 //
792 // This method is not supported with kUnifiedPlan semantics. Please use
793 // RemoveTrack instead.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000794 virtual void RemoveStream(MediaStreamInterface* stream) = 0;
795
deadbeefb10f32f2017-02-08 01:38:21 -0800796 // Add a new MediaStreamTrack to be sent on this PeerConnection, and return
Steve Antonf9381f02017-12-14 10:23:57 -0800797 // the newly created RtpSender. The RtpSender will be associated with the
Artem Titov0e61fdd2021-07-25 21:50:14 +0200798 // streams specified in the `stream_ids` list.
deadbeefb10f32f2017-02-08 01:38:21 -0800799 //
Steve Antonf9381f02017-12-14 10:23:57 -0800800 // Errors:
Artem Titov0e61fdd2021-07-25 21:50:14 +0200801 // - INVALID_PARAMETER: `track` is null, has a kind other than audio or video,
Steve Antonf9381f02017-12-14 10:23:57 -0800802 // or a sender already exists for the track.
803 // - INVALID_STATE: The PeerConnection is closed.
Steve Anton2d6c76a2018-01-05 17:10:52 -0800804 virtual RTCErrorOr<rtc::scoped_refptr<RtpSenderInterface>> AddTrack(
805 rtc::scoped_refptr<MediaStreamTrackInterface> track,
Niels Möller7b04a912019-09-13 15:41:21 +0200806 const std::vector<std::string>& stream_ids) = 0;
deadbeefe1f9d832016-01-14 15:35:42 -0800807
808 // Remove an RtpSender from this PeerConnection.
809 // Returns true on success.
Steve Anton24db5732018-07-23 10:27:33 -0700810 // TODO(steveanton): Replace with signature that returns RTCError.
Niels Möller7b04a912019-09-13 15:41:21 +0200811 virtual bool RemoveTrack(RtpSenderInterface* sender) = 0;
Steve Anton24db5732018-07-23 10:27:33 -0700812
813 // Plan B semantics: Removes the RtpSender from this PeerConnection.
814 // Unified Plan semantics: Stop sending on the RtpSender and mark the
815 // corresponding RtpTransceiver direction as no longer sending.
816 //
817 // Errors:
Artem Titov0e61fdd2021-07-25 21:50:14 +0200818 // - INVALID_PARAMETER: `sender` is null or (Plan B only) the sender is not
Steve Anton24db5732018-07-23 10:27:33 -0700819 // associated with this PeerConnection.
820 // - INVALID_STATE: PeerConnection is closed.
821 // TODO(bugs.webrtc.org/9534): Rename to RemoveTrack once the other signature
822 // is removed.
823 virtual RTCError RemoveTrackNew(
824 rtc::scoped_refptr<RtpSenderInterface> sender);
deadbeefe1f9d832016-01-14 15:35:42 -0800825
Steve Anton9158ef62017-11-27 13:01:52 -0800826 // AddTransceiver creates a new RtpTransceiver and adds it to the set of
827 // transceivers. Adding a transceiver will cause future calls to CreateOffer
828 // to add a media description for the corresponding transceiver.
829 //
Artem Titov0e61fdd2021-07-25 21:50:14 +0200830 // The initial value of `mid` in the returned transceiver is null. Setting a
Steve Anton9158ef62017-11-27 13:01:52 -0800831 // new session description may change it to a non-null value.
832 //
833 // https://w3c.github.io/webrtc-pc/#dom-rtcpeerconnection-addtransceiver
834 //
835 // Optionally, an RtpTransceiverInit structure can be specified to configure
836 // the transceiver from construction. If not specified, the transceiver will
837 // default to having a direction of kSendRecv and not be part of any streams.
838 //
839 // These methods are only available when Unified Plan is enabled (see
840 // RTCConfiguration).
841 //
842 // Common errors:
843 // - INTERNAL_ERROR: The configuration does not have Unified Plan enabled.
Steve Anton9158ef62017-11-27 13:01:52 -0800844
845 // Adds a transceiver with a sender set to transmit the given track. The kind
846 // of the transceiver (and sender/receiver) will be derived from the kind of
847 // the track.
848 // Errors:
Artem Titov0e61fdd2021-07-25 21:50:14 +0200849 // - INVALID_PARAMETER: `track` is null.
Steve Anton9158ef62017-11-27 13:01:52 -0800850 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>>
Niels Möller7b04a912019-09-13 15:41:21 +0200851 AddTransceiver(rtc::scoped_refptr<MediaStreamTrackInterface> track) = 0;
Steve Anton9158ef62017-11-27 13:01:52 -0800852 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>>
853 AddTransceiver(rtc::scoped_refptr<MediaStreamTrackInterface> track,
Niels Möller7b04a912019-09-13 15:41:21 +0200854 const RtpTransceiverInit& init) = 0;
Steve Anton9158ef62017-11-27 13:01:52 -0800855
856 // Adds a transceiver with the given kind. Can either be MEDIA_TYPE_AUDIO or
857 // MEDIA_TYPE_VIDEO.
858 // Errors:
Artem Titov0e61fdd2021-07-25 21:50:14 +0200859 // - INVALID_PARAMETER: `media_type` is not MEDIA_TYPE_AUDIO or
Steve Anton9158ef62017-11-27 13:01:52 -0800860 // MEDIA_TYPE_VIDEO.
861 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>>
Niels Möller7b04a912019-09-13 15:41:21 +0200862 AddTransceiver(cricket::MediaType media_type) = 0;
Steve Anton9158ef62017-11-27 13:01:52 -0800863 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>>
Niels Möller7b04a912019-09-13 15:41:21 +0200864 AddTransceiver(cricket::MediaType media_type,
865 const RtpTransceiverInit& init) = 0;
deadbeefb10f32f2017-02-08 01:38:21 -0800866
867 // Creates a sender without a track. Can be used for "early media"/"warmup"
868 // use cases, where the application may want to negotiate video attributes
869 // before a track is available to send.
870 //
871 // The standard way to do this would be through "addTransceiver", but we
872 // don't support that API yet.
873 //
Artem Titov0e61fdd2021-07-25 21:50:14 +0200874 // `kind` must be "audio" or "video".
deadbeefb10f32f2017-02-08 01:38:21 -0800875 //
Artem Titov0e61fdd2021-07-25 21:50:14 +0200876 // `stream_id` is used to populate the msid attribute; if empty, one will
deadbeefbd7d8f72015-12-18 16:58:44 -0800877 // be generated automatically.
Steve Antonab6ea6b2018-02-26 14:23:09 -0800878 //
879 // This method is not supported with kUnifiedPlan semantics. Please use
880 // AddTransceiver instead.
deadbeeffac06552015-11-25 11:26:01 -0800881 virtual rtc::scoped_refptr<RtpSenderInterface> CreateSender(
deadbeefbd7d8f72015-12-18 16:58:44 -0800882 const std::string& kind,
Niels Möller7b04a912019-09-13 15:41:21 +0200883 const std::string& stream_id) = 0;
deadbeeffac06552015-11-25 11:26:01 -0800884
Steve Antonab6ea6b2018-02-26 14:23:09 -0800885 // If Plan B semantics are specified, gets all RtpSenders, created either
886 // through AddStream, AddTrack, or CreateSender. All senders of a specific
887 // media type share the same media description.
888 //
889 // If Unified Plan semantics are specified, gets the RtpSender for each
890 // RtpTransceiver.
deadbeef70ab1a12015-09-28 16:53:55 -0700891 virtual std::vector<rtc::scoped_refptr<RtpSenderInterface>> GetSenders()
Niels Möller7b04a912019-09-13 15:41:21 +0200892 const = 0;
deadbeef70ab1a12015-09-28 16:53:55 -0700893
Steve Antonab6ea6b2018-02-26 14:23:09 -0800894 // If Plan B semantics are specified, gets all RtpReceivers created when a
895 // remote description is applied. All receivers of a specific media type share
896 // the same media description. It is also possible to have a media description
897 // with no associated RtpReceivers, if the directional attribute does not
898 // indicate that the remote peer is sending any media.
deadbeefb10f32f2017-02-08 01:38:21 -0800899 //
Steve Antonab6ea6b2018-02-26 14:23:09 -0800900 // If Unified Plan semantics are specified, gets the RtpReceiver for each
901 // RtpTransceiver.
deadbeef70ab1a12015-09-28 16:53:55 -0700902 virtual std::vector<rtc::scoped_refptr<RtpReceiverInterface>> GetReceivers()
Niels Möller7b04a912019-09-13 15:41:21 +0200903 const = 0;
deadbeef70ab1a12015-09-28 16:53:55 -0700904
Steve Anton9158ef62017-11-27 13:01:52 -0800905 // Get all RtpTransceivers, created either through AddTransceiver, AddTrack or
906 // by a remote description applied with SetRemoteDescription.
Steve Antonab6ea6b2018-02-26 14:23:09 -0800907 //
Steve Anton9158ef62017-11-27 13:01:52 -0800908 // Note: This method is only available when Unified Plan is enabled (see
909 // RTCConfiguration).
910 virtual std::vector<rtc::scoped_refptr<RtpTransceiverInterface>>
Niels Möller7b04a912019-09-13 15:41:21 +0200911 GetTransceivers() const = 0;
Steve Anton9158ef62017-11-27 13:01:52 -0800912
Henrik Boström1df1bf82018-03-20 13:24:20 +0100913 // The legacy non-compliant GetStats() API. This correspond to the
914 // callback-based version of getStats() in JavaScript. The returned metrics
915 // are UNDOCUMENTED and many of them rely on implementation-specific details.
916 // The goal is to DELETE THIS VERSION but we can't today because it is heavily
917 // relied upon by third parties. See https://crbug.com/822696.
918 //
919 // This version is wired up into Chrome. Any stats implemented are
920 // automatically exposed to the Web Platform. This has BYPASSED the Chrome
921 // release processes for years and lead to cross-browser incompatibility
922 // issues and web application reliance on Chrome-only behavior.
923 //
924 // This API is in "maintenance mode", serious regressions should be fixed but
925 // adding new stats is highly discouraged.
926 //
927 // TODO(hbos): Deprecate and remove this when third parties have migrated to
928 // the spec-compliant GetStats() API. https://crbug.com/822696
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000929 virtual bool GetStats(StatsObserver* observer,
Henrik Boström1df1bf82018-03-20 13:24:20 +0100930 MediaStreamTrackInterface* track, // Optional
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000931 StatsOutputLevel level) = 0;
Henrik Boström1df1bf82018-03-20 13:24:20 +0100932 // The spec-compliant GetStats() API. This correspond to the promise-based
933 // version of getStats() in JavaScript. Implementation status is described in
934 // api/stats/rtcstats_objects.h. For more details on stats, see spec:
935 // https://w3c.github.io/webrtc-pc/#dom-rtcpeerconnection-getstats
936 // TODO(hbos): Takes shared ownership, use rtc::scoped_refptr<> instead. This
937 // requires stop overriding the current version in third party or making third
938 // party calls explicit to avoid ambiguity during switch. Make the future
939 // version abstract as soon as third party projects implement it.
Niels Möller7b04a912019-09-13 15:41:21 +0200940 virtual void GetStats(RTCStatsCollectorCallback* callback) = 0;
Henrik Boström1df1bf82018-03-20 13:24:20 +0100941 // Spec-compliant getStats() performing the stats selection algorithm with the
942 // sender. https://w3c.github.io/webrtc-pc/#dom-rtcrtpsender-getstats
Henrik Boström1df1bf82018-03-20 13:24:20 +0100943 virtual void GetStats(
944 rtc::scoped_refptr<RtpSenderInterface> selector,
Niels Möller7b04a912019-09-13 15:41:21 +0200945 rtc::scoped_refptr<RTCStatsCollectorCallback> callback) = 0;
Henrik Boström1df1bf82018-03-20 13:24:20 +0100946 // Spec-compliant getStats() performing the stats selection algorithm with the
947 // receiver. https://w3c.github.io/webrtc-pc/#dom-rtcrtpreceiver-getstats
Henrik Boström1df1bf82018-03-20 13:24:20 +0100948 virtual void GetStats(
949 rtc::scoped_refptr<RtpReceiverInterface> selector,
Niels Möller7b04a912019-09-13 15:41:21 +0200950 rtc::scoped_refptr<RTCStatsCollectorCallback> callback) = 0;
Steve Antonab6ea6b2018-02-26 14:23:09 -0800951 // Clear cached stats in the RTCStatsCollector.
Harald Alvestrand89061872018-01-02 14:08:34 +0100952 // Exposed for testing while waiting for automatic cache clear to work.
953 // https://bugs.webrtc.org/8693
954 virtual void ClearStatsCache() {}
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000955
deadbeefb10f32f2017-02-08 01:38:21 -0800956 // Create a data channel with the provided config, or default config if none
957 // is provided. Note that an offer/answer negotiation is still necessary
958 // before the data channel can be used.
959 //
960 // Also, calling CreateDataChannel is the only way to get a data "m=" section
961 // in SDP, so it should be done before CreateOffer is called, if the
962 // application plans to use data channels.
Harald Alvestranda9af50f2021-05-21 13:33:51 +0000963 virtual RTCErrorOr<rtc::scoped_refptr<DataChannelInterface>>
964 CreateDataChannelOrError(const std::string& label,
965 const DataChannelInit* config) {
966 return RTCError(RTCErrorType::INTERNAL_ERROR, "dummy function called");
967 }
968 // TODO(crbug.com/788659): Remove "virtual" below and default implementation
969 // above once mock in Chrome is fixed.
970 ABSL_DEPRECATED("Use CreateDataChannelOrError")
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000971 virtual rtc::scoped_refptr<DataChannelInterface> CreateDataChannel(
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000972 const std::string& label,
Harald Alvestranda9af50f2021-05-21 13:33:51 +0000973 const DataChannelInit* config) {
974 auto result = CreateDataChannelOrError(label, config);
975 if (!result.ok()) {
976 return nullptr;
977 } else {
978 return result.MoveValue();
979 }
980 }
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000981
Taylor Brandstetterc88fe702020-08-03 16:36:16 -0700982 // NOTE: For the following 6 methods, it's only safe to dereference the
983 // SessionDescriptionInterface on signaling_thread() (for example, calling
984 // ToString).
985
deadbeefb10f32f2017-02-08 01:38:21 -0800986 // Returns the more recently applied description; "pending" if it exists, and
987 // otherwise "current". See below.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000988 virtual const SessionDescriptionInterface* local_description() const = 0;
989 virtual const SessionDescriptionInterface* remote_description() const = 0;
deadbeefb10f32f2017-02-08 01:38:21 -0800990
deadbeeffe4a8a42016-12-20 17:56:17 -0800991 // A "current" description the one currently negotiated from a complete
992 // offer/answer exchange.
Niels Möller7b04a912019-09-13 15:41:21 +0200993 virtual const SessionDescriptionInterface* current_local_description()
994 const = 0;
995 virtual const SessionDescriptionInterface* current_remote_description()
996 const = 0;
deadbeefb10f32f2017-02-08 01:38:21 -0800997
deadbeeffe4a8a42016-12-20 17:56:17 -0800998 // A "pending" description is one that's part of an incomplete offer/answer
999 // exchange (thus, either an offer or a pranswer). Once the offer/answer
1000 // exchange is finished, the "pending" description will become "current".
Niels Möller7b04a912019-09-13 15:41:21 +02001001 virtual const SessionDescriptionInterface* pending_local_description()
1002 const = 0;
1003 virtual const SessionDescriptionInterface* pending_remote_description()
1004 const = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001005
Henrik Boström79b69802019-07-18 11:16:56 +02001006 // Tells the PeerConnection that ICE should be restarted. This triggers a need
1007 // for negotiation and subsequent CreateOffer() calls will act as if
1008 // RTCOfferAnswerOptions::ice_restart is true.
1009 // https://w3c.github.io/webrtc-pc/#dom-rtcpeerconnection-restartice
1010 // TODO(hbos): Remove default implementation when downstream projects
1011 // implement this.
Niels Möller7b04a912019-09-13 15:41:21 +02001012 virtual void RestartIce() = 0;
Henrik Boström79b69802019-07-18 11:16:56 +02001013
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001014 // Create a new offer.
1015 // The CreateSessionDescriptionObserver callback will be called when done.
1016 virtual void CreateOffer(CreateSessionDescriptionObserver* observer,
Niels Möllerf06f9232018-08-07 12:32:18 +02001017 const RTCOfferAnswerOptions& options) = 0;
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +00001018
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001019 // Create an answer to an offer.
1020 // The CreateSessionDescriptionObserver callback will be called when done.
1021 virtual void CreateAnswer(CreateSessionDescriptionObserver* observer,
Niels Möllerf06f9232018-08-07 12:32:18 +02001022 const RTCOfferAnswerOptions& options) = 0;
htaa2a49d92016-03-04 02:51:39 -08001023
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001024 // Sets the local session description.
Henrik Boström831ae4e2020-07-29 12:04:00 +02001025 //
1026 // According to spec, the local session description MUST be the same as was
1027 // returned by CreateOffer() or CreateAnswer() or else the operation should
1028 // fail. Our implementation however allows some amount of "SDP munging", but
1029 // please note that this is HIGHLY DISCOURAGED. If you do not intent to munge
Artem Titov0e61fdd2021-07-25 21:50:14 +02001030 // SDP, the method below that doesn't take `desc` as an argument will create
Henrik Boström831ae4e2020-07-29 12:04:00 +02001031 // the offer or answer for you.
1032 //
1033 // The observer is invoked as soon as the operation completes, which could be
1034 // before or after the SetLocalDescription() method has exited.
1035 virtual void SetLocalDescription(
1036 std::unique_ptr<SessionDescriptionInterface> desc,
1037 rtc::scoped_refptr<SetLocalDescriptionObserverInterface> observer) {}
1038 // Creates an offer or answer (depending on current signaling state) and sets
1039 // it as the local session description.
1040 //
1041 // The observer is invoked as soon as the operation completes, which could be
1042 // before or after the SetLocalDescription() method has exited.
1043 virtual void SetLocalDescription(
1044 rtc::scoped_refptr<SetLocalDescriptionObserverInterface> observer) {}
1045 // Like SetLocalDescription() above, but the observer is invoked with a delay
1046 // after the operation completes. This helps avoid recursive calls by the
1047 // observer but also makes it possible for states to change in-between the
1048 // operation completing and the observer getting called. This makes them racy
1049 // for synchronizing peer connection states to the application.
1050 // TODO(https://crbug.com/webrtc/11798): Delete these methods in favor of the
1051 // ones taking SetLocalDescriptionObserverInterface as argument.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001052 virtual void SetLocalDescription(SetSessionDescriptionObserver* observer,
1053 SessionDescriptionInterface* desc) = 0;
Henrik Boström4e196702019-10-30 10:35:50 +01001054 virtual void SetLocalDescription(SetSessionDescriptionObserver* observer) {}
Henrik Boström831ae4e2020-07-29 12:04:00 +02001055
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001056 // Sets the remote session description.
Henrik Boström831ae4e2020-07-29 12:04:00 +02001057 //
1058 // (Unlike "SDP munging" before SetLocalDescription(), modifying a remote
1059 // offer or answer is allowed by the spec.)
1060 //
1061 // The observer is invoked as soon as the operation completes, which could be
1062 // before or after the SetRemoteDescription() method has exited.
Henrik Boström31638672017-11-23 17:48:32 +01001063 virtual void SetRemoteDescription(
1064 std::unique_ptr<SessionDescriptionInterface> desc,
Niels Möller7b04a912019-09-13 15:41:21 +02001065 rtc::scoped_refptr<SetRemoteDescriptionObserverInterface> observer) = 0;
Henrik Boström831ae4e2020-07-29 12:04:00 +02001066 // Like SetRemoteDescription() above, but the observer is invoked with a delay
1067 // after the operation completes. This helps avoid recursive calls by the
1068 // observer but also makes it possible for states to change in-between the
1069 // operation completing and the observer getting called. This makes them racy
1070 // for synchronizing peer connection states to the application.
1071 // TODO(https://crbug.com/webrtc/11798): Delete this method in favor of the
1072 // ones taking SetRemoteDescriptionObserverInterface as argument.
1073 virtual void SetRemoteDescription(SetSessionDescriptionObserver* observer,
1074 SessionDescriptionInterface* desc) {}
deadbeefb10f32f2017-02-08 01:38:21 -08001075
Henrik Boströme574a312020-08-25 10:20:11 +02001076 // According to spec, we must only fire "negotiationneeded" if the Operations
1077 // Chain is empty. This method takes care of validating an event previously
1078 // generated with PeerConnectionObserver::OnNegotiationNeededEvent() to make
1079 // sure that even if there was a delay (e.g. due to a PostTask) between the
1080 // event being generated and the time of firing, the Operations Chain is empty
1081 // and the event is still valid to be fired.
1082 virtual bool ShouldFireNegotiationNeededEvent(uint32_t event_id) {
1083 return true;
1084 }
1085
Niels Möller7b04a912019-09-13 15:41:21 +02001086 virtual PeerConnectionInterface::RTCConfiguration GetConfiguration() = 0;
deadbeef293e9262017-01-11 12:28:30 -08001087
Artem Titov0e61fdd2021-07-25 21:50:14 +02001088 // Sets the PeerConnection's global configuration to `config`.
deadbeef293e9262017-01-11 12:28:30 -08001089 //
Artem Titov0e61fdd2021-07-25 21:50:14 +02001090 // The members of `config` that may be changed are `type`, `servers`,
1091 // `ice_candidate_pool_size` and `prune_turn_ports` (though the candidate
deadbeef293e9262017-01-11 12:28:30 -08001092 // pool size can't be changed after the first call to SetLocalDescription).
1093 // Note that this means the BUNDLE and RTCP-multiplexing policies cannot be
1094 // changed with this method.
1095 //
deadbeefa67696b2015-09-29 11:56:26 -07001096 // Any changes to STUN/TURN servers or ICE candidate policy will affect the
1097 // next gathering phase, and cause the next call to createOffer to generate
deadbeef293e9262017-01-11 12:28:30 -08001098 // new ICE credentials, as described in JSEP. This also occurs when
Artem Titov0e61fdd2021-07-25 21:50:14 +02001099 // `prune_turn_ports` changes, for the same reasoning.
deadbeef293e9262017-01-11 12:28:30 -08001100 //
Artem Titov0e61fdd2021-07-25 21:50:14 +02001101 // If an error occurs, returns false and populates `error` if non-null:
1102 // - INVALID_MODIFICATION if `config` contains a modified parameter other
deadbeef293e9262017-01-11 12:28:30 -08001103 // than one of the parameters listed above.
Artem Titov0e61fdd2021-07-25 21:50:14 +02001104 // - INVALID_RANGE if `ice_candidate_pool_size` is out of range.
deadbeef293e9262017-01-11 12:28:30 -08001105 // - SYNTAX_ERROR if parsing an ICE server URL failed.
Artem Titov0e61fdd2021-07-25 21:50:14 +02001106 // - INVALID_PARAMETER if a TURN server is missing `username` or `password`.
deadbeef293e9262017-01-11 12:28:30 -08001107 // - INTERNAL_ERROR if an unexpected error occurred.
1108 //
Niels Möller2579f0c2019-08-19 09:58:17 +02001109 // TODO(nisse): Make this pure virtual once all Chrome subclasses of
1110 // PeerConnectionInterface implement it.
1111 virtual RTCError SetConfiguration(
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001112 const PeerConnectionInterface::RTCConfiguration& config);
deadbeefb10f32f2017-02-08 01:38:21 -08001113
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001114 // Provides a remote candidate to the ICE Agent.
Artem Titov0e61fdd2021-07-25 21:50:14 +02001115 // A copy of the `candidate` will be created and added to the remote
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001116 // description. So the caller of this method still has the ownership of the
Artem Titov0e61fdd2021-07-25 21:50:14 +02001117 // `candidate`.
Henrik Boströmee6f4f62019-11-06 12:36:12 +01001118 // TODO(hbos): The spec mandates chaining this operation onto the operations
1119 // chain; deprecate and remove this version in favor of the callback-based
1120 // signature.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001121 virtual bool AddIceCandidate(const IceCandidateInterface* candidate) = 0;
Henrik Boströmee6f4f62019-11-06 12:36:12 +01001122 // TODO(hbos): Remove default implementation once implemented by downstream
1123 // projects.
1124 virtual void AddIceCandidate(std::unique_ptr<IceCandidateInterface> candidate,
1125 std::function<void(RTCError)> callback) {}
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001126
deadbeefb10f32f2017-02-08 01:38:21 -08001127 // Removes a group of remote candidates from the ICE agent. Needed mainly for
1128 // continual gathering, to avoid an ever-growing list of candidates as
Taylor Brandstetter9e9bf752021-01-26 14:55:38 -08001129 // networks come and go. Note that the candidates' transport_name must be set
1130 // to the MID of the m= section that generated the candidate.
1131 // TODO(bugs.webrtc.org/8395): Use IceCandidateInterface instead of
1132 // cricket::Candidate, which would avoid the transport_name oddity.
Honghai Zhang7fb69db2016-03-14 11:59:18 -07001133 virtual bool RemoveIceCandidates(
Niels Möller7b04a912019-09-13 15:41:21 +02001134 const std::vector<cricket::Candidate>& candidates) = 0;
Honghai Zhang7fb69db2016-03-14 11:59:18 -07001135
zstein4b979802017-06-02 14:37:37 -07001136 // SetBitrate limits the bandwidth allocated for all RTP streams sent by
1137 // this PeerConnection. Other limitations might affect these limits and
1138 // are respected (for example "b=AS" in SDP).
1139 //
Artem Titov0e61fdd2021-07-25 21:50:14 +02001140 // Setting `current_bitrate_bps` will reset the current bitrate estimate
zstein4b979802017-06-02 14:37:37 -07001141 // to the provided value.
Niels Möller9ad1f6f2020-07-13 10:25:41 +02001142 virtual RTCError SetBitrate(const BitrateSettings& bitrate) = 0;
zstein4b979802017-06-02 14:37:37 -07001143
henrika5f6bf242017-11-01 11:06:56 +01001144 // Enable/disable playout of received audio streams. Enabled by default. Note
1145 // that even if playout is enabled, streams will only be played out if the
Artem Titov0e61fdd2021-07-25 21:50:14 +02001146 // appropriate SDP is also applied. Setting `playout` to false will stop
henrika5f6bf242017-11-01 11:06:56 +01001147 // playout of the underlying audio device but starts a task which will poll
1148 // for audio data every 10ms to ensure that audio processing happens and the
1149 // audio statistics are updated.
henrika5f6bf242017-11-01 11:06:56 +01001150 virtual void SetAudioPlayout(bool playout) {}
1151
1152 // Enable/disable recording of transmitted audio streams. Enabled by default.
1153 // Note that even if recording is enabled, streams will only be recorded if
1154 // the appropriate SDP is also applied.
henrika5f6bf242017-11-01 11:06:56 +01001155 virtual void SetAudioRecording(bool recording) {}
1156
Harald Alvestrandad88c882018-11-28 16:47:46 +01001157 // Looks up the DtlsTransport associated with a MID value.
1158 // In the Javascript API, DtlsTransport is a property of a sender, but
1159 // because the PeerConnection owns the DtlsTransport in this implementation,
1160 // it is better to look them up on the PeerConnection.
1161 virtual rtc::scoped_refptr<DtlsTransportInterface> LookupDtlsTransportByMid(
Niels Möller7b04a912019-09-13 15:41:21 +02001162 const std::string& mid) = 0;
Harald Alvestrandad88c882018-11-28 16:47:46 +01001163
Harald Alvestrandc85328f2019-02-28 07:51:00 +01001164 // Returns the SCTP transport, if any.
Niels Möller7b04a912019-09-13 15:41:21 +02001165 virtual rtc::scoped_refptr<SctpTransportInterface> GetSctpTransport()
1166 const = 0;
Harald Alvestrandc85328f2019-02-28 07:51:00 +01001167
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001168 // Returns the current SignalingState.
1169 virtual SignalingState signaling_state() = 0;
Taylor Brandstettercb423c42017-10-22 11:52:32 -07001170
Jonas Olsson12046902018-12-06 11:25:14 +01001171 // Returns an aggregate state of all ICE *and* DTLS transports.
1172 // This is left in place to avoid breaking native clients who expect our old,
1173 // nonstandard behavior.
1174 // TODO(jonasolsson): deprecate and remove this.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001175 virtual IceConnectionState ice_connection_state() = 0;
Taylor Brandstettercb423c42017-10-22 11:52:32 -07001176
Jonas Olsson12046902018-12-06 11:25:14 +01001177 // Returns an aggregated state of all ICE transports.
Niels Möller7b04a912019-09-13 15:41:21 +02001178 virtual IceConnectionState standardized_ice_connection_state() = 0;
Jonas Olsson12046902018-12-06 11:25:14 +01001179
1180 // Returns an aggregated state of all ICE and DTLS transports.
Niels Möller7b04a912019-09-13 15:41:21 +02001181 virtual PeerConnectionState peer_connection_state() = 0;
Jonas Olsson635474e2018-10-18 15:58:17 +02001182
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001183 virtual IceGatheringState ice_gathering_state() = 0;
1184
Harald Alvestrand61f74d92020-03-02 11:20:00 +01001185 // Returns the current state of canTrickleIceCandidates per
1186 // https://w3c.github.io/webrtc-pc/#attributes-1
1187 virtual absl::optional<bool> can_trickle_ice_candidates() {
1188 // TODO(crbug.com/708484): Remove default implementation.
1189 return absl::nullopt;
1190 }
1191
Henrik Boström4c1e7cc2020-06-11 12:26:53 +02001192 // When a resource is overused, the PeerConnection will try to reduce the load
1193 // on the sysem, for example by reducing the resolution or frame rate of
1194 // encoded streams. The Resource API allows injecting platform-specific usage
1195 // measurements. The conditions to trigger kOveruse or kUnderuse are up to the
1196 // implementation.
1197 // TODO(hbos): Make pure virtual when implemented by downstream projects.
1198 virtual void AddAdaptationResource(rtc::scoped_refptr<Resource> resource) {}
1199
Elad Alon99c3fe52017-10-13 16:29:40 +02001200 // Start RtcEventLog using an existing output-sink. Takes ownership of
Artem Titov0e61fdd2021-07-25 21:50:14 +02001201 // `output` and passes it on to Call, which will take the ownership. If the
Bjorn Tereliusde939432017-11-20 17:38:14 +01001202 // operation fails the output will be closed and deallocated. The event log
Artem Titov0e61fdd2021-07-25 21:50:14 +02001203 // will send serialized events to the output object every `output_period_ms`.
Niels Möllerf00ca1a2019-05-10 11:33:12 +02001204 // Applications using the event log should generally make their own trade-off
1205 // regarding the output period. A long period is generally more efficient,
1206 // with potential drawbacks being more bursty thread usage, and more events
Artem Titov0e61fdd2021-07-25 21:50:14 +02001207 // lost in case the application crashes. If the `output_period_ms` argument is
Niels Möllerf00ca1a2019-05-10 11:33:12 +02001208 // omitted, webrtc selects a default deemed to be workable in most cases.
Bjorn Tereliusde939432017-11-20 17:38:14 +01001209 virtual bool StartRtcEventLog(std::unique_ptr<RtcEventLogOutput> output,
Niels Möller7b04a912019-09-13 15:41:21 +02001210 int64_t output_period_ms) = 0;
1211 virtual bool StartRtcEventLog(std::unique_ptr<RtcEventLogOutput> output) = 0;
Elad Alon99c3fe52017-10-13 16:29:40 +02001212
ivoc14d5dbe2016-07-04 07:06:55 -07001213 // Stops logging the RtcEventLog.
Niels Möller7b04a912019-09-13 15:41:21 +02001214 virtual void StopRtcEventLog() = 0;
ivoc14d5dbe2016-07-04 07:06:55 -07001215
deadbeefb10f32f2017-02-08 01:38:21 -08001216 // Terminates all media, closes the transports, and in general releases any
1217 // resources used by the PeerConnection. This is an irreversible operation.
deadbeefd07061c2017-04-20 13:19:00 -07001218 //
1219 // Note that after this method completes, the PeerConnection will no longer
1220 // use the PeerConnectionObserver interface passed in on construction, and
1221 // thus the observer object can be safely destroyed.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001222 virtual void Close() = 0;
1223
Taylor Brandstetterc88fe702020-08-03 16:36:16 -07001224 // The thread on which all PeerConnectionObserver callbacks will be invoked,
1225 // as well as callbacks for other classes such as DataChannelObserver.
1226 //
1227 // Also the only thread on which it's safe to use SessionDescriptionInterface
1228 // pointers.
1229 // TODO(deadbeef): Make pure virtual when all subclasses implement it.
1230 virtual rtc::Thread* signaling_thread() const { return nullptr; }
1231
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001232 protected:
1233 // Dtor protected as objects shouldn't be deleted via this interface.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001234 ~PeerConnectionInterface() override = default;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001235};
1236
deadbeefb10f32f2017-02-08 01:38:21 -08001237// PeerConnection callback interface, used for RTCPeerConnection events.
1238// Application should implement these methods.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001239class PeerConnectionObserver {
1240 public:
Sami Kalliomäki02879f92018-01-11 10:02:19 +01001241 virtual ~PeerConnectionObserver() = default;
1242
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001243 // Triggered when the SignalingState changed.
1244 virtual void OnSignalingChange(
perkjdfb769d2016-02-09 03:09:43 -08001245 PeerConnectionInterface::SignalingState new_state) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001246
1247 // Triggered when media is received on a new stream from remote peer.
Steve Anton772eb212018-01-16 10:11:06 -08001248 virtual void OnAddStream(rtc::scoped_refptr<MediaStreamInterface> stream) {}
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001249
Steve Anton3172c032018-05-03 15:30:18 -07001250 // Triggered when a remote peer closes a stream.
Steve Anton772eb212018-01-16 10:11:06 -08001251 virtual void OnRemoveStream(rtc::scoped_refptr<MediaStreamInterface> stream) {
1252 }
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001253
Taylor Brandstetter98cde262016-05-31 13:02:21 -07001254 // Triggered when a remote peer opens a data channel.
1255 virtual void OnDataChannel(
nisse7f067662017-03-08 06:59:45 -08001256 rtc::scoped_refptr<DataChannelInterface> data_channel) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001257
Taylor Brandstetter98cde262016-05-31 13:02:21 -07001258 // Triggered when renegotiation is needed. For example, an ICE restart
1259 // has begun.
Henrik Boströme574a312020-08-25 10:20:11 +02001260 // TODO(hbos): Delete in favor of OnNegotiationNeededEvent() when downstream
1261 // projects have migrated.
1262 virtual void OnRenegotiationNeeded() {}
1263 // Used to fire spec-compliant onnegotiationneeded events, which should only
1264 // fire when the Operations Chain is empty. The observer is responsible for
1265 // queuing a task (e.g. Chromium: jump to main thread) to maybe fire the
Artem Titov0e61fdd2021-07-25 21:50:14 +02001266 // event. The event identified using `event_id` must only fire if
Henrik Boströme574a312020-08-25 10:20:11 +02001267 // PeerConnection::ShouldFireNegotiationNeededEvent() returns true since it is
1268 // possible for the event to become invalidated by operations subsequently
1269 // chained.
1270 virtual void OnNegotiationNeededEvent(uint32_t event_id) {}
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001271
Jonas Olsson12046902018-12-06 11:25:14 +01001272 // Called any time the legacy IceConnectionState changes.
deadbeefb10f32f2017-02-08 01:38:21 -08001273 //
1274 // Note that our ICE states lag behind the standard slightly. The most
1275 // notable differences include the fact that "failed" occurs after 15
1276 // seconds, not 30, and this actually represents a combination ICE + DTLS
1277 // state, so it may be "failed" if DTLS fails while ICE succeeds.
Jonas Olsson12046902018-12-06 11:25:14 +01001278 //
1279 // TODO(jonasolsson): deprecate and remove this.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001280 virtual void OnIceConnectionChange(
Sebastian Jansson6acb0692019-07-30 18:34:09 +02001281 PeerConnectionInterface::IceConnectionState new_state) {}
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001282
Jonas Olsson12046902018-12-06 11:25:14 +01001283 // Called any time the standards-compliant IceConnectionState changes.
1284 virtual void OnStandardizedIceConnectionChange(
1285 PeerConnectionInterface::IceConnectionState new_state) {}
1286
Jonas Olsson635474e2018-10-18 15:58:17 +02001287 // Called any time the PeerConnectionState changes.
1288 virtual void OnConnectionChange(
1289 PeerConnectionInterface::PeerConnectionState new_state) {}
1290
Taylor Brandstetter98cde262016-05-31 13:02:21 -07001291 // Called any time the IceGatheringState changes.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001292 virtual void OnIceGatheringChange(
perkjdfb769d2016-02-09 03:09:43 -08001293 PeerConnectionInterface::IceGatheringState new_state) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001294
Taylor Brandstetter98cde262016-05-31 13:02:21 -07001295 // A new ICE candidate has been gathered.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001296 virtual void OnIceCandidate(const IceCandidateInterface* candidate) = 0;
1297
Eldar Relloda13ea22019-06-01 12:23:43 +03001298 // Gathering of an ICE candidate failed.
1299 // See https://w3c.github.io/webrtc-pc/#event-icecandidateerror
Eldar Rello0095d372019-12-02 22:22:07 +02001300 virtual void OnIceCandidateError(const std::string& address,
1301 int port,
1302 const std::string& url,
1303 int error_code,
1304 const std::string& error_text) {}
1305
Honghai Zhang7fb69db2016-03-14 11:59:18 -07001306 // Ice candidates have been removed.
1307 // TODO(honghaiz): Make this a pure virtual method when all its subclasses
1308 // implement it.
1309 virtual void OnIceCandidatesRemoved(
1310 const std::vector<cricket::Candidate>& candidates) {}
1311
Peter Thatcher54360512015-07-08 11:08:35 -07001312 // Called when the ICE connection receiving status changes.
1313 virtual void OnIceConnectionReceivingChange(bool receiving) {}
1314
Alex Drake00c7ecf2019-08-06 10:54:47 -07001315 // Called when the selected candidate pair for the ICE connection changes.
1316 virtual void OnIceSelectedCandidatePairChanged(
1317 const cricket::CandidatePairChangeEvent& event) {}
1318
Steve Antonab6ea6b2018-02-26 14:23:09 -08001319 // This is called when a receiver and its track are created.
Henrik Boström933d8b02017-10-10 10:05:16 -07001320 // TODO(zhihuang): Make this pure virtual when all subclasses implement it.
Steve Anton8b815cd2018-02-16 16:14:42 -08001321 // Note: This is called with both Plan B and Unified Plan semantics. Unified
1322 // Plan users should prefer OnTrack, OnAddTrack is only called as backwards
1323 // compatibility (and is called in the exact same situations as OnTrack).
zhihuang81c3a032016-11-17 12:06:24 -08001324 virtual void OnAddTrack(
1325 rtc::scoped_refptr<RtpReceiverInterface> receiver,
zhihuangc63b8942016-12-02 15:41:10 -08001326 const std::vector<rtc::scoped_refptr<MediaStreamInterface>>& streams) {}
zhihuang81c3a032016-11-17 12:06:24 -08001327
Steve Anton8b815cd2018-02-16 16:14:42 -08001328 // This is called when signaling indicates a transceiver will be receiving
1329 // media from the remote endpoint. This is fired during a call to
1330 // SetRemoteDescription. The receiving track can be accessed by:
Artem Titovcfea2182021-08-10 01:22:31 +02001331 // `transceiver->receiver()->track()` and its associated streams by
1332 // `transceiver->receiver()->streams()`.
Steve Anton8b815cd2018-02-16 16:14:42 -08001333 // Note: This will only be called if Unified Plan semantics are specified.
1334 // This behavior is specified in section 2.2.8.2.5 of the "Set the
1335 // RTCSessionDescription" algorithm:
1336 // https://w3c.github.io/webrtc-pc/#set-description
1337 virtual void OnTrack(
1338 rtc::scoped_refptr<RtpTransceiverInterface> transceiver) {}
1339
Steve Anton3172c032018-05-03 15:30:18 -07001340 // Called when signaling indicates that media will no longer be received on a
1341 // track.
1342 // With Plan B semantics, the given receiver will have been removed from the
1343 // PeerConnection and the track muted.
1344 // With Unified Plan semantics, the receiver will remain but the transceiver
1345 // will have changed direction to either sendonly or inactive.
Henrik Boström933d8b02017-10-10 10:05:16 -07001346 // https://w3c.github.io/webrtc-pc/#process-remote-track-removal
Henrik Boström933d8b02017-10-10 10:05:16 -07001347 // TODO(hbos,deadbeef): Make pure virtual when all subclasses implement it.
1348 virtual void OnRemoveTrack(
1349 rtc::scoped_refptr<RtpReceiverInterface> receiver) {}
Harald Alvestrandc0e97252018-07-26 10:39:55 +02001350
1351 // Called when an interesting usage is detected by WebRTC.
1352 // An appropriate action is to add information about the context of the
1353 // PeerConnection and write the event to some kind of "interesting events"
1354 // log function.
1355 // The heuristics for defining what constitutes "interesting" are
1356 // implementation-defined.
1357 virtual void OnInterestingUsage(int usage_pattern) {}
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001358};
1359
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001360// PeerConnectionDependencies holds all of PeerConnections dependencies.
1361// A dependency is distinct from a configuration as it defines significant
1362// executable code that can be provided by a user of the API.
1363//
1364// All new dependencies should be added as a unique_ptr to allow the
1365// PeerConnection object to be the definitive owner of the dependencies
1366// lifetime making injection safer.
Mirko Bonadei35214fc2019-09-23 14:54:28 +02001367struct RTC_EXPORT PeerConnectionDependencies final {
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001368 explicit PeerConnectionDependencies(PeerConnectionObserver* observer_in);
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001369 // This object is not copyable or assignable.
1370 PeerConnectionDependencies(const PeerConnectionDependencies&) = delete;
1371 PeerConnectionDependencies& operator=(const PeerConnectionDependencies&) =
1372 delete;
1373 // This object is only moveable.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001374 PeerConnectionDependencies(PeerConnectionDependencies&&);
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001375 PeerConnectionDependencies& operator=(PeerConnectionDependencies&&) = default;
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001376 ~PeerConnectionDependencies();
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001377 // Mandatory dependencies
1378 PeerConnectionObserver* observer = nullptr;
1379 // Optional dependencies
Patrik Höglund662e31f2019-09-05 14:35:04 +02001380 // TODO(bugs.webrtc.org/7447): remove port allocator once downstream is
1381 // updated. For now, you can only set one of allocator and
1382 // packet_socket_factory, not both.
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001383 std::unique_ptr<cricket::PortAllocator> allocator;
Patrik Höglund662e31f2019-09-05 14:35:04 +02001384 std::unique_ptr<rtc::PacketSocketFactory> packet_socket_factory;
Harald Alvestrand0ccfbd22021-04-08 07:25:04 +00001385 // Factory for creating resolvers that look up hostnames in DNS
1386 std::unique_ptr<webrtc::AsyncDnsResolverFactoryInterface>
1387 async_dns_resolver_factory;
1388 // Deprecated - use async_dns_resolver_factory
Zach Steine20867f2018-08-02 13:20:15 -07001389 std::unique_ptr<webrtc::AsyncResolverFactory> async_resolver_factory;
Qingsi Wang25ec8882019-11-15 12:33:05 -08001390 std::unique_ptr<webrtc::IceTransportFactory> ice_transport_factory;
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001391 std::unique_ptr<rtc::RTCCertificateGeneratorInterface> cert_generator;
Benjamin Wrightd6f86e82018-05-08 13:12:25 -07001392 std::unique_ptr<rtc::SSLCertificateVerifier> tls_cert_verifier;
Jonas Orelanda3aa9bd2019-04-17 07:38:40 +02001393 std::unique_ptr<webrtc::VideoBitrateAllocatorFactory>
1394 video_bitrate_allocator_factory;
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001395};
1396
Benjamin Wright5234a492018-05-29 15:04:32 -07001397// PeerConnectionFactoryDependencies holds all of the PeerConnectionFactory
1398// dependencies. All new dependencies should be added here instead of
1399// overloading the function. This simplifies dependency injection and makes it
1400// clear which are mandatory and optional. If possible please allow the peer
1401// connection factory to take ownership of the dependency by adding a unique_ptr
1402// to this structure.
Mirko Bonadei35214fc2019-09-23 14:54:28 +02001403struct RTC_EXPORT PeerConnectionFactoryDependencies final {
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001404 PeerConnectionFactoryDependencies();
Benjamin Wright5234a492018-05-29 15:04:32 -07001405 // This object is not copyable or assignable.
1406 PeerConnectionFactoryDependencies(const PeerConnectionFactoryDependencies&) =
1407 delete;
1408 PeerConnectionFactoryDependencies& operator=(
1409 const PeerConnectionFactoryDependencies&) = delete;
1410 // This object is only moveable.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001411 PeerConnectionFactoryDependencies(PeerConnectionFactoryDependencies&&);
Benjamin Wright5234a492018-05-29 15:04:32 -07001412 PeerConnectionFactoryDependencies& operator=(
1413 PeerConnectionFactoryDependencies&&) = default;
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001414 ~PeerConnectionFactoryDependencies();
Benjamin Wright5234a492018-05-29 15:04:32 -07001415
1416 // Optional dependencies
1417 rtc::Thread* network_thread = nullptr;
1418 rtc::Thread* worker_thread = nullptr;
1419 rtc::Thread* signaling_thread = nullptr;
Danil Chapovalov9435c612019-04-01 10:33:16 +02001420 std::unique_ptr<TaskQueueFactory> task_queue_factory;
Benjamin Wright5234a492018-05-29 15:04:32 -07001421 std::unique_ptr<cricket::MediaEngineInterface> media_engine;
1422 std::unique_ptr<CallFactoryInterface> call_factory;
1423 std::unique_ptr<RtcEventLogFactoryInterface> event_log_factory;
1424 std::unique_ptr<FecControllerFactoryInterface> fec_controller_factory;
Ying Wang0810a7c2019-04-10 13:48:24 +02001425 std::unique_ptr<NetworkStatePredictorFactoryInterface>
1426 network_state_predictor_factory;
Benjamin Wright5234a492018-05-29 15:04:32 -07001427 std::unique_ptr<NetworkControllerFactoryInterface> network_controller_factory;
Taylor Brandstetter239ac8a2020-07-31 16:07:52 -07001428 // This will only be used if CreatePeerConnection is called without a
Artem Titov0e61fdd2021-07-25 21:50:14 +02001429 // `port_allocator`, causing the default allocator and network manager to be
Taylor Brandstetter239ac8a2020-07-31 16:07:52 -07001430 // used.
1431 std::unique_ptr<rtc::NetworkMonitorFactory> network_monitor_factory;
Ivo Creusenc3d1f9b2019-11-01 11:47:51 +01001432 std::unique_ptr<NetEqFactory> neteq_factory;
Per Kjellander2bca0082020-08-28 09:15:15 +02001433 std::unique_ptr<SctpTransportFactoryInterface> sctp_factory;
Erik Språng662678d2019-11-15 17:18:52 +01001434 std::unique_ptr<WebRtcKeyValueConfig> trials;
Vojin Ilic504fc192021-05-31 14:02:28 +02001435 std::unique_ptr<RtpTransportControllerSendFactoryInterface>
1436 transport_controller_send_factory;
Benjamin Wright5234a492018-05-29 15:04:32 -07001437};
1438
deadbeefb10f32f2017-02-08 01:38:21 -08001439// PeerConnectionFactoryInterface is the factory interface used for creating
1440// PeerConnection, MediaStream and MediaStreamTrack objects.
1441//
1442// The simplest method for obtaiing one, CreatePeerConnectionFactory will
1443// create the required libjingle threads, socket and network manager factory
1444// classes for networking if none are provided, though it requires that the
1445// application runs a message loop on the thread that called the method (see
1446// explanation below)
1447//
1448// If an application decides to provide its own threads and/or implementation
1449// of networking classes, it should use the alternate
1450// CreatePeerConnectionFactory method which accepts threads as input, and use
1451// the CreatePeerConnection version that takes a PortAllocator as an argument.
Ken MacKay831ce5f2019-12-02 10:26:34 -08001452class RTC_EXPORT PeerConnectionFactoryInterface
1453 : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001454 public:
wu@webrtc.org97077a32013-10-25 21:18:33 +00001455 class Options {
1456 public:
Benjamin Wrighta54daf12018-10-11 15:33:17 -07001457 Options() {}
deadbeefb10f32f2017-02-08 01:38:21 -08001458
1459 // If set to true, created PeerConnections won't enforce any SRTP
1460 // requirement, allowing unsecured media. Should only be used for
1461 // testing/debugging.
1462 bool disable_encryption = false;
1463
deadbeefb10f32f2017-02-08 01:38:21 -08001464 // If set to true, any platform-supported network monitoring capability
1465 // won't be used, and instead networks will only be updated via polling.
1466 //
1467 // This only has an effect if a PeerConnection is created with the default
1468 // PortAllocator implementation.
1469 bool disable_network_monitor = false;
phoglund@webrtc.org006521d2015-02-12 09:23:59 +00001470
1471 // Sets the network types to ignore. For instance, calling this with
1472 // ADAPTER_TYPE_ETHERNET | ADAPTER_TYPE_LOOPBACK will ignore Ethernet and
1473 // loopback interfaces.
deadbeefb10f32f2017-02-08 01:38:21 -08001474 int network_ignore_mask = rtc::kDefaultNetworkIgnoreMask;
Joachim Bauch04e5b492015-05-29 09:40:39 +02001475
1476 // Sets the maximum supported protocol version. The highest version
1477 // supported by both ends will be used for the connection, i.e. if one
1478 // party supports DTLS 1.0 and the other DTLS 1.2, DTLS 1.0 will be used.
deadbeefb10f32f2017-02-08 01:38:21 -08001479 rtc::SSLProtocolVersion ssl_max_version = rtc::SSL_PROTOCOL_DTLS_12;
jbauchcb560652016-08-04 05:20:32 -07001480
1481 // Sets crypto related options, e.g. enabled cipher suites.
Benjamin Wrighta54daf12018-10-11 15:33:17 -07001482 CryptoOptions crypto_options = CryptoOptions::NoGcm();
wu@webrtc.org97077a32013-10-25 21:18:33 +00001483 };
1484
deadbeef7914b8c2017-04-21 03:23:33 -07001485 // Set the options to be used for subsequently created PeerConnections.
wu@webrtc.org97077a32013-10-25 21:18:33 +00001486 virtual void SetOptions(const Options& options) = 0;
buildbot@webrtc.org41451d42014-05-03 05:39:45 +00001487
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001488 // The preferred way to create a new peer connection. Simply provide the
1489 // configuration and a PeerConnectionDependencies structure.
1490 // TODO(benwright): Make pure virtual once downstream mock PC factory classes
1491 // are updated.
Harald Alvestranda3dd7722020-11-27 08:05:42 +00001492 virtual RTCErrorOr<rtc::scoped_refptr<PeerConnectionInterface>>
1493 CreatePeerConnectionOrError(
1494 const PeerConnectionInterface::RTCConfiguration& configuration,
1495 PeerConnectionDependencies dependencies);
1496 // Deprecated creator - does not return an error code on error.
1497 // TODO(bugs.webrtc.org:12238): Deprecate and remove.
Harald Alvestrandf33f7a22021-05-09 14:58:57 +00001498 ABSL_DEPRECATED("Use CreatePeerConnectionOrError")
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001499 virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection(
1500 const PeerConnectionInterface::RTCConfiguration& configuration,
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001501 PeerConnectionDependencies dependencies);
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001502
Artem Titov0e61fdd2021-07-25 21:50:14 +02001503 // Deprecated; `allocator` and `cert_generator` may be null, in which case
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001504 // default implementations will be used.
deadbeefd07061c2017-04-20 13:19:00 -07001505 //
Artem Titov0e61fdd2021-07-25 21:50:14 +02001506 // `observer` must not be null.
deadbeefd07061c2017-04-20 13:19:00 -07001507 //
Artem Titov0e61fdd2021-07-25 21:50:14 +02001508 // Note that this method does not take ownership of `observer`; it's the
deadbeefd07061c2017-04-20 13:19:00 -07001509 // responsibility of the caller to delete it. It can be safely deleted after
1510 // Close has been called on the returned PeerConnection, which ensures no
1511 // more observer callbacks will be invoked.
Harald Alvestrandf33f7a22021-05-09 14:58:57 +00001512 ABSL_DEPRECATED("Use CreatePeerConnectionOrError")
deadbeef41b07982015-12-01 15:01:24 -08001513 virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection(
1514 const PeerConnectionInterface::RTCConfiguration& configuration,
kwibergd1fe2812016-04-27 06:47:29 -07001515 std::unique_ptr<cricket::PortAllocator> allocator,
Henrik Boströmd03c23b2016-06-01 11:44:18 +02001516 std::unique_ptr<rtc::RTCCertificateGeneratorInterface> cert_generator,
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001517 PeerConnectionObserver* observer);
1518
Artem Titov0e61fdd2021-07-25 21:50:14 +02001519 // Returns the capabilities of an RTP sender of type `kind`.
Florent Castelli72b751a2018-06-28 14:09:33 +02001520 // If for some reason you pass in MEDIA_TYPE_DATA, returns an empty structure.
1521 // TODO(orphis): Make pure virtual when all subclasses implement it.
1522 virtual RtpCapabilities GetRtpSenderCapabilities(
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001523 cricket::MediaType kind) const;
Florent Castelli72b751a2018-06-28 14:09:33 +02001524
Artem Titov0e61fdd2021-07-25 21:50:14 +02001525 // Returns the capabilities of an RTP receiver of type `kind`.
Florent Castelli72b751a2018-06-28 14:09:33 +02001526 // If for some reason you pass in MEDIA_TYPE_DATA, returns an empty structure.
1527 // TODO(orphis): Make pure virtual when all subclasses implement it.
1528 virtual RtpCapabilities GetRtpReceiverCapabilities(
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001529 cricket::MediaType kind) const;
Florent Castelli72b751a2018-06-28 14:09:33 +02001530
Seth Hampson845e8782018-03-02 11:34:10 -08001531 virtual rtc::scoped_refptr<MediaStreamInterface> CreateLocalMediaStream(
1532 const std::string& stream_id) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001533
deadbeefe814a0d2017-02-25 18:15:09 -08001534 // Creates an AudioSourceInterface.
Artem Titov0e61fdd2021-07-25 21:50:14 +02001535 // `options` decides audio processing settings.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +00001536 virtual rtc::scoped_refptr<AudioSourceInterface> CreateAudioSource(
htaa2a49d92016-03-04 02:51:39 -08001537 const cricket::AudioOptions& options) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001538
Artem Titov0e61fdd2021-07-25 21:50:14 +02001539 // Creates a new local VideoTrack. The same `source` can be used in several
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001540 // tracks.
perkja3ede6c2016-03-08 01:27:48 +01001541 virtual rtc::scoped_refptr<VideoTrackInterface> CreateVideoTrack(
1542 const std::string& label,
1543 VideoTrackSourceInterface* source) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001544
Artem Titov0e61fdd2021-07-25 21:50:14 +02001545 // Creates an new AudioTrack. At the moment `source` can be null.
Yves Gerey665174f2018-06-19 15:03:05 +02001546 virtual rtc::scoped_refptr<AudioTrackInterface> CreateAudioTrack(
1547 const std::string& label,
1548 AudioSourceInterface* source) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001549
Artem Titov0e61fdd2021-07-25 21:50:14 +02001550 // Starts AEC dump using existing file. Takes ownership of `file` and passes
wu@webrtc.orga9890802013-12-13 00:21:03 +00001551 // it on to VoiceEngine (via other objects) immediately, which will take
wu@webrtc.orga8910d22014-01-23 22:12:45 +00001552 // the ownerhip. If the operation fails, the file will be closed.
ivocd66b44d2016-01-15 03:06:36 -08001553 // A maximum file size in bytes can be specified. When the file size limit is
1554 // reached, logging is stopped automatically. If max_size_bytes is set to a
1555 // value <= 0, no limit will be used, and logging will continue until the
1556 // StopAecDump function is called.
Niels Möllere8e4dc42019-06-11 14:04:16 +02001557 // TODO(webrtc:6463): Delete default implementation when downstream mocks
1558 // classes are updated.
1559 virtual bool StartAecDump(FILE* file, int64_t max_size_bytes) {
1560 return false;
1561 }
wu@webrtc.orga9890802013-12-13 00:21:03 +00001562
ivoc797ef122015-10-22 03:25:41 -07001563 // Stops logging the AEC dump.
1564 virtual void StopAecDump() = 0;
1565
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001566 protected:
1567 // Dtor and ctor protected as objects shouldn't be created or deleted via
1568 // this interface.
1569 PeerConnectionFactoryInterface() {}
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001570 ~PeerConnectionFactoryInterface() override = default;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001571};
1572
Danil Chapovalov3b112e22019-05-20 14:36:00 +02001573// CreateModularPeerConnectionFactory is implemented in the "peerconnection"
1574// build target, which doesn't pull in the implementations of every module
1575// webrtc may use.
zhihuang38ede132017-06-15 12:52:32 -07001576//
1577// If an application knows it will only require certain modules, it can reduce
1578// webrtc's impact on its binary size by depending only on the "peerconnection"
1579// target and the modules the application requires, using
Danil Chapovalov3b112e22019-05-20 14:36:00 +02001580// CreateModularPeerConnectionFactory. For example, if an application
zhihuang38ede132017-06-15 12:52:32 -07001581// only uses WebRTC for audio, it can pass in null pointers for the
1582// video-specific interfaces, and omit the corresponding modules from its
1583// build.
1584//
Artem Titov0e61fdd2021-07-25 21:50:14 +02001585// If `network_thread` or `worker_thread` are null, the PeerConnectionFactory
1586// will create the necessary thread internally. If `signaling_thread` is null,
zhihuang38ede132017-06-15 12:52:32 -07001587// the PeerConnectionFactory will use the thread on which this method is called
1588// as the signaling thread, wrapping it in an rtc::Thread object if needed.
Mirko Bonadei35214fc2019-09-23 14:54:28 +02001589RTC_EXPORT rtc::scoped_refptr<PeerConnectionFactoryInterface>
Benjamin Wright5234a492018-05-29 15:04:32 -07001590CreateModularPeerConnectionFactory(
1591 PeerConnectionFactoryDependencies dependencies);
1592
Harald Alvestrand31b03e92021-11-02 10:54:38 +00001593// https://w3c.github.io/webrtc-pc/#dom-rtcsignalingstate
1594inline constexpr absl::string_view PeerConnectionInterface::AsString(
1595 SignalingState state) {
1596 switch (state) {
1597 case SignalingState::kStable:
1598 return "stable";
1599 case SignalingState::kHaveLocalOffer:
1600 return "have-local-offer";
1601 case SignalingState::kHaveLocalPrAnswer:
1602 return "have-local-pranswer";
1603 case SignalingState::kHaveRemoteOffer:
1604 return "have-remote-offer";
1605 case SignalingState::kHaveRemotePrAnswer:
1606 return "have-remote-pranswer";
1607 case SignalingState::kClosed:
1608 return "closed";
1609 }
1610 RTC_CHECK_NOTREACHED();
1611 return "";
1612}
1613
1614// https://w3c.github.io/webrtc-pc/#dom-rtcicegatheringstate
1615inline constexpr absl::string_view PeerConnectionInterface::AsString(
1616 IceGatheringState state) {
1617 switch (state) {
1618 case IceGatheringState::kIceGatheringNew:
1619 return "new";
1620 case IceGatheringState::kIceGatheringGathering:
1621 return "gathering";
1622 case IceGatheringState::kIceGatheringComplete:
1623 return "complete";
1624 }
1625 RTC_CHECK_NOTREACHED();
1626 return "";
1627}
1628
1629// https://w3c.github.io/webrtc-pc/#dom-rtciceconnectionstate
1630inline constexpr absl::string_view PeerConnectionInterface::AsString(
1631 PeerConnectionState state) {
1632 switch (state) {
1633 case PeerConnectionState::kNew:
1634 return "new";
1635 case PeerConnectionState::kConnecting:
1636 return "connecting";
1637 case PeerConnectionState::kConnected:
1638 return "connected";
1639 case PeerConnectionState::kDisconnected:
1640 return "disconnected";
1641 case PeerConnectionState::kFailed:
1642 return "failed";
1643 case PeerConnectionState::kClosed:
1644 return "closed";
1645 }
1646 RTC_CHECK_NOTREACHED();
1647 return "";
1648}
1649
1650inline constexpr absl::string_view PeerConnectionInterface::AsString(
1651 IceConnectionState state) {
1652 switch (state) {
1653 case kIceConnectionNew:
1654 return "new";
1655 case kIceConnectionChecking:
1656 return "checking";
1657 case kIceConnectionConnected:
1658 return "connected";
1659 case kIceConnectionCompleted:
1660 return "completed";
1661 case kIceConnectionFailed:
1662 return "failed";
1663 case kIceConnectionDisconnected:
1664 return "disconnected";
1665 case kIceConnectionClosed:
1666 return "closed";
1667 case kIceConnectionMax:
1668 RTC_CHECK_NOTREACHED();
1669 return "";
1670 }
1671 RTC_CHECK_NOTREACHED();
1672 return "";
1673}
1674
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001675} // namespace webrtc
1676
Steve Anton10542f22019-01-11 09:11:00 -08001677#endif // API_PEER_CONNECTION_INTERFACE_H_