blob: e80550cb0759c663340fe8f592762ff5e8ea0dfb [file] [log] [blame]
henrike@webrtc.org28e20752013-07-10 00:45:361/*
kjellanderb24317b2016-02-10 15:54:432 * Copyright 2012 The WebRTC project authors. All Rights Reserved.
henrike@webrtc.org28e20752013-07-10 00:45:363 *
kjellanderb24317b2016-02-10 15:54:434 * 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:369 */
10
11// This file contains the PeerConnection interface as defined in
Steve Antonab6ea6b2018-02-26 22:23:0912// https://w3c.github.io/webrtc-pc/#peer-to-peer-connections
henrike@webrtc.org28e20752013-07-10 00:45:3613//
deadbeefb10f32f2017-02-08 09:38:2114// 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:3619// 1. Create a PeerConnectionFactoryInterface. Check constructors for more
20// information about input parameters.
deadbeefb10f32f2017-02-08 09:38:2121//
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:3634// observer function OnIceCandidate. The candidates must also be serialized and
35// sent to the remote peer.
deadbeefb10f32f2017-02-08 09:38:2136//
henrike@webrtc.org28e20752013-07-10 00:45:3637// 6. Once an answer is received from the remote peer, call
deadbeefb10f32f2017-02-08 09:38:2138// SetRemoteDescription with the remote answer.
39//
henrike@webrtc.org28e20752013-07-10 00:45:3640// 7. Once a remote candidate is received from the remote peer, provide it to
deadbeefb10f32f2017-02-08 09:38:2141// 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:3649// 1. Create PeerConnectionFactoryInterface if it doesn't exist.
deadbeefb10f32f2017-02-08 09:38:2150//
henrike@webrtc.org28e20752013-07-10 00:45:3651// 2. Create a new PeerConnection.
deadbeefb10f32f2017-02-08 09:38:2152//
henrike@webrtc.org28e20752013-07-10 00:45:3653// 3. Provide the remote offer to the new PeerConnection object by calling
deadbeefb10f32f2017-02-08 09:38:2154// SetRemoteDescription.
55//
henrike@webrtc.org28e20752013-07-10 00:45:3656// 4. Generate an answer to the remote offer by calling CreateAnswer and send it
57// back to the remote peer.
deadbeefb10f32f2017-02-08 09:38:2158//
henrike@webrtc.org28e20752013-07-10 00:45:3659// 5. Provide the local answer to the new PeerConnection by calling
deadbeefb10f32f2017-02-08 09:38:2160// 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:3666
Steve Anton10542f22019-01-11 17:11:0067#ifndef API_PEER_CONNECTION_INTERFACE_H_
68#define API_PEER_CONNECTION_INTERFACE_H_
henrike@webrtc.org28e20752013-07-10 00:45:3669
Harald Alvestrandf33f7a22021-05-09 14:58:5770#include <stdint.h>
Niels Möllere8e4dc42019-06-11 12:04:1671#include <stdio.h>
72
Harald Alvestrandf33f7a22021-05-09 14:58:5773#include <functional>
kwibergd1fe2812016-04-27 13:47:2974#include <memory>
henrike@webrtc.org28e20752013-07-10 00:45:3675#include <string>
76#include <vector>
77
Harald Alvestrandf33f7a22021-05-09 14:58:5778#include "absl/base/attributes.h"
Harald Alvestrand31b03e92021-11-02 10:54:3879#include "absl/strings/string_view.h"
Harald Alvestrandf33f7a22021-05-09 14:58:5780#include "absl/types/optional.h"
Henrik Boström4c1e7cc2020-06-11 10:26:5381#include "api/adaptation/resource.h"
Harald Alvestrand0ccfbd22021-04-08 07:25:0482#include "api/async_dns_resolver.h"
Steve Anton10542f22019-01-11 17:11:0083#include "api/async_resolver_factory.h"
Niels Möllerd377f042018-02-13 14:03:4384#include "api/audio/audio_mixer.h"
Mirko Bonadei92ea95e2017-09-15 04:47:3185#include "api/audio_codecs/audio_decoder_factory.h"
86#include "api/audio_codecs/audio_encoder_factory.h"
Niels Möllera6fe2612018-01-19 10:28:5487#include "api/audio_options.h"
Steve Anton10542f22019-01-11 17:11:0088#include "api/call/call_factory_interface.h"
Harald Alvestrandf33f7a22021-05-09 14:58:5789#include "api/candidate.h"
Steve Anton10542f22019-01-11 17:11:0090#include "api/crypto/crypto_options.h"
91#include "api/data_channel_interface.h"
Niels Möllerc4e80ad2019-09-13 13:53:4692#include "api/dtls_transport_interface.h"
Ying Wang0dd1b0a2018-02-20 11:50:2793#include "api/fec_controller.h"
Jonas Orelande62c2f22022-03-29 09:04:4894#include "api/field_trials_view.h"
Qingsi Wang25ec8882019-11-15 20:33:0595#include "api/ice_transport_interface.h"
Mirko Bonadei92ea95e2017-09-15 04:47:3196#include "api/jsep.h"
Henrik Boström3e6931b2022-11-11 09:07:3497#include "api/legacy_stats_types.h"
Steve Anton10542f22019-01-11 17:11:0098#include "api/media_stream_interface.h"
Harald Alvestrandf33f7a22021-05-09 14:58:5799#include "api/media_types.h"
Evan Shrubsolea7ecf112022-01-26 17:02:30100#include "api/metronome/metronome.h"
Ivo Creusenc3d1f9b2019-11-01 10:47:51101#include "api/neteq/neteq_factory.h"
Ying Wang0810a7c2019-04-10 11:48:24102#include "api/network_state_predictor.h"
Patrik Höglund662e31f2019-09-05 12:35:04103#include "api/packet_socket_factory.h"
Steve Anton10542f22019-01-11 17:11:00104#include "api/rtc_error.h"
Danil Chapovalovb32f2c72019-05-22 11:39:25105#include "api/rtc_event_log/rtc_event_log_factory_interface.h"
Steve Anton10542f22019-01-11 17:11:00106#include "api/rtc_event_log_output.h"
Harald Alvestrandf33f7a22021-05-09 14:58:57107#include "api/rtp_parameters.h"
Steve Anton10542f22019-01-11 17:11:00108#include "api/rtp_receiver_interface.h"
109#include "api/rtp_sender_interface.h"
110#include "api/rtp_transceiver_interface.h"
Harald Alvestrandf33f7a22021-05-09 14:58:57111#include "api/scoped_refptr.h"
Niels Möllerc4e80ad2019-09-13 13:53:46112#include "api/sctp_transport_interface.h"
Henrik Boström831ae4e2020-07-29 10:04:00113#include "api/set_local_description_observer_interface.h"
Steve Anton10542f22019-01-11 17:11:00114#include "api/set_remote_description_observer_interface.h"
115#include "api/stats/rtc_stats_collector_callback.h"
Danil Chapovalov9435c6102019-04-01 08:33:16116#include "api/task_queue/task_queue_factory.h"
Niels Möller0c4f7be2018-05-07 12:01:37117#include "api/transport/bitrate_settings.h"
Honghai Zhangf8998cf2019-10-14 18:27:50118#include "api/transport/enums.h"
Sebastian Janssondfce03a2018-05-18 16:05:10119#include "api/transport/network_control.h"
Per Kjellander2bca0082020-08-28 07:15:15120#include "api/transport/sctp_transport_factory_interface.h"
Steve Anton10542f22019-01-11 17:11:00121#include "api/turn_customizer.h"
Harald Alvestrandf33f7a22021-05-09 14:58:57122#include "api/video/video_bitrate_allocator_factory.h"
Vojin Ilic504fc192021-05-31 12:02:28123#include "call/rtp_transport_controller_send_factory_interface.h"
Steve Anton10542f22019-01-11 17:11:00124#include "media/base/media_config.h"
Niels Möllere24557f2019-09-19 09:36:35125#include "media/base/media_engine.h"
Niels Möller8366e172018-02-14 11:20:13126// TODO(bugs.webrtc.org/7447): We plan to provide a way to let applications
127// inject a PacketSocketFactory and/or NetworkManager, and not expose
Mirko Bonadeid151cc62022-06-20 06:35:28128// PortAllocator in the PeerConnection api.
129#include "p2p/base/port_allocator.h"
Harald Alvestrandf33f7a22021-05-09 14:58:57130#include "rtc_base/network.h"
131#include "rtc_base/network_constants.h"
Taylor Brandstetter239ac8a2020-07-31 23:07:52132#include "rtc_base/network_monitor_factory.h"
Harald Alvestrandf33f7a22021-05-09 14:58:57133#include "rtc_base/ref_count.h"
Steve Anton10542f22019-01-11 17:11:00134#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 12:13:50139#include "rtc_base/system/rtc_export.h"
Harald Alvestrandf33f7a22021-05-09 14:58:57140#include "rtc_base/thread.h"
henrike@webrtc.org28e20752013-07-10 00:45:36141
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52142namespace rtc {
henrike@webrtc.org28e20752013-07-10 00:45:36143class Thread;
Yves Gerey665174f2018-06-19 13:03:05144} // namespace rtc
henrike@webrtc.org28e20752013-07-10 00:45:36145
henrike@webrtc.org28e20752013-07-10 00:45:36146namespace webrtc {
henrike@webrtc.org28e20752013-07-10 00:45:36147
148// MediaStream container interface.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52149class StreamCollectionInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36150 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 13:03:05155 virtual MediaStreamTrackInterface* FindAudioTrack(const std::string& id) = 0;
156 virtual MediaStreamTrackInterface* FindVideoTrack(const std::string& id) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36157
158 protected:
159 // Dtor protected as objects shouldn't be deleted via this interface.
Mirko Bonadei79eb4dd2018-07-19 08:39:30160 ~StreamCollectionInterface() override = default;
henrike@webrtc.org28e20752013-07-10 00:45:36161};
162
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52163class StatsObserver : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36164 public:
nissee8abe3e2017-01-18 13:00:34165 virtual void OnComplete(const StatsReports& reports) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36166
167 protected:
Mirko Bonadei79eb4dd2018-07-19 08:39:30168 ~StatsObserver() override = default;
henrike@webrtc.org28e20752013-07-10 00:45:36169};
170
Harald Alvestrandfa67aef2021-12-08 14:30:55171enum class SdpSemantics {
Henrik Boström62995db2022-01-03 08:58:10172 // TODO(https://crbug.com/webrtc/13528): Remove support for kPlanB.
Harald Alvestrandfa67aef2021-12-08 14:30:55173 kPlanB_DEPRECATED,
174 kPlanB [[deprecated]] = kPlanB_DEPRECATED,
Henrik Boström62995db2022-01-03 08:58:10175 kUnifiedPlan,
Harald Alvestrandfa67aef2021-12-08 14:30:55176};
Steve Anton79e79602017-11-20 18:25:56177
Mirko Bonadei66e76792019-04-02 09:33:59178class RTC_EXPORT PeerConnectionInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36179 public:
Jonas Olsson635474e2018-10-18 13:58:17180 // See https://w3c.github.io/webrtc-pc/#dom-rtcsignalingstate
henrike@webrtc.org28e20752013-07-10 00:45:36181 enum SignalingState {
182 kStable,
183 kHaveLocalOffer,
184 kHaveLocalPrAnswer,
185 kHaveRemoteOffer,
186 kHaveRemotePrAnswer,
187 kClosed,
188 };
Harald Alvestrand31b03e92021-11-02 10:54:38189 static constexpr absl::string_view AsString(SignalingState);
henrike@webrtc.org28e20752013-07-10 00:45:36190
Jonas Olsson635474e2018-10-18 13:58:17191 // See https://w3c.github.io/webrtc-pc/#dom-rtcicegatheringstate
henrike@webrtc.org28e20752013-07-10 00:45:36192 enum IceGatheringState {
193 kIceGatheringNew,
194 kIceGatheringGathering,
195 kIceGatheringComplete
196 };
Harald Alvestrand31b03e92021-11-02 10:54:38197 static constexpr absl::string_view AsString(IceGatheringState state);
henrike@webrtc.org28e20752013-07-10 00:45:36198
Jonas Olsson635474e2018-10-18 13:58:17199 // See https://w3c.github.io/webrtc-pc/#dom-rtcpeerconnectionstate
200 enum class PeerConnectionState {
201 kNew,
202 kConnecting,
203 kConnected,
204 kDisconnected,
205 kFailed,
206 kClosed,
207 };
Harald Alvestrand31b03e92021-11-02 10:54:38208 static constexpr absl::string_view AsString(PeerConnectionState state);
Jonas Olsson635474e2018-10-18 13:58:17209
210 // See https://w3c.github.io/webrtc-pc/#dom-rtciceconnectionstate
henrike@webrtc.org28e20752013-07-10 00:45:36211 enum IceConnectionState {
212 kIceConnectionNew,
213 kIceConnectionChecking,
214 kIceConnectionConnected,
215 kIceConnectionCompleted,
216 kIceConnectionFailed,
217 kIceConnectionDisconnected,
218 kIceConnectionClosed,
Guo-wei Shieh3d564c12015-08-19 23:51:15219 kIceConnectionMax,
henrike@webrtc.org28e20752013-07-10 00:45:36220 };
Harald Alvestrand31b03e92021-11-02 10:54:38221 static constexpr absl::string_view AsString(IceConnectionState state);
henrike@webrtc.org28e20752013-07-10 00:45:36222
hnsl04833622017-01-09 16:35:45223 // TLS certificate policy.
224 enum TlsCertPolicy {
225 // For TLS based protocols, ensure the connection is secure by not
226 // circumventing certificate validation.
227 kTlsCertPolicySecure,
228 // For TLS based protocols, disregard security completely by skipping
229 // certificate validation. This is insecure and should never be used unless
230 // security is irrelevant in that particular context.
231 kTlsCertPolicyInsecureNoCheck,
232 };
233
Mirko Bonadei051cae52019-11-12 12:01:23234 struct RTC_EXPORT IceServer {
Mirko Bonadei79eb4dd2018-07-19 08:39:30235 IceServer();
236 IceServer(const IceServer&);
237 ~IceServer();
238
Joachim Bauch7c4e7452015-05-28 21:06:30239 // TODO(jbauch): Remove uri when all code using it has switched to urls.
Emad Omaradab1d2d2017-06-16 22:43:11240 // List of URIs associated with this server. Valid formats are described
241 // in RFC7064 and RFC7065, and more may be added in the future. The "host"
242 // part of the URI may contain either an IP address or a hostname.
henrike@webrtc.org28e20752013-07-10 00:45:36243 std::string uri;
Joachim Bauch7c4e7452015-05-28 21:06:30244 std::vector<std::string> urls;
henrike@webrtc.org28e20752013-07-10 00:45:36245 std::string username;
246 std::string password;
hnsl04833622017-01-09 16:35:45247 TlsCertPolicy tls_cert_policy = kTlsCertPolicySecure;
Artem Titov0e61fdd2021-07-25 19:50:14248 // If the URIs in `urls` only contain IP addresses, this field can be used
Emad Omaradab1d2d2017-06-16 22:43:11249 // to indicate the hostname, which may be necessary for TLS (using the SNI
Artem Titov0e61fdd2021-07-25 19:50:14250 // extension). If `urls` itself contains the hostname, this isn't
Emad Omaradab1d2d2017-06-16 22:43:11251 // necessary.
252 std::string hostname;
Diogo Real1dca9d52017-08-29 19:18:32253 // List of protocols to be used in the TLS ALPN extension.
254 std::vector<std::string> tls_alpn_protocols;
Diogo Real7bd1f1b2017-09-08 19:50:41255 // List of elliptic curves to be used in the TLS elliptic curves extension.
256 std::vector<std::string> tls_elliptic_curves;
hnsl04833622017-01-09 16:35:45257
deadbeefd1a38b52016-12-10 21:15:33258 bool operator==(const IceServer& o) const {
259 return uri == o.uri && urls == o.urls && username == o.username &&
Emad Omaradab1d2d2017-06-16 22:43:11260 password == o.password && tls_cert_policy == o.tls_cert_policy &&
Diogo Real1dca9d52017-08-29 19:18:32261 hostname == o.hostname &&
Diogo Real7bd1f1b2017-09-08 19:50:41262 tls_alpn_protocols == o.tls_alpn_protocols &&
Sergey Silkin9c147dd2018-09-12 10:45:38263 tls_elliptic_curves == o.tls_elliptic_curves;
deadbeefd1a38b52016-12-10 21:15:33264 }
265 bool operator!=(const IceServer& o) const { return !(*this == o); }
henrike@webrtc.org28e20752013-07-10 00:45:36266 };
267 typedef std::vector<IceServer> IceServers;
268
buildbot@webrtc.org41451d42014-05-03 05:39:45269 enum IceTransportsType {
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06270 // TODO(pthatcher): Rename these kTransporTypeXXX, but update
271 // Chromium at the same time.
buildbot@webrtc.org41451d42014-05-03 05:39:45272 kNone,
273 kRelay,
274 kNoHost,
275 kAll
276 };
277
Steve Antonab6ea6b2018-02-26 22:23:09278 // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-24#section-4.1.1
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06279 enum BundlePolicy {
280 kBundlePolicyBalanced,
281 kBundlePolicyMaxBundle,
282 kBundlePolicyMaxCompat
283 };
buildbot@webrtc.org41451d42014-05-03 05:39:45284
Steve Antonab6ea6b2018-02-26 22:23:09285 // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-24#section-4.1.1
Peter Thatcheraf55ccc2015-05-21 14:48:41286 enum RtcpMuxPolicy {
287 kRtcpMuxPolicyNegotiate,
288 kRtcpMuxPolicyRequire,
289 };
290
Jiayang Liucac1b382015-04-30 19:35:24291 enum TcpCandidatePolicy {
292 kTcpCandidatePolicyEnabled,
293 kTcpCandidatePolicyDisabled
294 };
295
honghaiz60347052016-06-01 01:29:12296 enum CandidateNetworkPolicy {
297 kCandidateNetworkPolicyAll,
298 kCandidateNetworkPolicyLowCost
299 };
300
Yves Gerey665174f2018-06-19 13:03:05301 enum ContinualGatheringPolicy { GATHER_ONCE, GATHER_CONTINUALLY };
honghaiz1f429e32015-09-28 14:57:34302
Niels Möller73d07742021-12-02 12:58:01303 struct PortAllocatorConfig {
304 // For min_port and max_port, 0 means not specified.
305 int min_port = 0;
306 int max_port = 0;
307 uint32_t flags = 0; // Same as kDefaultPortAllocatorFlags.
308 };
309
Honghai Zhangf7ddc062016-09-01 22:34:01310 enum class RTCConfigurationType {
311 // A configuration that is safer to use, despite not having the best
312 // performance. Currently this is the default configuration.
313 kSafe,
314 // An aggressive configuration that has better performance, although it
315 // may be riskier and may need extra support in the application.
316 kAggressive
317 };
318
Henrik Boström87713d02015-08-25 07:53:21319 // TODO(hbos): Change into class with private data and public getters.
nissec36b31b2016-04-12 06:25:29320 // TODO(nisse): In particular, accessing fields directly from an
321 // application is brittle, since the organization mirrors the
322 // organization of the implementation, which isn't stable. So we
323 // need getters and setters at least for fields which applications
324 // are interested in.
Mirko Bonadeiac194142018-10-22 15:08:37325 struct RTC_EXPORT RTCConfiguration {
Niels Möller71bdda02016-03-31 10:59:59326 // This struct is subject to reorganization, both for naming
327 // consistency, and to group settings to match where they are used
328 // in the implementation. To do that, we need getter and setter
329 // methods for all settings which are of interest to applications,
330 // Chrome in particular.
331
Mirko Bonadei79eb4dd2018-07-19 08:39:30332 RTCConfiguration();
333 RTCConfiguration(const RTCConfiguration&);
334 explicit RTCConfiguration(RTCConfigurationType type);
335 ~RTCConfiguration();
Honghai Zhangbfd398c2016-08-31 05:07:42336
deadbeef293e9262017-01-11 20:28:30337 bool operator==(const RTCConfiguration& o) const;
338 bool operator!=(const RTCConfiguration& o) const;
339
Niels Möller6539f692018-01-18 07:58:50340 bool dscp() const { return media_config.enable_dscp; }
nissec36b31b2016-04-12 06:25:29341 void set_dscp(bool enable) { media_config.enable_dscp = enable; }
Niels Möller71bdda02016-03-31 10:59:59342
Niels Möller6539f692018-01-18 07:58:50343 bool cpu_adaptation() const {
Niels Möller1d7ecd22018-01-18 14:25:12344 return media_config.video.enable_cpu_adaptation;
nissec36b31b2016-04-12 06:25:29345 }
Niels Möller71bdda02016-03-31 10:59:59346 void set_cpu_adaptation(bool enable) {
Niels Möller1d7ecd22018-01-18 14:25:12347 media_config.video.enable_cpu_adaptation = enable;
Niels Möller71bdda02016-03-31 10:59:59348 }
349
Niels Möller6539f692018-01-18 07:58:50350 bool suspend_below_min_bitrate() const {
nissec36b31b2016-04-12 06:25:29351 return media_config.video.suspend_below_min_bitrate;
352 }
Niels Möller71bdda02016-03-31 10:59:59353 void set_suspend_below_min_bitrate(bool enable) {
nissec36b31b2016-04-12 06:25:29354 media_config.video.suspend_below_min_bitrate = enable;
Niels Möller71bdda02016-03-31 10:59:59355 }
356
Niels Möller6539f692018-01-18 07:58:50357 bool prerenderer_smoothing() const {
Niels Möller1d7ecd22018-01-18 14:25:12358 return media_config.video.enable_prerenderer_smoothing;
nissec36b31b2016-04-12 06:25:29359 }
Niels Möller71bdda02016-03-31 10:59:59360 void set_prerenderer_smoothing(bool enable) {
Niels Möller1d7ecd22018-01-18 14:25:12361 media_config.video.enable_prerenderer_smoothing = enable;
Niels Möller71bdda02016-03-31 10:59:59362 }
363
Niels Möller6539f692018-01-18 07:58:50364 bool experiment_cpu_load_estimator() const {
365 return media_config.video.experiment_cpu_load_estimator;
366 }
367 void set_experiment_cpu_load_estimator(bool enable) {
368 media_config.video.experiment_cpu_load_estimator = enable;
369 }
Ilya Nikolaevskiy97b4ee52018-05-28 08:24:22370
Jiawei Ou55718122018-11-09 21:17:39371 int audio_rtcp_report_interval_ms() const {
372 return media_config.audio.rtcp_report_interval_ms;
373 }
374 void set_audio_rtcp_report_interval_ms(int audio_rtcp_report_interval_ms) {
375 media_config.audio.rtcp_report_interval_ms =
376 audio_rtcp_report_interval_ms;
377 }
378
379 int video_rtcp_report_interval_ms() const {
380 return media_config.video.rtcp_report_interval_ms;
381 }
382 void set_video_rtcp_report_interval_ms(int video_rtcp_report_interval_ms) {
383 media_config.video.rtcp_report_interval_ms =
384 video_rtcp_report_interval_ms;
385 }
386
Niels Möller73d07742021-12-02 12:58:01387 // Settings for the port allcoator. Applied only if the port allocator is
388 // created by PeerConnectionFactory, not if it is injected with
389 // PeerConnectionDependencies
390 int min_port() const { return port_allocator_config.min_port; }
391 void set_min_port(int port) { port_allocator_config.min_port = port; }
392 int max_port() const { return port_allocator_config.max_port; }
393 void set_max_port(int port) { port_allocator_config.max_port = port; }
394 uint32_t port_allocator_flags() { return port_allocator_config.flags; }
395 void set_port_allocator_flags(uint32_t flags) {
396 port_allocator_config.flags = flags;
397 }
398
honghaiz4edc39c2015-09-01 16:53:56399 static const int kUndefined = -1;
400 // Default maximum number of packets in the audio jitter buffer.
Jakob Ivarsson647d5e62019-03-15 09:37:31401 static const int kAudioJitterBufferMaxPackets = 200;
Honghai Zhangaecd9822016-09-02 23:58:17402 // ICE connection receiving timeout for aggressive configuration.
403 static const int kAggressiveIceConnectionReceivingTimeout = 1000;
deadbeefb10f32f2017-02-08 09:38:21404
405 ////////////////////////////////////////////////////////////////////////
406 // The below few fields mirror the standard RTCConfiguration dictionary:
Steve Antonab6ea6b2018-02-26 22:23:09407 // https://w3c.github.io/webrtc-pc/#rtcconfiguration-dictionary
deadbeefb10f32f2017-02-08 09:38:21408 ////////////////////////////////////////////////////////////////////////
409
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06410 // TODO(pthatcher): Rename this ice_servers, but update Chromium
411 // at the same time.
412 IceServers servers;
deadbeefb10f32f2017-02-08 09:38:21413 // TODO(pthatcher): Rename this ice_transport_type, but update
414 // Chromium at the same time.
415 IceTransportsType type = kAll;
Taylor Brandstettera1c30352016-05-13 15:15:11416 BundlePolicy bundle_policy = kBundlePolicyBalanced;
zhihuang4dfb8ce2016-11-23 18:30:12417 RtcpMuxPolicy rtcp_mux_policy = kRtcpMuxPolicyRequire;
deadbeefb10f32f2017-02-08 09:38:21418 std::vector<rtc::scoped_refptr<rtc::RTCCertificate>> certificates;
419 int ice_candidate_pool_size = 0;
420
421 //////////////////////////////////////////////////////////////////////////
422 // The below fields correspond to constraints from the deprecated
423 // constraints interface for constructing a PeerConnection.
424 //
Danil Chapovalov0bc58cf2018-06-21 11:32:56425 // absl::optional fields can be "missing", in which case the implementation
deadbeefb10f32f2017-02-08 09:38:21426 // default will be used.
427 //////////////////////////////////////////////////////////////////////////
428
zhihuangb09b3f92017-03-07 22:40:51429 // If set to true, don't gather IPv6 ICE candidates on Wi-Fi.
430 // Only intended to be used on specific devices. Certain phones disable IPv6
431 // when the screen is turned off and it would be better to just disable the
432 // IPv6 ICE candidates on Wi-Fi in those cases.
433 bool disable_ipv6_on_wifi = false;
434
deadbeefd21eab3e2017-07-26 23:50:11435 // By default, the PeerConnection will use a limited number of IPv6 network
436 // interfaces, in order to avoid too many ICE candidate pairs being created
437 // and delaying ICE completion.
438 //
439 // Can be set to INT_MAX to effectively disable the limit.
440 int max_ipv6_networks = cricket::kDefaultMaxIPv6Networks;
441
Daniel Lazarenko2870b0a2018-01-25 09:30:22442 // Exclude link-local network interfaces
Honghai Zhangf8998cf2019-10-14 18:27:50443 // from consideration for gathering ICE candidates.
Daniel Lazarenko2870b0a2018-01-25 09:30:22444 bool disable_link_local_networks = false;
445
deadbeefb10f32f2017-02-08 09:38:21446 // Minimum bitrate at which screencast video tracks will be encoded at.
447 // This means adding padding bits up to this bitrate, which can help
448 // when switching from a static scene to one with motion.
Danil Chapovalov0bc58cf2018-06-21 11:32:56449 absl::optional<int> screencast_min_bitrate;
deadbeefb10f32f2017-02-08 09:38:21450
Harald Alvestrandca327932022-04-04 15:37:31451#if defined(WEBRTC_FUCHSIA)
452 // TODO(bugs.webrtc.org/11066): Remove entirely once Fuchsia does not use.
Harald Alvestrand50b95522021-11-18 10:01:06453 // TODO(bugs.webrtc.org/9891) - Move to crypto_options
454 // Can be used to disable DTLS-SRTP. This should never be done, but can be
455 // useful for testing purposes, for example in setting up a loopback call
456 // with a single PeerConnection.
457 absl::optional<bool> enable_dtls_srtp;
Harald Alvestrandca327932022-04-04 15:37:31458#endif
Harald Alvestrand50b95522021-11-18 10:01:06459
deadbeefb10f32f2017-02-08 09:38:21460 /////////////////////////////////////////////////
461 // The below fields are not part of the standard.
462 /////////////////////////////////////////////////
463
464 // Can be used to disable TCP candidate generation.
Taylor Brandstettera1c30352016-05-13 15:15:11465 TcpCandidatePolicy tcp_candidate_policy = kTcpCandidatePolicyEnabled;
deadbeefb10f32f2017-02-08 09:38:21466
467 // Can be used to avoid gathering candidates for a "higher cost" network,
468 // if a lower cost one exists. For example, if both Wi-Fi and cellular
469 // interfaces are available, this could be used to avoid using the cellular
470 // interface.
honghaiz60347052016-06-01 01:29:12471 CandidateNetworkPolicy candidate_network_policy =
472 kCandidateNetworkPolicyAll;
deadbeefb10f32f2017-02-08 09:38:21473
474 // The maximum number of packets that can be stored in the NetEq audio
475 // jitter buffer. Can be reduced to lower tolerated audio latency.
Taylor Brandstettera1c30352016-05-13 15:15:11476 int audio_jitter_buffer_max_packets = kAudioJitterBufferMaxPackets;
deadbeefb10f32f2017-02-08 09:38:21477
478 // Whether to use the NetEq "fast mode" which will accelerate audio quicker
479 // if it falls behind.
Taylor Brandstettera1c30352016-05-13 15:15:11480 bool audio_jitter_buffer_fast_accelerate = false;
deadbeefb10f32f2017-02-08 09:38:21481
Jakob Ivarsson10403ae2018-11-27 14:45:20482 // The minimum delay in milliseconds for the audio jitter buffer.
483 int audio_jitter_buffer_min_delay_ms = 0;
484
deadbeefb10f32f2017-02-08 09:38:21485 // Timeout in milliseconds before an ICE candidate pair is considered to be
486 // "not receiving", after which a lower priority candidate pair may be
487 // selected.
488 int ice_connection_receiving_timeout = kUndefined;
489
490 // Interval in milliseconds at which an ICE "backup" candidate pair will be
491 // pinged. This is a candidate pair which is not actively in use, but may
492 // be switched to if the active candidate pair becomes unusable.
493 //
494 // This is relevant mainly to Wi-Fi/cell handoff; the application may not
495 // want this backup cellular candidate pair pinged frequently, since it
496 // consumes data/battery.
497 int ice_backup_candidate_pair_ping_interval = kUndefined;
498
499 // Can be used to enable continual gathering, which means new candidates
500 // will be gathered as network interfaces change. Note that if continual
501 // gathering is used, the candidate removal API should also be used, to
502 // avoid an ever-growing list of candidates.
Taylor Brandstettera1c30352016-05-13 15:15:11503 ContinualGatheringPolicy continual_gathering_policy = GATHER_ONCE;
deadbeefb10f32f2017-02-08 09:38:21504
505 // If set to true, candidate pairs will be pinged in order of most likely
506 // to work (which means using a TURN server, generally), rather than in
507 // standard priority order.
Taylor Brandstettera1c30352016-05-13 15:15:11508 bool prioritize_most_likely_ice_candidate_pairs = false;
deadbeefb10f32f2017-02-08 09:38:21509
Niels Möller6daa2782018-01-23 09:37:42510 // Implementation defined settings. A public member only for the benefit of
511 // the implementation. Applications must not access it directly, and should
512 // instead use provided accessor methods, e.g., set_cpu_adaptation.
nissec36b31b2016-04-12 06:25:29513 struct cricket::MediaConfig media_config;
deadbeefb10f32f2017-02-08 09:38:21514
deadbeefb10f32f2017-02-08 09:38:21515 // If set to true, only one preferred TURN allocation will be used per
516 // network interface. UDP is preferred over TCP and IPv6 over IPv4. This
517 // can be used to cut down on the number of candidate pairings.
Honghai Zhangf8998cf2019-10-14 18:27:50518 // Deprecated. TODO(webrtc:11026) Remove this flag once the downstream
519 // dependency is removed.
Honghai Zhangb9e7b4a2016-07-01 03:52:02520 bool prune_turn_ports = false;
deadbeefb10f32f2017-02-08 09:38:21521
Honghai Zhangf8998cf2019-10-14 18:27:50522 // The policy used to prune turn port.
523 PortPrunePolicy turn_port_prune_policy = NO_PRUNE;
524
525 PortPrunePolicy GetTurnPortPrunePolicy() const {
526 return prune_turn_ports ? PRUNE_BASED_ON_PRIORITY
527 : turn_port_prune_policy;
528 }
529
Taylor Brandstettere9851112016-07-01 18:11:13530 // If set to true, this means the ICE transport should presume TURN-to-TURN
531 // candidate pairs will succeed, even before a binding response is received.
deadbeefb10f32f2017-02-08 09:38:21532 // This can be used to optimize the initial connection time, since the DTLS
533 // handshake can begin immediately.
Taylor Brandstettere9851112016-07-01 18:11:13534 bool presume_writable_when_fully_relayed = false;
deadbeefb10f32f2017-02-08 09:38:21535
Honghai Zhang4cedf2b2016-08-31 15:18:11536 // If true, "renomination" will be added to the ice options in the transport
537 // description.
deadbeefb10f32f2017-02-08 09:38:21538 // See: https://tools.ietf.org/html/draft-thatcher-ice-renomination-00
Honghai Zhang4cedf2b2016-08-31 15:18:11539 bool enable_ice_renomination = false;
deadbeefb10f32f2017-02-08 09:38:21540
541 // If true, the ICE role is re-determined when the PeerConnection sets a
542 // local transport description that indicates an ICE restart.
543 //
544 // This is standard RFC5245 ICE behavior, but causes unnecessary role
545 // thrashing, so an application may wish to avoid it. This role
546 // re-determining was removed in ICEbis (ICE v2).
Honghai Zhangbfd398c2016-08-31 05:07:42547 bool redetermine_role_on_ice_restart = true;
deadbeefb10f32f2017-02-08 09:38:21548
Artem Titov0e61fdd2021-07-25 19:50:14549 // This flag is only effective when `continual_gathering_policy` is
Qingsi Wang1fe119f2019-05-31 23:55:33550 // GATHER_CONTINUALLY.
551 //
552 // If true, after the ICE transport type is changed such that new types of
553 // ICE candidates are allowed by the new transport type, e.g. from
554 // IceTransportsType::kRelay to IceTransportsType::kAll, candidates that
555 // have been gathered by the ICE transport but not matching the previous
556 // transport type and as a result not observed by PeerConnectionObserver,
557 // will be surfaced to the observer.
558 bool surface_ice_candidates_on_ice_transport_type_changed = false;
559
Qingsi Wange6826d22018-03-08 22:55:14560 // The following fields define intervals in milliseconds at which ICE
561 // connectivity checks are sent.
562 //
563 // We consider ICE is "strongly connected" for an agent when there is at
564 // least one candidate pair that currently succeeds in connectivity check
565 // from its direction i.e. sending a STUN ping and receives a STUN ping
566 // response, AND all candidate pairs have sent a minimum number of pings for
567 // connectivity (this number is implementation-specific). Otherwise, ICE is
568 // considered in "weak connectivity".
569 //
570 // Note that the above notion of strong and weak connectivity is not defined
571 // in RFC 5245, and they apply to our current ICE implementation only.
572 //
573 // 1) ice_check_interval_strong_connectivity defines the interval applied to
574 // ALL candidate pairs when ICE is strongly connected, and it overrides the
575 // default value of this interval in the ICE implementation;
576 // 2) ice_check_interval_weak_connectivity defines the counterpart for ALL
577 // pairs when ICE is weakly connected, and it overrides the default value of
578 // this interval in the ICE implementation;
579 // 3) ice_check_min_interval defines the minimal interval (equivalently the
580 // maximum rate) that overrides the above two intervals when either of them
581 // is less.
Danil Chapovalov0bc58cf2018-06-21 11:32:56582 absl::optional<int> ice_check_interval_strong_connectivity;
583 absl::optional<int> ice_check_interval_weak_connectivity;
584 absl::optional<int> ice_check_min_interval;
deadbeefb10f32f2017-02-08 09:38:21585
Qingsi Wang22e623a2018-03-13 17:53:57586 // The min time period for which a candidate pair must wait for response to
587 // connectivity checks before it becomes unwritable. This parameter
588 // overrides the default value in the ICE implementation if set.
Danil Chapovalov0bc58cf2018-06-21 11:32:56589 absl::optional<int> ice_unwritable_timeout;
Qingsi Wang22e623a2018-03-13 17:53:57590
591 // The min number of connectivity checks that a candidate pair must sent
592 // without receiving response before it becomes unwritable. This parameter
593 // overrides the default value in the ICE implementation if set.
Danil Chapovalov0bc58cf2018-06-21 11:32:56594 absl::optional<int> ice_unwritable_min_checks;
Qingsi Wang22e623a2018-03-13 17:53:57595
Jiawei Ou9d4fd5552018-12-07 07:30:17596 // The min time period for which a candidate pair must wait for response to
597 // connectivity checks it becomes inactive. This parameter overrides the
598 // default value in the ICE implementation if set.
599 absl::optional<int> ice_inactive_timeout;
600
Qingsi Wangdb53f8e2018-02-20 22:45:49601 // The interval in milliseconds at which STUN candidates will resend STUN
602 // binding requests to keep NAT bindings open.
Danil Chapovalov0bc58cf2018-06-21 11:32:56603 absl::optional<int> stun_candidate_keepalive_interval;
Qingsi Wangdb53f8e2018-02-20 22:45:49604
Jonas Orelandbdcee282017-10-10 12:01:40605 // Optional TurnCustomizer.
606 // With this class one can modify outgoing TURN messages.
607 // The object passed in must remain valid until PeerConnection::Close() is
608 // called.
609 webrtc::TurnCustomizer* turn_customizer = nullptr;
610
Qingsi Wang9a5c6f82018-02-01 18:38:40611 // Preferred network interface.
612 // A candidate pair on a preferred network has a higher precedence in ICE
613 // than one on an un-preferred network, regardless of priority or network
614 // cost.
Danil Chapovalov0bc58cf2018-06-21 11:32:56615 absl::optional<rtc::AdapterType> network_preference;
Qingsi Wang9a5c6f82018-02-01 18:38:40616
Henrik Boström6d2fe892022-01-21 08:51:07617 // Configure the SDP semantics used by this PeerConnection. By default, this
618 // is Unified Plan which is compliant to the WebRTC 1.0 specification. It is
619 // possible to overrwite this to the deprecated Plan B SDP format, but note
620 // that kPlanB will be deleted at some future date, see
621 // https://crbug.com/webrtc/13528.
Steve Anton79e79602017-11-20 18:25:56622 //
Henrik Boström6d2fe892022-01-21 08:51:07623 // kUnifiedPlan will cause the PeerConnection to create offers and answers
624 // with multiple m= sections where each m= section maps to one RtpSender and
625 // one RtpReceiver (an RtpTransceiver), either both audio or both video.
626 // This will also cause the PeerConnection to ignore all but the first
627 // a=ssrc lines that form a Plan B streams (if the PeerConnection is given
628 // Plan B SDP to process).
Steve Anton79e79602017-11-20 18:25:56629 //
Henrik Boström6d2fe892022-01-21 08:51:07630 // kPlanB will cause the PeerConnection to create offers and answers with at
Harald Alvestrandfa67aef2021-12-08 14:30:55631 // most one audio and one video m= section with multiple RtpSenders and
632 // RtpReceivers specified as multiple a=ssrc lines within the section. This
633 // will also cause PeerConnection to ignore all but the first m= section of
Henrik Boström6d2fe892022-01-21 08:51:07634 // the same media type (if the PeerConnection is given Unified Plan SDP to
635 // process).
636 SdpSemantics sdp_semantics = SdpSemantics::kUnifiedPlan;
Steve Anton79e79602017-11-20 18:25:56637
Benjamin Wright8c27cca2018-10-25 17:16:44638 // TODO(bugs.webrtc.org/9891) - Move to crypto_options or remove.
Zhi Huangb57e1692018-06-12 18:41:11639 // Actively reset the SRTP parameters whenever the DTLS transports
640 // underneath are reset for every offer/answer negotiation.
641 // This is only intended to be a workaround for crbug.com/835958
642 // WARNING: This would cause RTP/RTCP packets decryption failure if not used
643 // correctly. This flag will be deprecated soon. Do not rely on it.
644 bool active_reset_srtp_params = false;
645
Benjamin Wright8c27cca2018-10-25 17:16:44646 // Defines advanced optional cryptographic settings related to SRTP and
647 // frame encryption for native WebRTC. Setting this will overwrite any
648 // settings set in PeerConnectionFactory (which is deprecated).
649 absl::optional<CryptoOptions> crypto_options;
650
Johannes Kron89f874e2018-11-12 09:25:48651 // Configure if we should include the SDP attribute extmap-allow-mixed in
Emil Lundmark801c9992021-01-19 12:06:32652 // our offer on session level.
653 bool offer_extmap_allow_mixed = true;
Johannes Kron89f874e2018-11-12 09:25:48654
Jonas Oreland3c028422019-08-22 14:16:35655 // TURN logging identifier.
656 // This identifier is added to a TURN allocation
657 // and it intended to be used to be able to match client side
658 // logs with TURN server logs. It will not be added if it's an empty string.
659 std::string turn_logging_id;
660
Eldar Rello5ab79e62019-10-09 15:29:44661 // Added to be able to control rollout of this feature.
662 bool enable_implicit_rollback = false;
663
philipel16cec3b2019-10-25 10:23:02664 // Whether network condition based codec switching is allowed.
665 absl::optional<bool> allow_codec_switching;
666
Harald Alvestrand62166932020-10-26 08:30:41667 // The delay before doing a usage histogram report for long-lived
668 // PeerConnections. Used for testing only.
669 absl::optional<int> report_usage_pattern_delay_ms;
Derek Bailey6c127a12021-04-15 19:42:41670
671 // The ping interval (ms) when the connection is stable and writable. This
672 // parameter overrides the default value in the ICE implementation if set.
673 absl::optional<int> stable_writable_connection_ping_interval_ms;
Jonas Orelandc8fa1ee2021-08-25 06:58:04674
675 // Whether this PeerConnection will avoid VPNs (kAvoidVpn), prefer VPNs
676 // (kPreferVpn), only work over VPN (kOnlyUseVpn) or only work over non-VPN
677 // (kNeverUseVpn) interfaces. This controls which local interfaces the
678 // PeerConnection will prefer to connect over. Since VPN detection is not
679 // perfect, adherence to this preference cannot be guaranteed.
680 VpnPreference vpn_preference = VpnPreference::kDefault;
681
Jonas Oreland2ee0e642021-08-25 13:43:02682 // List of address/length subnets that should be treated like
683 // VPN (in case webrtc fails to auto detect them).
684 std::vector<rtc::NetworkMask> vpn_list;
685
Niels Möller73d07742021-12-02 12:58:01686 PortAllocatorConfig port_allocator_config;
687
Henrik Boströmcf2856b2022-11-15 08:23:19688 // The burst interval of the pacer, see TaskQueuePacedSender constructor.
689 absl::optional<TimeDelta> pacer_burst_interval;
690
deadbeef293e9262017-01-11 20:28:30691 //
692 // Don't forget to update operator== if adding something.
693 //
buildbot@webrtc.org41451d42014-05-03 05:39:45694 };
695
deadbeefb10f32f2017-02-08 09:38:21696 // See: https://www.w3.org/TR/webrtc/#idl-def-rtcofferansweroptions
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16697 struct RTCOfferAnswerOptions {
698 static const int kUndefined = -1;
699 static const int kMaxOfferToReceiveMedia = 1;
700
701 // The default value for constraint offerToReceiveX:true.
702 static const int kOfferToReceiveMediaTrue = 1;
703
Steve Antonab6ea6b2018-02-26 22:23:09704 // These options are left as backwards compatibility for clients who need
705 // "Plan B" semantics. Clients who have switched to "Unified Plan" semantics
706 // should use the RtpTransceiver API (AddTransceiver) instead.
deadbeefb10f32f2017-02-08 09:38:21707 //
708 // offer_to_receive_X set to 1 will cause a media description to be
709 // generated in the offer, even if no tracks of that type have been added.
710 // Values greater than 1 are treated the same.
711 //
712 // If set to 0, the generated directional attribute will not include the
713 // "recv" direction (meaning it will be "sendonly" or "inactive".
Honghai Zhang4cedf2b2016-08-31 15:18:11714 int offer_to_receive_video = kUndefined;
715 int offer_to_receive_audio = kUndefined;
deadbeefb10f32f2017-02-08 09:38:21716
Honghai Zhang4cedf2b2016-08-31 15:18:11717 bool voice_activity_detection = true;
718 bool ice_restart = false;
deadbeefb10f32f2017-02-08 09:38:21719
720 // If true, will offer to BUNDLE audio/video/data together. Not to be
721 // confused with RTCP mux (multiplexing RTP and RTCP together).
Honghai Zhang4cedf2b2016-08-31 15:18:11722 bool use_rtp_mux = true;
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16723
Mirta Dvornicic479a3c02019-06-04 13:38:50724 // If true, "a=packetization:<payload_type> raw" attribute will be offered
725 // in the SDP for all video payload and accepted in the answer if offered.
726 bool raw_packetization_for_video = false;
727
Jonas Orelandfc1acd22018-08-24 08:58:37728 // This will apply to all video tracks with a Plan B SDP offer/answer.
729 int num_simulcast_layers = 1;
730
Harald Alvestrand4aa11922019-05-14 20:00:01731 // If true: Use SDP format from draft-ietf-mmusic-scdp-sdp-03
732 // If false: Use SDP format from draft-ietf-mmusic-sdp-sdp-26 or later
733 bool use_obsolete_sctp_sdp = false;
734
Honghai Zhang4cedf2b2016-08-31 15:18:11735 RTCOfferAnswerOptions() = default;
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16736
737 RTCOfferAnswerOptions(int offer_to_receive_video,
738 int offer_to_receive_audio,
739 bool voice_activity_detection,
740 bool ice_restart,
741 bool use_rtp_mux)
742 : offer_to_receive_video(offer_to_receive_video),
743 offer_to_receive_audio(offer_to_receive_audio),
744 voice_activity_detection(voice_activity_detection),
745 ice_restart(ice_restart),
746 use_rtp_mux(use_rtp_mux) {}
747 };
748
wu@webrtc.orgb9a088b2014-02-13 23:18:49749 // Used by GetStats to decide which stats to include in the stats reports.
Artem Titov0e61fdd2021-07-25 19:50:14750 // `kStatsOutputLevelStandard` includes the standard stats for Javascript API;
751 // `kStatsOutputLevelDebug` includes both the standard stats and additional
wu@webrtc.orgb9a088b2014-02-13 23:18:49752 // stats for debugging purposes.
753 enum StatsOutputLevel {
754 kStatsOutputLevelStandard,
755 kStatsOutputLevelDebug,
756 };
757
henrike@webrtc.org28e20752013-07-10 00:45:36758 // Accessor methods to active local streams.
Steve Antonab6ea6b2018-02-26 22:23:09759 // This method is not supported with kUnifiedPlan semantics. Please use
760 // GetSenders() instead.
Yves Gerey665174f2018-06-19 13:03:05761 virtual rtc::scoped_refptr<StreamCollectionInterface> local_streams() = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36762
763 // Accessor methods to remote streams.
Steve Antonab6ea6b2018-02-26 22:23:09764 // This method is not supported with kUnifiedPlan semantics. Please use
765 // GetReceivers() instead.
Yves Gerey665174f2018-06-19 13:03:05766 virtual rtc::scoped_refptr<StreamCollectionInterface> remote_streams() = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36767
768 // Add a new MediaStream to be sent on this PeerConnection.
769 // Note that a SessionDescription negotiation is needed before the
770 // remote peer can receive the stream.
deadbeefb10f32f2017-02-08 09:38:21771 //
772 // This has been removed from the standard in favor of a track-based API. So,
773 // this is equivalent to simply calling AddTrack for each track within the
774 // stream, with the one difference that if "stream->AddTrack(...)" is called
775 // later, the PeerConnection will automatically pick up the new track. Though
776 // this functionality will be deprecated in the future.
Steve Antonab6ea6b2018-02-26 22:23:09777 //
778 // This method is not supported with kUnifiedPlan semantics. Please use
779 // AddTrack instead.
perkj@webrtc.orgfd0efb62014-11-06 12:16:36780 virtual bool AddStream(MediaStreamInterface* stream) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36781
782 // Remove a MediaStream from this PeerConnection.
deadbeefb10f32f2017-02-08 09:38:21783 // Note that a SessionDescription negotiation is needed before the
henrike@webrtc.org28e20752013-07-10 00:45:36784 // remote peer is notified.
Steve Antonab6ea6b2018-02-26 22:23:09785 //
786 // This method is not supported with kUnifiedPlan semantics. Please use
787 // RemoveTrack instead.
henrike@webrtc.org28e20752013-07-10 00:45:36788 virtual void RemoveStream(MediaStreamInterface* stream) = 0;
789
deadbeefb10f32f2017-02-08 09:38:21790 // Add a new MediaStreamTrack to be sent on this PeerConnection, and return
Steve Antonf9381f02017-12-14 18:23:57791 // the newly created RtpSender. The RtpSender will be associated with the
Artem Titov0e61fdd2021-07-25 19:50:14792 // streams specified in the `stream_ids` list.
deadbeefb10f32f2017-02-08 09:38:21793 //
Steve Antonf9381f02017-12-14 18:23:57794 // Errors:
Artem Titov0e61fdd2021-07-25 19:50:14795 // - INVALID_PARAMETER: `track` is null, has a kind other than audio or video,
Steve Antonf9381f02017-12-14 18:23:57796 // or a sender already exists for the track.
797 // - INVALID_STATE: The PeerConnection is closed.
Steve Anton2d6c76a2018-01-06 01:10:52798 virtual RTCErrorOr<rtc::scoped_refptr<RtpSenderInterface>> AddTrack(
799 rtc::scoped_refptr<MediaStreamTrackInterface> track,
Niels Möller7b04a912019-09-13 13:41:21800 const std::vector<std::string>& stream_ids) = 0;
deadbeefe1f9d832016-01-14 23:35:42801
Jonas Oreland4b2a1062022-10-19 07:24:42802 // Add a new MediaStreamTrack as above, but with an additional parameter,
803 // `init_send_encodings` : initial RtpEncodingParameters for RtpSender,
804 // similar to init_send_encodings in RtpTransceiverInit.
805 // Note that a new transceiver will always be created.
806 //
807 virtual RTCErrorOr<rtc::scoped_refptr<RtpSenderInterface>> AddTrack(
808 rtc::scoped_refptr<MediaStreamTrackInterface> track,
809 const std::vector<std::string>& stream_ids,
810 const std::vector<RtpEncodingParameters>& init_send_encodings) = 0;
811
Harald Alvestrand09a0d012022-01-04 19:42:07812 // Removes the connection between a MediaStreamTrack and the PeerConnection.
813 // Stops sending on the RtpSender and marks the
Steve Anton24db5732018-07-23 17:27:33814 // corresponding RtpTransceiver direction as no longer sending.
Harald Alvestrand09a0d012022-01-04 19:42:07815 // https://w3c.github.io/webrtc-pc/#dom-rtcpeerconnection-removetrack
Steve Anton24db5732018-07-23 17:27:33816 //
817 // Errors:
Artem Titov0e61fdd2021-07-25 19:50:14818 // - INVALID_PARAMETER: `sender` is null or (Plan B only) the sender is not
Steve Anton24db5732018-07-23 17:27:33819 // associated with this PeerConnection.
820 // - INVALID_STATE: PeerConnection is closed.
Harald Alvestrand09a0d012022-01-04 19:42:07821 //
822 // Plan B semantics: Removes the RtpSender from this PeerConnection.
823 //
Steve Anton24db5732018-07-23 17:27:33824 // TODO(bugs.webrtc.org/9534): Rename to RemoveTrack once the other signature
Harald Alvestrand09a0d012022-01-04 19:42:07825 // is removed; remove default implementation once upstream is updated.
826 virtual RTCError RemoveTrackOrError(
827 rtc::scoped_refptr<RtpSenderInterface> sender) {
828 RTC_CHECK_NOTREACHED();
829 return RTCError();
830 }
831
Steve Anton9158ef62017-11-27 21:01:52832 // AddTransceiver creates a new RtpTransceiver and adds it to the set of
833 // transceivers. Adding a transceiver will cause future calls to CreateOffer
834 // to add a media description for the corresponding transceiver.
835 //
Artem Titov0e61fdd2021-07-25 19:50:14836 // The initial value of `mid` in the returned transceiver is null. Setting a
Steve Anton9158ef62017-11-27 21:01:52837 // new session description may change it to a non-null value.
838 //
839 // https://w3c.github.io/webrtc-pc/#dom-rtcpeerconnection-addtransceiver
840 //
841 // Optionally, an RtpTransceiverInit structure can be specified to configure
842 // the transceiver from construction. If not specified, the transceiver will
843 // default to having a direction of kSendRecv and not be part of any streams.
844 //
845 // These methods are only available when Unified Plan is enabled (see
846 // RTCConfiguration).
847 //
848 // Common errors:
849 // - INTERNAL_ERROR: The configuration does not have Unified Plan enabled.
Steve Anton9158ef62017-11-27 21:01:52850
851 // Adds a transceiver with a sender set to transmit the given track. The kind
852 // of the transceiver (and sender/receiver) will be derived from the kind of
853 // the track.
854 // Errors:
Artem Titov0e61fdd2021-07-25 19:50:14855 // - INVALID_PARAMETER: `track` is null.
Steve Anton9158ef62017-11-27 21:01:52856 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>>
Niels Möller7b04a912019-09-13 13:41:21857 AddTransceiver(rtc::scoped_refptr<MediaStreamTrackInterface> track) = 0;
Steve Anton9158ef62017-11-27 21:01:52858 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>>
859 AddTransceiver(rtc::scoped_refptr<MediaStreamTrackInterface> track,
Niels Möller7b04a912019-09-13 13:41:21860 const RtpTransceiverInit& init) = 0;
Steve Anton9158ef62017-11-27 21:01:52861
862 // Adds a transceiver with the given kind. Can either be MEDIA_TYPE_AUDIO or
863 // MEDIA_TYPE_VIDEO.
864 // Errors:
Artem Titov0e61fdd2021-07-25 19:50:14865 // - INVALID_PARAMETER: `media_type` is not MEDIA_TYPE_AUDIO or
Steve Anton9158ef62017-11-27 21:01:52866 // MEDIA_TYPE_VIDEO.
867 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>>
Niels Möller7b04a912019-09-13 13:41:21868 AddTransceiver(cricket::MediaType media_type) = 0;
Steve Anton9158ef62017-11-27 21:01:52869 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>>
Niels Möller7b04a912019-09-13 13:41:21870 AddTransceiver(cricket::MediaType media_type,
871 const RtpTransceiverInit& init) = 0;
deadbeefb10f32f2017-02-08 09:38:21872
873 // Creates a sender without a track. Can be used for "early media"/"warmup"
874 // use cases, where the application may want to negotiate video attributes
875 // before a track is available to send.
876 //
877 // The standard way to do this would be through "addTransceiver", but we
878 // don't support that API yet.
879 //
Artem Titov0e61fdd2021-07-25 19:50:14880 // `kind` must be "audio" or "video".
deadbeefb10f32f2017-02-08 09:38:21881 //
Artem Titov0e61fdd2021-07-25 19:50:14882 // `stream_id` is used to populate the msid attribute; if empty, one will
deadbeefbd7d8f72015-12-19 00:58:44883 // be generated automatically.
Steve Antonab6ea6b2018-02-26 22:23:09884 //
885 // This method is not supported with kUnifiedPlan semantics. Please use
886 // AddTransceiver instead.
deadbeeffac06552015-11-25 19:26:01887 virtual rtc::scoped_refptr<RtpSenderInterface> CreateSender(
deadbeefbd7d8f72015-12-19 00:58:44888 const std::string& kind,
Niels Möller7b04a912019-09-13 13:41:21889 const std::string& stream_id) = 0;
deadbeeffac06552015-11-25 19:26:01890
Steve Antonab6ea6b2018-02-26 22:23:09891 // If Plan B semantics are specified, gets all RtpSenders, created either
892 // through AddStream, AddTrack, or CreateSender. All senders of a specific
893 // media type share the same media description.
894 //
895 // If Unified Plan semantics are specified, gets the RtpSender for each
896 // RtpTransceiver.
deadbeef70ab1a12015-09-28 23:53:55897 virtual std::vector<rtc::scoped_refptr<RtpSenderInterface>> GetSenders()
Niels Möller7b04a912019-09-13 13:41:21898 const = 0;
deadbeef70ab1a12015-09-28 23:53:55899
Steve Antonab6ea6b2018-02-26 22:23:09900 // If Plan B semantics are specified, gets all RtpReceivers created when a
901 // remote description is applied. All receivers of a specific media type share
902 // the same media description. It is also possible to have a media description
903 // with no associated RtpReceivers, if the directional attribute does not
904 // indicate that the remote peer is sending any media.
deadbeefb10f32f2017-02-08 09:38:21905 //
Steve Antonab6ea6b2018-02-26 22:23:09906 // If Unified Plan semantics are specified, gets the RtpReceiver for each
907 // RtpTransceiver.
deadbeef70ab1a12015-09-28 23:53:55908 virtual std::vector<rtc::scoped_refptr<RtpReceiverInterface>> GetReceivers()
Niels Möller7b04a912019-09-13 13:41:21909 const = 0;
deadbeef70ab1a12015-09-28 23:53:55910
Steve Anton9158ef62017-11-27 21:01:52911 // Get all RtpTransceivers, created either through AddTransceiver, AddTrack or
912 // by a remote description applied with SetRemoteDescription.
Steve Antonab6ea6b2018-02-26 22:23:09913 //
Steve Anton9158ef62017-11-27 21:01:52914 // Note: This method is only available when Unified Plan is enabled (see
915 // RTCConfiguration).
916 virtual std::vector<rtc::scoped_refptr<RtpTransceiverInterface>>
Niels Möller7b04a912019-09-13 13:41:21917 GetTransceivers() const = 0;
Steve Anton9158ef62017-11-27 21:01:52918
Henrik Boström1df1bf82018-03-20 12:24:20919 // The legacy non-compliant GetStats() API. This correspond to the
920 // callback-based version of getStats() in JavaScript. The returned metrics
921 // are UNDOCUMENTED and many of them rely on implementation-specific details.
922 // The goal is to DELETE THIS VERSION but we can't today because it is heavily
923 // relied upon by third parties. See https://crbug.com/822696.
924 //
925 // This version is wired up into Chrome. Any stats implemented are
926 // automatically exposed to the Web Platform. This has BYPASSED the Chrome
927 // release processes for years and lead to cross-browser incompatibility
928 // issues and web application reliance on Chrome-only behavior.
929 //
930 // This API is in "maintenance mode", serious regressions should be fixed but
931 // adding new stats is highly discouraged.
932 //
933 // TODO(hbos): Deprecate and remove this when third parties have migrated to
934 // the spec-compliant GetStats() API. https://crbug.com/822696
wu@webrtc.orgb9a088b2014-02-13 23:18:49935 virtual bool GetStats(StatsObserver* observer,
Henrik Boström1df1bf82018-03-20 12:24:20936 MediaStreamTrackInterface* track, // Optional
wu@webrtc.orgb9a088b2014-02-13 23:18:49937 StatsOutputLevel level) = 0;
Henrik Boström1df1bf82018-03-20 12:24:20938 // The spec-compliant GetStats() API. This correspond to the promise-based
939 // version of getStats() in JavaScript. Implementation status is described in
940 // api/stats/rtcstats_objects.h. For more details on stats, see spec:
941 // https://w3c.github.io/webrtc-pc/#dom-rtcpeerconnection-getstats
942 // TODO(hbos): Takes shared ownership, use rtc::scoped_refptr<> instead. This
943 // requires stop overriding the current version in third party or making third
944 // party calls explicit to avoid ambiguity during switch. Make the future
945 // version abstract as soon as third party projects implement it.
Niels Möller7b04a912019-09-13 13:41:21946 virtual void GetStats(RTCStatsCollectorCallback* callback) = 0;
Henrik Boström1df1bf82018-03-20 12:24:20947 // Spec-compliant getStats() performing the stats selection algorithm with the
948 // sender. https://w3c.github.io/webrtc-pc/#dom-rtcrtpsender-getstats
Henrik Boström1df1bf82018-03-20 12:24:20949 virtual void GetStats(
950 rtc::scoped_refptr<RtpSenderInterface> selector,
Niels Möller7b04a912019-09-13 13:41:21951 rtc::scoped_refptr<RTCStatsCollectorCallback> callback) = 0;
Henrik Boström1df1bf82018-03-20 12:24:20952 // Spec-compliant getStats() performing the stats selection algorithm with the
953 // receiver. https://w3c.github.io/webrtc-pc/#dom-rtcrtpreceiver-getstats
Henrik Boström1df1bf82018-03-20 12:24:20954 virtual void GetStats(
955 rtc::scoped_refptr<RtpReceiverInterface> selector,
Niels Möller7b04a912019-09-13 13:41:21956 rtc::scoped_refptr<RTCStatsCollectorCallback> callback) = 0;
Steve Antonab6ea6b2018-02-26 22:23:09957 // Clear cached stats in the RTCStatsCollector.
Harald Alvestrand89061872018-01-02 13:08:34958 virtual void ClearStatsCache() {}
wu@webrtc.orgb9a088b2014-02-13 23:18:49959
deadbeefb10f32f2017-02-08 09:38:21960 // Create a data channel with the provided config, or default config if none
961 // is provided. Note that an offer/answer negotiation is still necessary
962 // before the data channel can be used.
963 //
964 // Also, calling CreateDataChannel is the only way to get a data "m=" section
965 // in SDP, so it should be done before CreateOffer is called, if the
966 // application plans to use data channels.
Harald Alvestranda9af50f2021-05-21 13:33:51967 virtual RTCErrorOr<rtc::scoped_refptr<DataChannelInterface>>
968 CreateDataChannelOrError(const std::string& label,
969 const DataChannelInit* config) {
970 return RTCError(RTCErrorType::INTERNAL_ERROR, "dummy function called");
971 }
972 // TODO(crbug.com/788659): Remove "virtual" below and default implementation
973 // above once mock in Chrome is fixed.
974 ABSL_DEPRECATED("Use CreateDataChannelOrError")
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52975 virtual rtc::scoped_refptr<DataChannelInterface> CreateDataChannel(
henrike@webrtc.org28e20752013-07-10 00:45:36976 const std::string& label,
Harald Alvestranda9af50f2021-05-21 13:33:51977 const DataChannelInit* config) {
978 auto result = CreateDataChannelOrError(label, config);
979 if (!result.ok()) {
980 return nullptr;
981 } else {
982 return result.MoveValue();
983 }
984 }
henrike@webrtc.org28e20752013-07-10 00:45:36985
Taylor Brandstetterc88fe702020-08-03 23:36:16986 // NOTE: For the following 6 methods, it's only safe to dereference the
987 // SessionDescriptionInterface on signaling_thread() (for example, calling
988 // ToString).
989
deadbeefb10f32f2017-02-08 09:38:21990 // Returns the more recently applied description; "pending" if it exists, and
991 // otherwise "current". See below.
henrike@webrtc.org28e20752013-07-10 00:45:36992 virtual const SessionDescriptionInterface* local_description() const = 0;
993 virtual const SessionDescriptionInterface* remote_description() const = 0;
deadbeefb10f32f2017-02-08 09:38:21994
deadbeeffe4a8a42016-12-21 01:56:17995 // A "current" description the one currently negotiated from a complete
996 // offer/answer exchange.
Niels Möller7b04a912019-09-13 13:41:21997 virtual const SessionDescriptionInterface* current_local_description()
998 const = 0;
999 virtual const SessionDescriptionInterface* current_remote_description()
1000 const = 0;
deadbeefb10f32f2017-02-08 09:38:211001
deadbeeffe4a8a42016-12-21 01:56:171002 // A "pending" description is one that's part of an incomplete offer/answer
1003 // exchange (thus, either an offer or a pranswer). Once the offer/answer
1004 // exchange is finished, the "pending" description will become "current".
Niels Möller7b04a912019-09-13 13:41:211005 virtual const SessionDescriptionInterface* pending_local_description()
1006 const = 0;
1007 virtual const SessionDescriptionInterface* pending_remote_description()
1008 const = 0;
henrike@webrtc.org28e20752013-07-10 00:45:361009
Henrik Boström79b69802019-07-18 09:16:561010 // Tells the PeerConnection that ICE should be restarted. This triggers a need
1011 // for negotiation and subsequent CreateOffer() calls will act as if
1012 // RTCOfferAnswerOptions::ice_restart is true.
1013 // https://w3c.github.io/webrtc-pc/#dom-rtcpeerconnection-restartice
1014 // TODO(hbos): Remove default implementation when downstream projects
1015 // implement this.
Niels Möller7b04a912019-09-13 13:41:211016 virtual void RestartIce() = 0;
Henrik Boström79b69802019-07-18 09:16:561017
henrike@webrtc.org28e20752013-07-10 00:45:361018 // Create a new offer.
1019 // The CreateSessionDescriptionObserver callback will be called when done.
1020 virtual void CreateOffer(CreateSessionDescriptionObserver* observer,
Niels Möllerf06f9232018-08-07 10:32:181021 const RTCOfferAnswerOptions& options) = 0;
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:161022
henrike@webrtc.org28e20752013-07-10 00:45:361023 // Create an answer to an offer.
1024 // The CreateSessionDescriptionObserver callback will be called when done.
1025 virtual void CreateAnswer(CreateSessionDescriptionObserver* observer,
Niels Möllerf06f9232018-08-07 10:32:181026 const RTCOfferAnswerOptions& options) = 0;
htaa2a49d92016-03-04 10:51:391027
henrike@webrtc.org28e20752013-07-10 00:45:361028 // Sets the local session description.
Henrik Boström831ae4e2020-07-29 10:04:001029 //
1030 // According to spec, the local session description MUST be the same as was
1031 // returned by CreateOffer() or CreateAnswer() or else the operation should
1032 // fail. Our implementation however allows some amount of "SDP munging", but
1033 // please note that this is HIGHLY DISCOURAGED. If you do not intent to munge
Artem Titov0e61fdd2021-07-25 19:50:141034 // SDP, the method below that doesn't take `desc` as an argument will create
Henrik Boström831ae4e2020-07-29 10:04:001035 // the offer or answer for you.
1036 //
1037 // The observer is invoked as soon as the operation completes, which could be
1038 // before or after the SetLocalDescription() method has exited.
1039 virtual void SetLocalDescription(
1040 std::unique_ptr<SessionDescriptionInterface> desc,
1041 rtc::scoped_refptr<SetLocalDescriptionObserverInterface> observer) {}
1042 // Creates an offer or answer (depending on current signaling state) and sets
1043 // it as the local session description.
1044 //
1045 // The observer is invoked as soon as the operation completes, which could be
1046 // before or after the SetLocalDescription() method has exited.
1047 virtual void SetLocalDescription(
1048 rtc::scoped_refptr<SetLocalDescriptionObserverInterface> observer) {}
1049 // Like SetLocalDescription() above, but the observer is invoked with a delay
1050 // after the operation completes. This helps avoid recursive calls by the
1051 // observer but also makes it possible for states to change in-between the
1052 // operation completing and the observer getting called. This makes them racy
1053 // for synchronizing peer connection states to the application.
1054 // TODO(https://crbug.com/webrtc/11798): Delete these methods in favor of the
1055 // ones taking SetLocalDescriptionObserverInterface as argument.
henrike@webrtc.org28e20752013-07-10 00:45:361056 virtual void SetLocalDescription(SetSessionDescriptionObserver* observer,
1057 SessionDescriptionInterface* desc) = 0;
Henrik Boström4e196702019-10-30 09:35:501058 virtual void SetLocalDescription(SetSessionDescriptionObserver* observer) {}
Henrik Boström831ae4e2020-07-29 10:04:001059
henrike@webrtc.org28e20752013-07-10 00:45:361060 // Sets the remote session description.
Henrik Boström831ae4e2020-07-29 10:04:001061 //
1062 // (Unlike "SDP munging" before SetLocalDescription(), modifying a remote
1063 // offer or answer is allowed by the spec.)
1064 //
1065 // The observer is invoked as soon as the operation completes, which could be
1066 // before or after the SetRemoteDescription() method has exited.
Henrik Boström31638672017-11-23 16:48:321067 virtual void SetRemoteDescription(
1068 std::unique_ptr<SessionDescriptionInterface> desc,
Niels Möller7b04a912019-09-13 13:41:211069 rtc::scoped_refptr<SetRemoteDescriptionObserverInterface> observer) = 0;
Henrik Boström831ae4e2020-07-29 10:04:001070 // Like SetRemoteDescription() above, but the observer is invoked with a delay
1071 // after the operation completes. This helps avoid recursive calls by the
1072 // observer but also makes it possible for states to change in-between the
1073 // operation completing and the observer getting called. This makes them racy
1074 // for synchronizing peer connection states to the application.
1075 // TODO(https://crbug.com/webrtc/11798): Delete this method in favor of the
1076 // ones taking SetRemoteDescriptionObserverInterface as argument.
1077 virtual void SetRemoteDescription(SetSessionDescriptionObserver* observer,
1078 SessionDescriptionInterface* desc) {}
deadbeefb10f32f2017-02-08 09:38:211079
Henrik Boströme574a312020-08-25 08:20:111080 // According to spec, we must only fire "negotiationneeded" if the Operations
1081 // Chain is empty. This method takes care of validating an event previously
1082 // generated with PeerConnectionObserver::OnNegotiationNeededEvent() to make
1083 // sure that even if there was a delay (e.g. due to a PostTask) between the
1084 // event being generated and the time of firing, the Operations Chain is empty
1085 // and the event is still valid to be fired.
1086 virtual bool ShouldFireNegotiationNeededEvent(uint32_t event_id) {
1087 return true;
1088 }
1089
Niels Möller7b04a912019-09-13 13:41:211090 virtual PeerConnectionInterface::RTCConfiguration GetConfiguration() = 0;
deadbeef293e9262017-01-11 20:28:301091
Artem Titov0e61fdd2021-07-25 19:50:141092 // Sets the PeerConnection's global configuration to `config`.
deadbeef293e9262017-01-11 20:28:301093 //
Artem Titov0e61fdd2021-07-25 19:50:141094 // The members of `config` that may be changed are `type`, `servers`,
1095 // `ice_candidate_pool_size` and `prune_turn_ports` (though the candidate
deadbeef293e9262017-01-11 20:28:301096 // pool size can't be changed after the first call to SetLocalDescription).
1097 // Note that this means the BUNDLE and RTCP-multiplexing policies cannot be
1098 // changed with this method.
1099 //
deadbeefa67696b2015-09-29 18:56:261100 // Any changes to STUN/TURN servers or ICE candidate policy will affect the
1101 // next gathering phase, and cause the next call to createOffer to generate
deadbeef293e9262017-01-11 20:28:301102 // new ICE credentials, as described in JSEP. This also occurs when
Artem Titov0e61fdd2021-07-25 19:50:141103 // `prune_turn_ports` changes, for the same reasoning.
deadbeef293e9262017-01-11 20:28:301104 //
Artem Titov0e61fdd2021-07-25 19:50:141105 // If an error occurs, returns false and populates `error` if non-null:
1106 // - INVALID_MODIFICATION if `config` contains a modified parameter other
deadbeef293e9262017-01-11 20:28:301107 // than one of the parameters listed above.
Artem Titov0e61fdd2021-07-25 19:50:141108 // - INVALID_RANGE if `ice_candidate_pool_size` is out of range.
deadbeef293e9262017-01-11 20:28:301109 // - SYNTAX_ERROR if parsing an ICE server URL failed.
Artem Titov0e61fdd2021-07-25 19:50:141110 // - INVALID_PARAMETER if a TURN server is missing `username` or `password`.
deadbeef293e9262017-01-11 20:28:301111 // - INTERNAL_ERROR if an unexpected error occurred.
Niels Möller2579f0c2019-08-19 07:58:171112 virtual RTCError SetConfiguration(
Niels Möller22a62532022-07-05 07:16:131113 const PeerConnectionInterface::RTCConfiguration& config) = 0;
deadbeefb10f32f2017-02-08 09:38:211114
henrike@webrtc.org28e20752013-07-10 00:45:361115 // Provides a remote candidate to the ICE Agent.
Artem Titov0e61fdd2021-07-25 19:50:141116 // A copy of the `candidate` will be created and added to the remote
henrike@webrtc.org28e20752013-07-10 00:45:361117 // description. So the caller of this method still has the ownership of the
Artem Titov0e61fdd2021-07-25 19:50:141118 // `candidate`.
Henrik Boströmee6f4f62019-11-06 11:36:121119 // TODO(hbos): The spec mandates chaining this operation onto the operations
1120 // chain; deprecate and remove this version in favor of the callback-based
1121 // signature.
henrike@webrtc.org28e20752013-07-10 00:45:361122 virtual bool AddIceCandidate(const IceCandidateInterface* candidate) = 0;
Henrik Boströmee6f4f62019-11-06 11:36:121123 // TODO(hbos): Remove default implementation once implemented by downstream
1124 // projects.
1125 virtual void AddIceCandidate(std::unique_ptr<IceCandidateInterface> candidate,
1126 std::function<void(RTCError)> callback) {}
henrike@webrtc.org28e20752013-07-10 00:45:361127
deadbeefb10f32f2017-02-08 09:38:211128 // Removes a group of remote candidates from the ICE agent. Needed mainly for
1129 // continual gathering, to avoid an ever-growing list of candidates as
Taylor Brandstetter9e9bf752021-01-26 22:55:381130 // networks come and go. Note that the candidates' transport_name must be set
1131 // to the MID of the m= section that generated the candidate.
1132 // TODO(bugs.webrtc.org/8395): Use IceCandidateInterface instead of
1133 // cricket::Candidate, which would avoid the transport_name oddity.
Honghai Zhang7fb69db2016-03-14 18:59:181134 virtual bool RemoveIceCandidates(
Niels Möller7b04a912019-09-13 13:41:211135 const std::vector<cricket::Candidate>& candidates) = 0;
Honghai Zhang7fb69db2016-03-14 18:59:181136
zstein4b979802017-06-02 21:37:371137 // SetBitrate limits the bandwidth allocated for all RTP streams sent by
1138 // this PeerConnection. Other limitations might affect these limits and
1139 // are respected (for example "b=AS" in SDP).
1140 //
Artem Titov0e61fdd2021-07-25 19:50:141141 // Setting `current_bitrate_bps` will reset the current bitrate estimate
zstein4b979802017-06-02 21:37:371142 // to the provided value.
Niels Möller9ad1f6f2020-07-13 08:25:411143 virtual RTCError SetBitrate(const BitrateSettings& bitrate) = 0;
zstein4b979802017-06-02 21:37:371144
henrika5f6bf242017-11-01 10:06:561145 // Enable/disable playout of received audio streams. Enabled by default. Note
1146 // that even if playout is enabled, streams will only be played out if the
Artem Titov0e61fdd2021-07-25 19:50:141147 // appropriate SDP is also applied. Setting `playout` to false will stop
henrika5f6bf242017-11-01 10:06:561148 // playout of the underlying audio device but starts a task which will poll
1149 // for audio data every 10ms to ensure that audio processing happens and the
1150 // audio statistics are updated.
henrika5f6bf242017-11-01 10:06:561151 virtual void SetAudioPlayout(bool playout) {}
1152
1153 // Enable/disable recording of transmitted audio streams. Enabled by default.
1154 // Note that even if recording is enabled, streams will only be recorded if
1155 // the appropriate SDP is also applied.
henrika5f6bf242017-11-01 10:06:561156 virtual void SetAudioRecording(bool recording) {}
1157
Harald Alvestrandad88c882018-11-28 15:47:461158 // Looks up the DtlsTransport associated with a MID value.
1159 // In the Javascript API, DtlsTransport is a property of a sender, but
1160 // because the PeerConnection owns the DtlsTransport in this implementation,
1161 // it is better to look them up on the PeerConnection.
1162 virtual rtc::scoped_refptr<DtlsTransportInterface> LookupDtlsTransportByMid(
Niels Möller7b04a912019-09-13 13:41:211163 const std::string& mid) = 0;
Harald Alvestrandad88c882018-11-28 15:47:461164
Harald Alvestrandc85328f2019-02-28 06:51:001165 // Returns the SCTP transport, if any.
Niels Möller7b04a912019-09-13 13:41:211166 virtual rtc::scoped_refptr<SctpTransportInterface> GetSctpTransport()
1167 const = 0;
Harald Alvestrandc85328f2019-02-28 06:51:001168
henrike@webrtc.org28e20752013-07-10 00:45:361169 // Returns the current SignalingState.
1170 virtual SignalingState signaling_state() = 0;
Taylor Brandstettercb423c42017-10-22 18:52:321171
Jonas Olsson12046902018-12-06 10:25:141172 // Returns an aggregate state of all ICE *and* DTLS transports.
1173 // This is left in place to avoid breaking native clients who expect our old,
1174 // nonstandard behavior.
1175 // TODO(jonasolsson): deprecate and remove this.
henrike@webrtc.org28e20752013-07-10 00:45:361176 virtual IceConnectionState ice_connection_state() = 0;
Taylor Brandstettercb423c42017-10-22 18:52:321177
Jonas Olsson12046902018-12-06 10:25:141178 // Returns an aggregated state of all ICE transports.
Niels Möller7b04a912019-09-13 13:41:211179 virtual IceConnectionState standardized_ice_connection_state() = 0;
Jonas Olsson12046902018-12-06 10:25:141180
1181 // Returns an aggregated state of all ICE and DTLS transports.
Niels Möller7b04a912019-09-13 13:41:211182 virtual PeerConnectionState peer_connection_state() = 0;
Jonas Olsson635474e2018-10-18 13:58:171183
henrike@webrtc.org28e20752013-07-10 00:45:361184 virtual IceGatheringState ice_gathering_state() = 0;
1185
Harald Alvestrand61f74d92020-03-02 10:20:001186 // Returns the current state of canTrickleIceCandidates per
1187 // https://w3c.github.io/webrtc-pc/#attributes-1
1188 virtual absl::optional<bool> can_trickle_ice_candidates() {
1189 // TODO(crbug.com/708484): Remove default implementation.
1190 return absl::nullopt;
1191 }
1192
Henrik Boström4c1e7cc2020-06-11 10:26:531193 // When a resource is overused, the PeerConnection will try to reduce the load
1194 // on the sysem, for example by reducing the resolution or frame rate of
1195 // encoded streams. The Resource API allows injecting platform-specific usage
1196 // measurements. The conditions to trigger kOveruse or kUnderuse are up to the
1197 // implementation.
1198 // TODO(hbos): Make pure virtual when implemented by downstream projects.
1199 virtual void AddAdaptationResource(rtc::scoped_refptr<Resource> resource) {}
1200
Elad Alon99c3fe52017-10-13 14:29:401201 // Start RtcEventLog using an existing output-sink. Takes ownership of
Artem Titov0e61fdd2021-07-25 19:50:141202 // `output` and passes it on to Call, which will take the ownership. If the
Bjorn Tereliusde939432017-11-20 16:38:141203 // operation fails the output will be closed and deallocated. The event log
Artem Titov0e61fdd2021-07-25 19:50:141204 // will send serialized events to the output object every `output_period_ms`.
Niels Möllerf00ca1a2019-05-10 09:33:121205 // Applications using the event log should generally make their own trade-off
1206 // regarding the output period. A long period is generally more efficient,
1207 // with potential drawbacks being more bursty thread usage, and more events
Artem Titov0e61fdd2021-07-25 19:50:141208 // lost in case the application crashes. If the `output_period_ms` argument is
Niels Möllerf00ca1a2019-05-10 09:33:121209 // omitted, webrtc selects a default deemed to be workable in most cases.
Bjorn Tereliusde939432017-11-20 16:38:141210 virtual bool StartRtcEventLog(std::unique_ptr<RtcEventLogOutput> output,
Niels Möller7b04a912019-09-13 13:41:211211 int64_t output_period_ms) = 0;
1212 virtual bool StartRtcEventLog(std::unique_ptr<RtcEventLogOutput> output) = 0;
Elad Alon99c3fe52017-10-13 14:29:401213
ivoc14d5dbe2016-07-04 14:06:551214 // Stops logging the RtcEventLog.
Niels Möller7b04a912019-09-13 13:41:211215 virtual void StopRtcEventLog() = 0;
ivoc14d5dbe2016-07-04 14:06:551216
deadbeefb10f32f2017-02-08 09:38:211217 // Terminates all media, closes the transports, and in general releases any
1218 // resources used by the PeerConnection. This is an irreversible operation.
deadbeefd07061c2017-04-20 20:19:001219 //
1220 // Note that after this method completes, the PeerConnection will no longer
1221 // use the PeerConnectionObserver interface passed in on construction, and
1222 // thus the observer object can be safely destroyed.
henrike@webrtc.org28e20752013-07-10 00:45:361223 virtual void Close() = 0;
1224
Taylor Brandstetterc88fe702020-08-03 23:36:161225 // The thread on which all PeerConnectionObserver callbacks will be invoked,
1226 // as well as callbacks for other classes such as DataChannelObserver.
1227 //
1228 // Also the only thread on which it's safe to use SessionDescriptionInterface
1229 // pointers.
1230 // TODO(deadbeef): Make pure virtual when all subclasses implement it.
1231 virtual rtc::Thread* signaling_thread() const { return nullptr; }
1232
henrike@webrtc.org28e20752013-07-10 00:45:361233 protected:
1234 // Dtor protected as objects shouldn't be deleted via this interface.
Mirko Bonadei79eb4dd2018-07-19 08:39:301235 ~PeerConnectionInterface() override = default;
henrike@webrtc.org28e20752013-07-10 00:45:361236};
1237
deadbeefb10f32f2017-02-08 09:38:211238// PeerConnection callback interface, used for RTCPeerConnection events.
1239// Application should implement these methods.
henrike@webrtc.org28e20752013-07-10 00:45:361240class PeerConnectionObserver {
1241 public:
Sami Kalliomäki02879f92018-01-11 09:02:191242 virtual ~PeerConnectionObserver() = default;
1243
henrike@webrtc.org28e20752013-07-10 00:45:361244 // Triggered when the SignalingState changed.
1245 virtual void OnSignalingChange(
perkjdfb769d2016-02-09 11:09:431246 PeerConnectionInterface::SignalingState new_state) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:361247
1248 // Triggered when media is received on a new stream from remote peer.
Steve Anton772eb212018-01-16 18:11:061249 virtual void OnAddStream(rtc::scoped_refptr<MediaStreamInterface> stream) {}
henrike@webrtc.org28e20752013-07-10 00:45:361250
Steve Anton3172c032018-05-03 22:30:181251 // Triggered when a remote peer closes a stream.
Steve Anton772eb212018-01-16 18:11:061252 virtual void OnRemoveStream(rtc::scoped_refptr<MediaStreamInterface> stream) {
1253 }
henrike@webrtc.org28e20752013-07-10 00:45:361254
Taylor Brandstetter98cde262016-05-31 20:02:211255 // Triggered when a remote peer opens a data channel.
1256 virtual void OnDataChannel(
nisse7f067662017-03-08 14:59:451257 rtc::scoped_refptr<DataChannelInterface> data_channel) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:361258
Taylor Brandstetter98cde262016-05-31 20:02:211259 // Triggered when renegotiation is needed. For example, an ICE restart
1260 // has begun.
Henrik Boströme574a312020-08-25 08:20:111261 // TODO(hbos): Delete in favor of OnNegotiationNeededEvent() when downstream
1262 // projects have migrated.
1263 virtual void OnRenegotiationNeeded() {}
1264 // Used to fire spec-compliant onnegotiationneeded events, which should only
1265 // fire when the Operations Chain is empty. The observer is responsible for
1266 // queuing a task (e.g. Chromium: jump to main thread) to maybe fire the
Artem Titov0e61fdd2021-07-25 19:50:141267 // event. The event identified using `event_id` must only fire if
Henrik Boströme574a312020-08-25 08:20:111268 // PeerConnection::ShouldFireNegotiationNeededEvent() returns true since it is
1269 // possible for the event to become invalidated by operations subsequently
1270 // chained.
1271 virtual void OnNegotiationNeededEvent(uint32_t event_id) {}
henrike@webrtc.org28e20752013-07-10 00:45:361272
Jonas Olsson12046902018-12-06 10:25:141273 // Called any time the legacy IceConnectionState changes.
deadbeefb10f32f2017-02-08 09:38:211274 //
1275 // Note that our ICE states lag behind the standard slightly. The most
1276 // notable differences include the fact that "failed" occurs after 15
1277 // seconds, not 30, and this actually represents a combination ICE + DTLS
1278 // state, so it may be "failed" if DTLS fails while ICE succeeds.
Jonas Olsson12046902018-12-06 10:25:141279 //
1280 // TODO(jonasolsson): deprecate and remove this.
henrike@webrtc.org28e20752013-07-10 00:45:361281 virtual void OnIceConnectionChange(
Sebastian Jansson6acb0692019-07-30 16:34:091282 PeerConnectionInterface::IceConnectionState new_state) {}
henrike@webrtc.org28e20752013-07-10 00:45:361283
Jonas Olsson12046902018-12-06 10:25:141284 // Called any time the standards-compliant IceConnectionState changes.
1285 virtual void OnStandardizedIceConnectionChange(
1286 PeerConnectionInterface::IceConnectionState new_state) {}
1287
Jonas Olsson635474e2018-10-18 13:58:171288 // Called any time the PeerConnectionState changes.
1289 virtual void OnConnectionChange(
1290 PeerConnectionInterface::PeerConnectionState new_state) {}
1291
Taylor Brandstetter98cde262016-05-31 20:02:211292 // Called any time the IceGatheringState changes.
henrike@webrtc.org28e20752013-07-10 00:45:361293 virtual void OnIceGatheringChange(
perkjdfb769d2016-02-09 11:09:431294 PeerConnectionInterface::IceGatheringState new_state) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:361295
Taylor Brandstetter98cde262016-05-31 20:02:211296 // A new ICE candidate has been gathered.
henrike@webrtc.org28e20752013-07-10 00:45:361297 virtual void OnIceCandidate(const IceCandidateInterface* candidate) = 0;
1298
Eldar Relloda13ea22019-06-01 09:23:431299 // Gathering of an ICE candidate failed.
1300 // See https://w3c.github.io/webrtc-pc/#event-icecandidateerror
Eldar Rello0095d372019-12-02 20:22:071301 virtual void OnIceCandidateError(const std::string& address,
1302 int port,
1303 const std::string& url,
1304 int error_code,
1305 const std::string& error_text) {}
1306
Honghai Zhang7fb69db2016-03-14 18:59:181307 // Ice candidates have been removed.
1308 // TODO(honghaiz): Make this a pure virtual method when all its subclasses
1309 // implement it.
1310 virtual void OnIceCandidatesRemoved(
1311 const std::vector<cricket::Candidate>& candidates) {}
1312
Peter Thatcher54360512015-07-08 18:08:351313 // Called when the ICE connection receiving status changes.
1314 virtual void OnIceConnectionReceivingChange(bool receiving) {}
1315
Alex Drake00c7ecf2019-08-06 17:54:471316 // Called when the selected candidate pair for the ICE connection changes.
1317 virtual void OnIceSelectedCandidatePairChanged(
1318 const cricket::CandidatePairChangeEvent& event) {}
1319
Steve Antonab6ea6b2018-02-26 22:23:091320 // This is called when a receiver and its track are created.
Henrik Boström933d8b02017-10-10 17:05:161321 // TODO(zhihuang): Make this pure virtual when all subclasses implement it.
Steve Anton8b815cd2018-02-17 00:14:421322 // Note: This is called with both Plan B and Unified Plan semantics. Unified
1323 // Plan users should prefer OnTrack, OnAddTrack is only called as backwards
1324 // compatibility (and is called in the exact same situations as OnTrack).
zhihuang81c3a032016-11-17 20:06:241325 virtual void OnAddTrack(
1326 rtc::scoped_refptr<RtpReceiverInterface> receiver,
zhihuangc63b8942016-12-02 23:41:101327 const std::vector<rtc::scoped_refptr<MediaStreamInterface>>& streams) {}
zhihuang81c3a032016-11-17 20:06:241328
Steve Anton8b815cd2018-02-17 00:14:421329 // This is called when signaling indicates a transceiver will be receiving
1330 // media from the remote endpoint. This is fired during a call to
1331 // SetRemoteDescription. The receiving track can be accessed by:
Artem Titovcfea2182021-08-09 23:22:311332 // `transceiver->receiver()->track()` and its associated streams by
1333 // `transceiver->receiver()->streams()`.
Steve Anton8b815cd2018-02-17 00:14:421334 // Note: This will only be called if Unified Plan semantics are specified.
1335 // This behavior is specified in section 2.2.8.2.5 of the "Set the
1336 // RTCSessionDescription" algorithm:
1337 // https://w3c.github.io/webrtc-pc/#set-description
1338 virtual void OnTrack(
1339 rtc::scoped_refptr<RtpTransceiverInterface> transceiver) {}
1340
Steve Anton3172c032018-05-03 22:30:181341 // Called when signaling indicates that media will no longer be received on a
1342 // track.
1343 // With Plan B semantics, the given receiver will have been removed from the
1344 // PeerConnection and the track muted.
1345 // With Unified Plan semantics, the receiver will remain but the transceiver
1346 // will have changed direction to either sendonly or inactive.
Henrik Boström933d8b02017-10-10 17:05:161347 // https://w3c.github.io/webrtc-pc/#process-remote-track-removal
Henrik Boström933d8b02017-10-10 17:05:161348 // TODO(hbos,deadbeef): Make pure virtual when all subclasses implement it.
1349 virtual void OnRemoveTrack(
1350 rtc::scoped_refptr<RtpReceiverInterface> receiver) {}
Harald Alvestrandc0e97252018-07-26 08:39:551351
1352 // Called when an interesting usage is detected by WebRTC.
1353 // An appropriate action is to add information about the context of the
1354 // PeerConnection and write the event to some kind of "interesting events"
1355 // log function.
1356 // The heuristics for defining what constitutes "interesting" are
1357 // implementation-defined.
1358 virtual void OnInterestingUsage(int usage_pattern) {}
henrike@webrtc.org28e20752013-07-10 00:45:361359};
1360
Benjamin Wright6f7e6d62018-05-02 20:46:311361// PeerConnectionDependencies holds all of PeerConnections dependencies.
1362// A dependency is distinct from a configuration as it defines significant
1363// executable code that can be provided by a user of the API.
1364//
1365// All new dependencies should be added as a unique_ptr to allow the
1366// PeerConnection object to be the definitive owner of the dependencies
1367// lifetime making injection safer.
Mirko Bonadei35214fc2019-09-23 12:54:281368struct RTC_EXPORT PeerConnectionDependencies final {
Mirko Bonadei79eb4dd2018-07-19 08:39:301369 explicit PeerConnectionDependencies(PeerConnectionObserver* observer_in);
Benjamin Wright6f7e6d62018-05-02 20:46:311370 // This object is not copyable or assignable.
1371 PeerConnectionDependencies(const PeerConnectionDependencies&) = delete;
1372 PeerConnectionDependencies& operator=(const PeerConnectionDependencies&) =
1373 delete;
1374 // This object is only moveable.
Mirko Bonadei79eb4dd2018-07-19 08:39:301375 PeerConnectionDependencies(PeerConnectionDependencies&&);
Benjamin Wright6f7e6d62018-05-02 20:46:311376 PeerConnectionDependencies& operator=(PeerConnectionDependencies&&) = default;
Mirko Bonadei79eb4dd2018-07-19 08:39:301377 ~PeerConnectionDependencies();
Benjamin Wright6f7e6d62018-05-02 20:46:311378 // Mandatory dependencies
1379 PeerConnectionObserver* observer = nullptr;
1380 // Optional dependencies
Patrik Höglund662e31f2019-09-05 12:35:041381 // TODO(bugs.webrtc.org/7447): remove port allocator once downstream is
Niels Möller573b1452022-06-21 09:37:291382 // updated. The recommended way to inject networking components is to pass a
1383 // PacketSocketFactory when creating the PeerConnectionFactory.
Benjamin Wright6f7e6d62018-05-02 20:46:311384 std::unique_ptr<cricket::PortAllocator> allocator;
Harald Alvestrand0ccfbd22021-04-08 07:25:041385 // 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 20:20:151389 std::unique_ptr<webrtc::AsyncResolverFactory> async_resolver_factory;
Qingsi Wang25ec8882019-11-15 20:33:051390 std::unique_ptr<webrtc::IceTransportFactory> ice_transport_factory;
Benjamin Wright6f7e6d62018-05-02 20:46:311391 std::unique_ptr<rtc::RTCCertificateGeneratorInterface> cert_generator;
Benjamin Wrightd6f86e82018-05-08 20:12:251392 std::unique_ptr<rtc::SSLCertificateVerifier> tls_cert_verifier;
Jonas Orelanda3aa9bd2019-04-17 05:38:401393 std::unique_ptr<webrtc::VideoBitrateAllocatorFactory>
1394 video_bitrate_allocator_factory;
Jonas Oreland6c7f9842022-04-19 15:24:101395 // Optional field trials to use.
1396 // Overrides those from PeerConnectionFactoryDependencies.
1397 std::unique_ptr<FieldTrialsView> trials;
Benjamin Wright6f7e6d62018-05-02 20:46:311398};
1399
Benjamin Wright5234a492018-05-29 22:04:321400// PeerConnectionFactoryDependencies holds all of the PeerConnectionFactory
1401// dependencies. All new dependencies should be added here instead of
1402// overloading the function. This simplifies dependency injection and makes it
1403// clear which are mandatory and optional. If possible please allow the peer
1404// connection factory to take ownership of the dependency by adding a unique_ptr
1405// to this structure.
Mirko Bonadei35214fc2019-09-23 12:54:281406struct RTC_EXPORT PeerConnectionFactoryDependencies final {
Mirko Bonadei79eb4dd2018-07-19 08:39:301407 PeerConnectionFactoryDependencies();
Benjamin Wright5234a492018-05-29 22:04:321408 // This object is not copyable or assignable.
1409 PeerConnectionFactoryDependencies(const PeerConnectionFactoryDependencies&) =
1410 delete;
1411 PeerConnectionFactoryDependencies& operator=(
1412 const PeerConnectionFactoryDependencies&) = delete;
1413 // This object is only moveable.
Mirko Bonadei79eb4dd2018-07-19 08:39:301414 PeerConnectionFactoryDependencies(PeerConnectionFactoryDependencies&&);
Benjamin Wright5234a492018-05-29 22:04:321415 PeerConnectionFactoryDependencies& operator=(
1416 PeerConnectionFactoryDependencies&&) = default;
Mirko Bonadei79eb4dd2018-07-19 08:39:301417 ~PeerConnectionFactoryDependencies();
Benjamin Wright5234a492018-05-29 22:04:321418
1419 // Optional dependencies
1420 rtc::Thread* network_thread = nullptr;
1421 rtc::Thread* worker_thread = nullptr;
1422 rtc::Thread* signaling_thread = nullptr;
Niels Möllerb02e1ac2022-02-04 13:29:501423 rtc::SocketFactory* socket_factory = nullptr;
Niels Möller43455f22022-06-22 07:14:111424 // The `packet_socket_factory` will only be used if CreatePeerConnection is
1425 // called without a `port_allocator`.
Niels Möller573b1452022-06-21 09:37:291426 std::unique_ptr<rtc::PacketSocketFactory> packet_socket_factory;
Danil Chapovalov9435c6102019-04-01 08:33:161427 std::unique_ptr<TaskQueueFactory> task_queue_factory;
Benjamin Wright5234a492018-05-29 22:04:321428 std::unique_ptr<cricket::MediaEngineInterface> media_engine;
1429 std::unique_ptr<CallFactoryInterface> call_factory;
1430 std::unique_ptr<RtcEventLogFactoryInterface> event_log_factory;
1431 std::unique_ptr<FecControllerFactoryInterface> fec_controller_factory;
Ying Wang0810a7c2019-04-10 11:48:241432 std::unique_ptr<NetworkStatePredictorFactoryInterface>
1433 network_state_predictor_factory;
Benjamin Wright5234a492018-05-29 22:04:321434 std::unique_ptr<NetworkControllerFactoryInterface> network_controller_factory;
Niels Möllerd6849d02022-06-21 08:04:441435 // The `network_manager` will only be used if CreatePeerConnection is called
1436 // without a `port_allocator`, causing the default allocator and network
1437 // manager to be used.
Niels Möllerdcb5a582022-06-20 13:33:591438 std::unique_ptr<rtc::NetworkManager> network_manager;
Niels Möllerd6849d02022-06-21 08:04:441439 // The `network_monitor_factory` will only be used if CreatePeerConnection is
1440 // called without a `port_allocator`, and the above `network_manager' is null.
Taylor Brandstetter239ac8a2020-07-31 23:07:521441 std::unique_ptr<rtc::NetworkMonitorFactory> network_monitor_factory;
Ivo Creusenc3d1f9b2019-11-01 10:47:511442 std::unique_ptr<NetEqFactory> neteq_factory;
Per Kjellander2bca0082020-08-28 07:15:151443 std::unique_ptr<SctpTransportFactoryInterface> sctp_factory;
Jonas Orelande62c2f22022-03-29 09:04:481444 std::unique_ptr<FieldTrialsView> trials;
Vojin Ilic504fc192021-05-31 12:02:281445 std::unique_ptr<RtpTransportControllerSendFactoryInterface>
1446 transport_controller_send_factory;
Evan Shrubsole7c023f52022-02-04 16:19:431447 std::unique_ptr<Metronome> metronome;
Benjamin Wright5234a492018-05-29 22:04:321448};
1449
deadbeefb10f32f2017-02-08 09:38:211450// PeerConnectionFactoryInterface is the factory interface used for creating
1451// PeerConnection, MediaStream and MediaStreamTrack objects.
1452//
1453// The simplest method for obtaiing one, CreatePeerConnectionFactory will
1454// create the required libjingle threads, socket and network manager factory
1455// classes for networking if none are provided, though it requires that the
1456// application runs a message loop on the thread that called the method (see
1457// explanation below)
1458//
1459// If an application decides to provide its own threads and/or implementation
1460// of networking classes, it should use the alternate
1461// CreatePeerConnectionFactory method which accepts threads as input, and use
1462// the CreatePeerConnection version that takes a PortAllocator as an argument.
Ken MacKay831ce5f2019-12-02 18:26:341463class RTC_EXPORT PeerConnectionFactoryInterface
1464 : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:361465 public:
wu@webrtc.org97077a32013-10-25 21:18:331466 class Options {
1467 public:
Benjamin Wrighta54daf12018-10-11 22:33:171468 Options() {}
deadbeefb10f32f2017-02-08 09:38:211469
1470 // If set to true, created PeerConnections won't enforce any SRTP
1471 // requirement, allowing unsecured media. Should only be used for
1472 // testing/debugging.
1473 bool disable_encryption = false;
1474
deadbeefb10f32f2017-02-08 09:38:211475 // If set to true, any platform-supported network monitoring capability
1476 // won't be used, and instead networks will only be updated via polling.
1477 //
1478 // This only has an effect if a PeerConnection is created with the default
1479 // PortAllocator implementation.
1480 bool disable_network_monitor = false;
phoglund@webrtc.org006521d2015-02-12 09:23:591481
1482 // Sets the network types to ignore. For instance, calling this with
1483 // ADAPTER_TYPE_ETHERNET | ADAPTER_TYPE_LOOPBACK will ignore Ethernet and
1484 // loopback interfaces.
deadbeefb10f32f2017-02-08 09:38:211485 int network_ignore_mask = rtc::kDefaultNetworkIgnoreMask;
Joachim Bauch04e5b492015-05-29 07:40:391486
1487 // Sets the maximum supported protocol version. The highest version
1488 // supported by both ends will be used for the connection, i.e. if one
1489 // party supports DTLS 1.0 and the other DTLS 1.2, DTLS 1.0 will be used.
deadbeefb10f32f2017-02-08 09:38:211490 rtc::SSLProtocolVersion ssl_max_version = rtc::SSL_PROTOCOL_DTLS_12;
jbauchcb560652016-08-04 12:20:321491
1492 // Sets crypto related options, e.g. enabled cipher suites.
Benjamin Wrighta54daf12018-10-11 22:33:171493 CryptoOptions crypto_options = CryptoOptions::NoGcm();
wu@webrtc.org97077a32013-10-25 21:18:331494 };
1495
deadbeef7914b8c2017-04-21 10:23:331496 // Set the options to be used for subsequently created PeerConnections.
wu@webrtc.org97077a32013-10-25 21:18:331497 virtual void SetOptions(const Options& options) = 0;
buildbot@webrtc.org41451d42014-05-03 05:39:451498
Benjamin Wright6f7e6d62018-05-02 20:46:311499 // The preferred way to create a new peer connection. Simply provide the
1500 // configuration and a PeerConnectionDependencies structure.
1501 // TODO(benwright): Make pure virtual once downstream mock PC factory classes
1502 // are updated.
Harald Alvestranda3dd7722020-11-27 08:05:421503 virtual RTCErrorOr<rtc::scoped_refptr<PeerConnectionInterface>>
1504 CreatePeerConnectionOrError(
1505 const PeerConnectionInterface::RTCConfiguration& configuration,
1506 PeerConnectionDependencies dependencies);
1507 // Deprecated creator - does not return an error code on error.
1508 // TODO(bugs.webrtc.org:12238): Deprecate and remove.
Harald Alvestrandf33f7a22021-05-09 14:58:571509 ABSL_DEPRECATED("Use CreatePeerConnectionOrError")
Benjamin Wright6f7e6d62018-05-02 20:46:311510 virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection(
1511 const PeerConnectionInterface::RTCConfiguration& configuration,
Mirko Bonadei79eb4dd2018-07-19 08:39:301512 PeerConnectionDependencies dependencies);
Benjamin Wright6f7e6d62018-05-02 20:46:311513
Artem Titov0e61fdd2021-07-25 19:50:141514 // Deprecated; `allocator` and `cert_generator` may be null, in which case
Benjamin Wright6f7e6d62018-05-02 20:46:311515 // default implementations will be used.
deadbeefd07061c2017-04-20 20:19:001516 //
Artem Titov0e61fdd2021-07-25 19:50:141517 // `observer` must not be null.
deadbeefd07061c2017-04-20 20:19:001518 //
Artem Titov0e61fdd2021-07-25 19:50:141519 // Note that this method does not take ownership of `observer`; it's the
deadbeefd07061c2017-04-20 20:19:001520 // responsibility of the caller to delete it. It can be safely deleted after
1521 // Close has been called on the returned PeerConnection, which ensures no
1522 // more observer callbacks will be invoked.
Harald Alvestrandf33f7a22021-05-09 14:58:571523 ABSL_DEPRECATED("Use CreatePeerConnectionOrError")
deadbeef41b07982015-12-01 23:01:241524 virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection(
1525 const PeerConnectionInterface::RTCConfiguration& configuration,
kwibergd1fe2812016-04-27 13:47:291526 std::unique_ptr<cricket::PortAllocator> allocator,
Henrik Boströmd03c23b2016-06-01 09:44:181527 std::unique_ptr<rtc::RTCCertificateGeneratorInterface> cert_generator,
Mirko Bonadei79eb4dd2018-07-19 08:39:301528 PeerConnectionObserver* observer);
1529
Artem Titov0e61fdd2021-07-25 19:50:141530 // Returns the capabilities of an RTP sender of type `kind`.
Florent Castelli72b751a2018-06-28 12:09:331531 // If for some reason you pass in MEDIA_TYPE_DATA, returns an empty structure.
1532 // TODO(orphis): Make pure virtual when all subclasses implement it.
1533 virtual RtpCapabilities GetRtpSenderCapabilities(
Mirko Bonadei79eb4dd2018-07-19 08:39:301534 cricket::MediaType kind) const;
Florent Castelli72b751a2018-06-28 12:09:331535
Artem Titov0e61fdd2021-07-25 19:50:141536 // Returns the capabilities of an RTP receiver of type `kind`.
Florent Castelli72b751a2018-06-28 12:09:331537 // If for some reason you pass in MEDIA_TYPE_DATA, returns an empty structure.
1538 // TODO(orphis): Make pure virtual when all subclasses implement it.
1539 virtual RtpCapabilities GetRtpReceiverCapabilities(
Mirko Bonadei79eb4dd2018-07-19 08:39:301540 cricket::MediaType kind) const;
Florent Castelli72b751a2018-06-28 12:09:331541
Seth Hampson845e8782018-03-02 19:34:101542 virtual rtc::scoped_refptr<MediaStreamInterface> CreateLocalMediaStream(
1543 const std::string& stream_id) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:361544
deadbeefe814a0d2017-02-26 02:15:091545 // Creates an AudioSourceInterface.
Artem Titov0e61fdd2021-07-25 19:50:141546 // `options` decides audio processing settings.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:521547 virtual rtc::scoped_refptr<AudioSourceInterface> CreateAudioSource(
htaa2a49d92016-03-04 10:51:391548 const cricket::AudioOptions& options) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:361549
Artem Titov0e61fdd2021-07-25 19:50:141550 // Creates a new local VideoTrack. The same `source` can be used in several
henrike@webrtc.org28e20752013-07-10 00:45:361551 // tracks.
perkja3ede6c2016-03-08 00:27:481552 virtual rtc::scoped_refptr<VideoTrackInterface> CreateVideoTrack(
Harald Alvestrand041ecb82023-03-20 14:13:421553 rtc::scoped_refptr<VideoTrackSourceInterface> source,
1554 absl::string_view label) = 0;
Harald Alvestrandd32e5b32023-03-26 06:33:511555 ABSL_DEPRECATED("Use version with scoped_refptr")
Harald Alvestrand041ecb82023-03-20 14:13:421556 virtual rtc::scoped_refptr<VideoTrackInterface> CreateVideoTrack(
perkja3ede6c2016-03-08 00:27:481557 const std::string& label,
Harald Alvestrand041ecb82023-03-20 14:13:421558 VideoTrackSourceInterface* source) {
1559 return CreateVideoTrack(
1560 rtc::scoped_refptr<VideoTrackSourceInterface>(source), label);
1561 }
henrike@webrtc.org28e20752013-07-10 00:45:361562
Artem Titov0e61fdd2021-07-25 19:50:141563 // Creates an new AudioTrack. At the moment `source` can be null.
Yves Gerey665174f2018-06-19 13:03:051564 virtual rtc::scoped_refptr<AudioTrackInterface> CreateAudioTrack(
1565 const std::string& label,
1566 AudioSourceInterface* source) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:361567
Artem Titov0e61fdd2021-07-25 19:50:141568 // Starts AEC dump using existing file. Takes ownership of `file` and passes
wu@webrtc.orga9890802013-12-13 00:21:031569 // it on to VoiceEngine (via other objects) immediately, which will take
wu@webrtc.orga8910d22014-01-23 22:12:451570 // the ownerhip. If the operation fails, the file will be closed.
ivocd66b44d2016-01-15 11:06:361571 // A maximum file size in bytes can be specified. When the file size limit is
1572 // reached, logging is stopped automatically. If max_size_bytes is set to a
1573 // value <= 0, no limit will be used, and logging will continue until the
1574 // StopAecDump function is called.
Niels Möllere8e4dc42019-06-11 12:04:161575 // TODO(webrtc:6463): Delete default implementation when downstream mocks
1576 // classes are updated.
1577 virtual bool StartAecDump(FILE* file, int64_t max_size_bytes) {
1578 return false;
1579 }
wu@webrtc.orga9890802013-12-13 00:21:031580
ivoc797ef122015-10-22 10:25:411581 // Stops logging the AEC dump.
1582 virtual void StopAecDump() = 0;
1583
henrike@webrtc.org28e20752013-07-10 00:45:361584 protected:
1585 // Dtor and ctor protected as objects shouldn't be created or deleted via
1586 // this interface.
1587 PeerConnectionFactoryInterface() {}
Mirko Bonadei79eb4dd2018-07-19 08:39:301588 ~PeerConnectionFactoryInterface() override = default;
henrike@webrtc.org28e20752013-07-10 00:45:361589};
1590
Danil Chapovalov3b112e22019-05-20 12:36:001591// CreateModularPeerConnectionFactory is implemented in the "peerconnection"
1592// build target, which doesn't pull in the implementations of every module
1593// webrtc may use.
zhihuang38ede132017-06-15 19:52:321594//
1595// If an application knows it will only require certain modules, it can reduce
1596// webrtc's impact on its binary size by depending only on the "peerconnection"
1597// target and the modules the application requires, using
Danil Chapovalov3b112e22019-05-20 12:36:001598// CreateModularPeerConnectionFactory. For example, if an application
zhihuang38ede132017-06-15 19:52:321599// only uses WebRTC for audio, it can pass in null pointers for the
1600// video-specific interfaces, and omit the corresponding modules from its
1601// build.
1602//
Artem Titov0e61fdd2021-07-25 19:50:141603// If `network_thread` or `worker_thread` are null, the PeerConnectionFactory
1604// will create the necessary thread internally. If `signaling_thread` is null,
zhihuang38ede132017-06-15 19:52:321605// the PeerConnectionFactory will use the thread on which this method is called
1606// as the signaling thread, wrapping it in an rtc::Thread object if needed.
Mirko Bonadei35214fc2019-09-23 12:54:281607RTC_EXPORT rtc::scoped_refptr<PeerConnectionFactoryInterface>
Benjamin Wright5234a492018-05-29 22:04:321608CreateModularPeerConnectionFactory(
1609 PeerConnectionFactoryDependencies dependencies);
1610
Harald Alvestrand31b03e92021-11-02 10:54:381611// https://w3c.github.io/webrtc-pc/#dom-rtcsignalingstate
1612inline constexpr absl::string_view PeerConnectionInterface::AsString(
1613 SignalingState state) {
1614 switch (state) {
1615 case SignalingState::kStable:
1616 return "stable";
1617 case SignalingState::kHaveLocalOffer:
1618 return "have-local-offer";
1619 case SignalingState::kHaveLocalPrAnswer:
1620 return "have-local-pranswer";
1621 case SignalingState::kHaveRemoteOffer:
1622 return "have-remote-offer";
1623 case SignalingState::kHaveRemotePrAnswer:
1624 return "have-remote-pranswer";
1625 case SignalingState::kClosed:
1626 return "closed";
1627 }
Henrik Boström49a1d622022-01-24 08:19:421628 // This cannot happen.
1629 // Not using "RTC_CHECK_NOTREACHED()" because AsString() is constexpr.
Harald Alvestrand31b03e92021-11-02 10:54:381630 return "";
1631}
1632
1633// https://w3c.github.io/webrtc-pc/#dom-rtcicegatheringstate
1634inline constexpr absl::string_view PeerConnectionInterface::AsString(
1635 IceGatheringState state) {
1636 switch (state) {
1637 case IceGatheringState::kIceGatheringNew:
1638 return "new";
1639 case IceGatheringState::kIceGatheringGathering:
1640 return "gathering";
1641 case IceGatheringState::kIceGatheringComplete:
1642 return "complete";
1643 }
Henrik Boström49a1d622022-01-24 08:19:421644 // This cannot happen.
1645 // Not using "RTC_CHECK_NOTREACHED()" because AsString() is constexpr.
Harald Alvestrand31b03e92021-11-02 10:54:381646 return "";
1647}
1648
1649// https://w3c.github.io/webrtc-pc/#dom-rtciceconnectionstate
1650inline constexpr absl::string_view PeerConnectionInterface::AsString(
1651 PeerConnectionState state) {
1652 switch (state) {
1653 case PeerConnectionState::kNew:
1654 return "new";
1655 case PeerConnectionState::kConnecting:
1656 return "connecting";
1657 case PeerConnectionState::kConnected:
1658 return "connected";
1659 case PeerConnectionState::kDisconnected:
1660 return "disconnected";
1661 case PeerConnectionState::kFailed:
1662 return "failed";
1663 case PeerConnectionState::kClosed:
1664 return "closed";
1665 }
Henrik Boström49a1d622022-01-24 08:19:421666 // This cannot happen.
1667 // Not using "RTC_CHECK_NOTREACHED()" because AsString() is constexpr.
Harald Alvestrand31b03e92021-11-02 10:54:381668 return "";
1669}
1670
1671inline constexpr absl::string_view PeerConnectionInterface::AsString(
1672 IceConnectionState state) {
1673 switch (state) {
1674 case kIceConnectionNew:
1675 return "new";
1676 case kIceConnectionChecking:
1677 return "checking";
1678 case kIceConnectionConnected:
1679 return "connected";
1680 case kIceConnectionCompleted:
1681 return "completed";
1682 case kIceConnectionFailed:
1683 return "failed";
1684 case kIceConnectionDisconnected:
1685 return "disconnected";
1686 case kIceConnectionClosed:
1687 return "closed";
1688 case kIceConnectionMax:
Henrik Boström49a1d622022-01-24 08:19:421689 // This cannot happen.
1690 // Not using "RTC_CHECK_NOTREACHED()" because AsString() is constexpr.
Harald Alvestrand31b03e92021-11-02 10:54:381691 return "";
1692 }
Henrik Boström49a1d622022-01-24 08:19:421693 // This cannot happen.
1694 // Not using "RTC_CHECK_NOTREACHED()" because AsString() is constexpr.
Harald Alvestrand31b03e92021-11-02 10:54:381695 return "";
1696}
1697
henrike@webrtc.org28e20752013-07-10 00:45:361698} // namespace webrtc
1699
Steve Anton10542f22019-01-11 17:11:001700#endif // API_PEER_CONNECTION_INTERFACE_H_