blob: ceec13ab0c85cd2fe6aae8193d9b669c71a28bab [file] [log] [blame]
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001/*
kjellanderb24317b2016-02-10 07:54:43 -08002 * Copyright 2012 The WebRTC project authors. All Rights Reserved.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00003 *
kjellanderb24317b2016-02-10 07:54:43 -08004 * Use of this source code is governed by a BSD-style license
5 * that can be found in the LICENSE file in the root of the source
6 * tree. An additional intellectual property rights grant can be found
7 * in the file PATENTS. All contributing project authors may
8 * be found in the AUTHORS file in the root of the source tree.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00009 */
10
11// This file contains the PeerConnection interface as defined in
Steve Antonab6ea6b2018-02-26 14:23:09 -080012// https://w3c.github.io/webrtc-pc/#peer-to-peer-connections
henrike@webrtc.org28e20752013-07-10 00:45:36 +000013//
deadbeefb10f32f2017-02-08 01:38:21 -080014// The PeerConnectionFactory class provides factory methods to create
15// PeerConnection, MediaStream and MediaStreamTrack objects.
16//
17// The following steps are needed to setup a typical call using WebRTC:
18//
henrike@webrtc.org28e20752013-07-10 00:45:36 +000019// 1. Create a PeerConnectionFactoryInterface. Check constructors for more
20// information about input parameters.
deadbeefb10f32f2017-02-08 01:38:21 -080021//
22// 2. Create a PeerConnection object. Provide a configuration struct which
23// points to STUN and/or TURN servers used to generate ICE candidates, and
24// provide an object that implements the PeerConnectionObserver interface,
25// which is used to receive callbacks from the PeerConnection.
26//
27// 3. Create local MediaStreamTracks using the PeerConnectionFactory and add
28// them to PeerConnection by calling AddTrack (or legacy method, AddStream).
29//
30// 4. Create an offer, call SetLocalDescription with it, serialize it, and send
31// it to the remote peer
32//
33// 5. Once an ICE candidate has been gathered, the PeerConnection will call the
henrike@webrtc.org28e20752013-07-10 00:45:36 +000034// observer function OnIceCandidate. The candidates must also be serialized and
35// sent to the remote peer.
deadbeefb10f32f2017-02-08 01:38:21 -080036//
henrike@webrtc.org28e20752013-07-10 00:45:36 +000037// 6. Once an answer is received from the remote peer, call
deadbeefb10f32f2017-02-08 01:38:21 -080038// SetRemoteDescription with the remote answer.
39//
henrike@webrtc.org28e20752013-07-10 00:45:36 +000040// 7. Once a remote candidate is received from the remote peer, provide it to
deadbeefb10f32f2017-02-08 01:38:21 -080041// the PeerConnection by calling AddIceCandidate.
42//
43// The receiver of a call (assuming the application is "call"-based) can decide
44// to accept or reject the call; this decision will be taken by the application,
45// not the PeerConnection.
46//
47// If the application decides to accept the call, it should:
48//
henrike@webrtc.org28e20752013-07-10 00:45:36 +000049// 1. Create PeerConnectionFactoryInterface if it doesn't exist.
deadbeefb10f32f2017-02-08 01:38:21 -080050//
henrike@webrtc.org28e20752013-07-10 00:45:36 +000051// 2. Create a new PeerConnection.
deadbeefb10f32f2017-02-08 01:38:21 -080052//
henrike@webrtc.org28e20752013-07-10 00:45:36 +000053// 3. Provide the remote offer to the new PeerConnection object by calling
deadbeefb10f32f2017-02-08 01:38:21 -080054// SetRemoteDescription.
55//
henrike@webrtc.org28e20752013-07-10 00:45:36 +000056// 4. Generate an answer to the remote offer by calling CreateAnswer and send it
57// back to the remote peer.
deadbeefb10f32f2017-02-08 01:38:21 -080058//
henrike@webrtc.org28e20752013-07-10 00:45:36 +000059// 5. Provide the local answer to the new PeerConnection by calling
deadbeefb10f32f2017-02-08 01:38:21 -080060// SetLocalDescription with the answer.
61//
62// 6. Provide the remote ICE candidates by calling AddIceCandidate.
63//
64// 7. Once a candidate has been gathered, the PeerConnection will call the
65// observer function OnIceCandidate. Send these candidates to the remote peer.
henrike@webrtc.org28e20752013-07-10 00:45:36 +000066
Steve Anton10542f22019-01-11 09:11:00 -080067#ifndef API_PEER_CONNECTION_INTERFACE_H_
68#define API_PEER_CONNECTION_INTERFACE_H_
henrike@webrtc.org28e20752013-07-10 00:45:36 +000069
kwibergd1fe2812016-04-27 06:47:29 -070070#include <memory>
henrike@webrtc.org28e20752013-07-10 00:45:36 +000071#include <string>
72#include <vector>
73
Steve Anton10542f22019-01-11 09:11:00 -080074#include "api/async_resolver_factory.h"
Niels Möllerd377f042018-02-13 15:03:43 +010075#include "api/audio/audio_mixer.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020076#include "api/audio_codecs/audio_decoder_factory.h"
77#include "api/audio_codecs/audio_encoder_factory.h"
Niels Möllera6fe2612018-01-19 11:28:54 +010078#include "api/audio_options.h"
Steve Anton10542f22019-01-11 09:11:00 -080079#include "api/call/call_factory_interface.h"
80#include "api/crypto/crypto_options.h"
81#include "api/data_channel_interface.h"
Ying Wang0dd1b0a2018-02-20 12:50:27 +010082#include "api/fec_controller.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020083#include "api/jsep.h"
Steve Anton10542f22019-01-11 09:11:00 -080084#include "api/media_stream_interface.h"
Piotr (Peter) Slatalae0c2e972018-10-08 09:43:21 -070085#include "api/media_transport_interface.h"
Ying Wang0810a7c2019-04-10 13:48:24 +020086#include "api/network_state_predictor.h"
Steve Anton10542f22019-01-11 09:11:00 -080087#include "api/rtc_error.h"
Danil Chapovalovb32f2c72019-05-22 13:39:25 +020088#include "api/rtc_event_log/rtc_event_log_factory_interface.h"
Steve Anton10542f22019-01-11 09:11:00 -080089#include "api/rtc_event_log_output.h"
90#include "api/rtp_receiver_interface.h"
91#include "api/rtp_sender_interface.h"
92#include "api/rtp_transceiver_interface.h"
93#include "api/set_remote_description_observer_interface.h"
94#include "api/stats/rtc_stats_collector_callback.h"
95#include "api/stats_types.h"
Danil Chapovalov9435c612019-04-01 10:33:16 +020096#include "api/task_queue/task_queue_factory.h"
Niels Möller0c4f7be2018-05-07 14:01:37 +020097#include "api/transport/bitrate_settings.h"
Sebastian Janssondfce03a2018-05-18 18:05:10 +020098#include "api/transport/network_control.h"
Steve Anton10542f22019-01-11 09:11:00 -080099#include "api/turn_customizer.h"
Steve Anton10542f22019-01-11 09:11:00 -0800100#include "media/base/media_config.h"
Niels Möller8366e172018-02-14 12:20:13 +0100101// TODO(bugs.webrtc.org/7447): We plan to provide a way to let applications
102// inject a PacketSocketFactory and/or NetworkManager, and not expose
103// PortAllocator in the PeerConnection api.
Steve Anton10542f22019-01-11 09:11:00 -0800104#include "media/base/media_engine.h" // nogncheck
105#include "p2p/base/port_allocator.h" // nogncheck
Niels Möller8366e172018-02-14 12:20:13 +0100106// TODO(nisse): The interface for bitrate allocation strategy belongs in api/.
Steve Anton10542f22019-01-11 09:11:00 -0800107#include "rtc_base/bitrate_allocation_strategy.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +0200108#include "rtc_base/network.h"
Niels Möller8366e172018-02-14 12:20:13 +0100109#include "rtc_base/platform_file.h"
Steve Anton10542f22019-01-11 09:11:00 -0800110#include "rtc_base/rtc_certificate.h"
111#include "rtc_base/rtc_certificate_generator.h"
112#include "rtc_base/socket_address.h"
113#include "rtc_base/ssl_certificate.h"
114#include "rtc_base/ssl_stream_adapter.h"
Mirko Bonadei276827c2018-10-16 14:13:50 +0200115#include "rtc_base/system/rtc_export.h"
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000116
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000117namespace rtc {
jiayl@webrtc.org61e00b02015-03-04 22:17:38 +0000118class SSLIdentity;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000119class Thread;
Yves Gerey665174f2018-06-19 15:03:05 +0200120} // namespace rtc
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000121
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000122namespace webrtc {
123class AudioDeviceModule;
gyzhou95aa9642016-12-13 14:06:26 -0800124class AudioMixer;
Niels Möller8366e172018-02-14 12:20:13 +0100125class AudioProcessing;
Harald Alvestrandad88c882018-11-28 16:47:46 +0100126class DtlsTransportInterface;
Harald Alvestrandc85328f2019-02-28 07:51:00 +0100127class SctpTransportInterface;
Magnus Jedvert58b03162017-09-15 19:02:47 +0200128class VideoDecoderFactory;
129class VideoEncoderFactory;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000130
131// MediaStream container interface.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000132class StreamCollectionInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000133 public:
134 // TODO(ronghuawu): Update the function names to c++ style, e.g. find -> Find.
135 virtual size_t count() = 0;
136 virtual MediaStreamInterface* at(size_t index) = 0;
137 virtual MediaStreamInterface* find(const std::string& label) = 0;
Yves Gerey665174f2018-06-19 15:03:05 +0200138 virtual MediaStreamTrackInterface* FindAudioTrack(const std::string& id) = 0;
139 virtual MediaStreamTrackInterface* FindVideoTrack(const std::string& id) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000140
141 protected:
142 // Dtor protected as objects shouldn't be deleted via this interface.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200143 ~StreamCollectionInterface() override = default;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000144};
145
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000146class StatsObserver : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000147 public:
nissee8abe3e2017-01-18 05:00:34 -0800148 virtual void OnComplete(const StatsReports& reports) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000149
150 protected:
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200151 ~StatsObserver() override = default;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000152};
153
Steve Anton3acffc32018-04-12 17:21:03 -0700154enum class SdpSemantics { kPlanB, kUnifiedPlan };
Steve Anton79e79602017-11-20 10:25:56 -0800155
Mirko Bonadei66e76792019-04-02 11:33:59 +0200156class RTC_EXPORT PeerConnectionInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000157 public:
Jonas Olsson635474e2018-10-18 15:58:17 +0200158 // See https://w3c.github.io/webrtc-pc/#dom-rtcsignalingstate
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000159 enum SignalingState {
160 kStable,
161 kHaveLocalOffer,
162 kHaveLocalPrAnswer,
163 kHaveRemoteOffer,
164 kHaveRemotePrAnswer,
165 kClosed,
166 };
167
Jonas Olsson635474e2018-10-18 15:58:17 +0200168 // See https://w3c.github.io/webrtc-pc/#dom-rtcicegatheringstate
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000169 enum IceGatheringState {
170 kIceGatheringNew,
171 kIceGatheringGathering,
172 kIceGatheringComplete
173 };
174
Jonas Olsson635474e2018-10-18 15:58:17 +0200175 // See https://w3c.github.io/webrtc-pc/#dom-rtcpeerconnectionstate
176 enum class PeerConnectionState {
177 kNew,
178 kConnecting,
179 kConnected,
180 kDisconnected,
181 kFailed,
182 kClosed,
183 };
184
185 // See https://w3c.github.io/webrtc-pc/#dom-rtciceconnectionstate
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000186 enum IceConnectionState {
187 kIceConnectionNew,
188 kIceConnectionChecking,
189 kIceConnectionConnected,
190 kIceConnectionCompleted,
191 kIceConnectionFailed,
192 kIceConnectionDisconnected,
193 kIceConnectionClosed,
Guo-wei Shieh3d564c12015-08-19 16:51:15 -0700194 kIceConnectionMax,
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000195 };
196
hnsl04833622017-01-09 08:35:45 -0800197 // TLS certificate policy.
198 enum TlsCertPolicy {
199 // For TLS based protocols, ensure the connection is secure by not
200 // circumventing certificate validation.
201 kTlsCertPolicySecure,
202 // For TLS based protocols, disregard security completely by skipping
203 // certificate validation. This is insecure and should never be used unless
204 // security is irrelevant in that particular context.
205 kTlsCertPolicyInsecureNoCheck,
206 };
207
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000208 struct IceServer {
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200209 IceServer();
210 IceServer(const IceServer&);
211 ~IceServer();
212
Joachim Bauch7c4e7452015-05-28 23:06:30 +0200213 // TODO(jbauch): Remove uri when all code using it has switched to urls.
Emad Omaradab1d2d2017-06-16 15:43:11 -0700214 // List of URIs associated with this server. Valid formats are described
215 // in RFC7064 and RFC7065, and more may be added in the future. The "host"
216 // part of the URI may contain either an IP address or a hostname.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000217 std::string uri;
Joachim Bauch7c4e7452015-05-28 23:06:30 +0200218 std::vector<std::string> urls;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000219 std::string username;
220 std::string password;
hnsl04833622017-01-09 08:35:45 -0800221 TlsCertPolicy tls_cert_policy = kTlsCertPolicySecure;
Emad Omaradab1d2d2017-06-16 15:43:11 -0700222 // If the URIs in |urls| only contain IP addresses, this field can be used
223 // to indicate the hostname, which may be necessary for TLS (using the SNI
224 // extension). If |urls| itself contains the hostname, this isn't
225 // necessary.
226 std::string hostname;
Diogo Real1dca9d52017-08-29 12:18:32 -0700227 // List of protocols to be used in the TLS ALPN extension.
228 std::vector<std::string> tls_alpn_protocols;
Diogo Real7bd1f1b2017-09-08 12:50:41 -0700229 // List of elliptic curves to be used in the TLS elliptic curves extension.
230 std::vector<std::string> tls_elliptic_curves;
hnsl04833622017-01-09 08:35:45 -0800231
deadbeefd1a38b52016-12-10 13:15:33 -0800232 bool operator==(const IceServer& o) const {
233 return uri == o.uri && urls == o.urls && username == o.username &&
Emad Omaradab1d2d2017-06-16 15:43:11 -0700234 password == o.password && tls_cert_policy == o.tls_cert_policy &&
Diogo Real1dca9d52017-08-29 12:18:32 -0700235 hostname == o.hostname &&
Diogo Real7bd1f1b2017-09-08 12:50:41 -0700236 tls_alpn_protocols == o.tls_alpn_protocols &&
Sergey Silkin9c147dd2018-09-12 10:45:38 +0000237 tls_elliptic_curves == o.tls_elliptic_curves;
deadbeefd1a38b52016-12-10 13:15:33 -0800238 }
239 bool operator!=(const IceServer& o) const { return !(*this == o); }
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000240 };
241 typedef std::vector<IceServer> IceServers;
242
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000243 enum IceTransportsType {
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000244 // TODO(pthatcher): Rename these kTransporTypeXXX, but update
245 // Chromium at the same time.
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000246 kNone,
247 kRelay,
248 kNoHost,
249 kAll
250 };
251
Steve Antonab6ea6b2018-02-26 14:23:09 -0800252 // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-24#section-4.1.1
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000253 enum BundlePolicy {
254 kBundlePolicyBalanced,
255 kBundlePolicyMaxBundle,
256 kBundlePolicyMaxCompat
257 };
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000258
Steve Antonab6ea6b2018-02-26 14:23:09 -0800259 // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-24#section-4.1.1
Peter Thatcheraf55ccc2015-05-21 07:48:41 -0700260 enum RtcpMuxPolicy {
261 kRtcpMuxPolicyNegotiate,
262 kRtcpMuxPolicyRequire,
263 };
264
Jiayang Liucac1b382015-04-30 12:35:24 -0700265 enum TcpCandidatePolicy {
266 kTcpCandidatePolicyEnabled,
267 kTcpCandidatePolicyDisabled
268 };
269
honghaiz60347052016-05-31 18:29:12 -0700270 enum CandidateNetworkPolicy {
271 kCandidateNetworkPolicyAll,
272 kCandidateNetworkPolicyLowCost
273 };
274
Yves Gerey665174f2018-06-19 15:03:05 +0200275 enum ContinualGatheringPolicy { GATHER_ONCE, GATHER_CONTINUALLY };
honghaiz1f429e32015-09-28 07:57:34 -0700276
Honghai Zhangf7ddc062016-09-01 15:34:01 -0700277 enum class RTCConfigurationType {
278 // A configuration that is safer to use, despite not having the best
279 // performance. Currently this is the default configuration.
280 kSafe,
281 // An aggressive configuration that has better performance, although it
282 // may be riskier and may need extra support in the application.
283 kAggressive
284 };
285
Henrik Boström87713d02015-08-25 09:53:21 +0200286 // TODO(hbos): Change into class with private data and public getters.
nissec36b31b2016-04-11 23:25:29 -0700287 // TODO(nisse): In particular, accessing fields directly from an
288 // application is brittle, since the organization mirrors the
289 // organization of the implementation, which isn't stable. So we
290 // need getters and setters at least for fields which applications
291 // are interested in.
Mirko Bonadeiac194142018-10-22 17:08:37 +0200292 struct RTC_EXPORT RTCConfiguration {
Niels Möller71bdda02016-03-31 12:59:59 +0200293 // This struct is subject to reorganization, both for naming
294 // consistency, and to group settings to match where they are used
295 // in the implementation. To do that, we need getter and setter
296 // methods for all settings which are of interest to applications,
297 // Chrome in particular.
298
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200299 RTCConfiguration();
300 RTCConfiguration(const RTCConfiguration&);
301 explicit RTCConfiguration(RTCConfigurationType type);
302 ~RTCConfiguration();
Honghai Zhangbfd398c2016-08-30 22:07:42 -0700303
deadbeef293e9262017-01-11 12:28:30 -0800304 bool operator==(const RTCConfiguration& o) const;
305 bool operator!=(const RTCConfiguration& o) const;
306
Niels Möller6539f692018-01-18 08:58:50 +0100307 bool dscp() const { return media_config.enable_dscp; }
nissec36b31b2016-04-11 23:25:29 -0700308 void set_dscp(bool enable) { media_config.enable_dscp = enable; }
Niels Möller71bdda02016-03-31 12:59:59 +0200309
Niels Möller6539f692018-01-18 08:58:50 +0100310 bool cpu_adaptation() const {
Niels Möller1d7ecd22018-01-18 15:25:12 +0100311 return media_config.video.enable_cpu_adaptation;
nissec36b31b2016-04-11 23:25:29 -0700312 }
Niels Möller71bdda02016-03-31 12:59:59 +0200313 void set_cpu_adaptation(bool enable) {
Niels Möller1d7ecd22018-01-18 15:25:12 +0100314 media_config.video.enable_cpu_adaptation = enable;
Niels Möller71bdda02016-03-31 12:59:59 +0200315 }
316
Niels Möller6539f692018-01-18 08:58:50 +0100317 bool suspend_below_min_bitrate() const {
nissec36b31b2016-04-11 23:25:29 -0700318 return media_config.video.suspend_below_min_bitrate;
319 }
Niels Möller71bdda02016-03-31 12:59:59 +0200320 void set_suspend_below_min_bitrate(bool enable) {
nissec36b31b2016-04-11 23:25:29 -0700321 media_config.video.suspend_below_min_bitrate = enable;
Niels Möller71bdda02016-03-31 12:59:59 +0200322 }
323
Niels Möller6539f692018-01-18 08:58:50 +0100324 bool prerenderer_smoothing() const {
Niels Möller1d7ecd22018-01-18 15:25:12 +0100325 return media_config.video.enable_prerenderer_smoothing;
nissec36b31b2016-04-11 23:25:29 -0700326 }
Niels Möller71bdda02016-03-31 12:59:59 +0200327 void set_prerenderer_smoothing(bool enable) {
Niels Möller1d7ecd22018-01-18 15:25:12 +0100328 media_config.video.enable_prerenderer_smoothing = enable;
Niels Möller71bdda02016-03-31 12:59:59 +0200329 }
330
Niels Möller6539f692018-01-18 08:58:50 +0100331 bool experiment_cpu_load_estimator() const {
332 return media_config.video.experiment_cpu_load_estimator;
333 }
334 void set_experiment_cpu_load_estimator(bool enable) {
335 media_config.video.experiment_cpu_load_estimator = enable;
336 }
Ilya Nikolaevskiy97b4ee52018-05-28 10:24:22 +0200337
Jiawei Ou55718122018-11-09 13:17:39 -0800338 int audio_rtcp_report_interval_ms() const {
339 return media_config.audio.rtcp_report_interval_ms;
340 }
341 void set_audio_rtcp_report_interval_ms(int audio_rtcp_report_interval_ms) {
342 media_config.audio.rtcp_report_interval_ms =
343 audio_rtcp_report_interval_ms;
344 }
345
346 int video_rtcp_report_interval_ms() const {
347 return media_config.video.rtcp_report_interval_ms;
348 }
349 void set_video_rtcp_report_interval_ms(int video_rtcp_report_interval_ms) {
350 media_config.video.rtcp_report_interval_ms =
351 video_rtcp_report_interval_ms;
352 }
353
honghaiz4edc39c2015-09-01 09:53:56 -0700354 static const int kUndefined = -1;
355 // Default maximum number of packets in the audio jitter buffer.
Jakob Ivarsson647d5e62019-03-15 10:37:31 +0100356 static const int kAudioJitterBufferMaxPackets = 200;
Honghai Zhangaecd9822016-09-02 16:58:17 -0700357 // ICE connection receiving timeout for aggressive configuration.
358 static const int kAggressiveIceConnectionReceivingTimeout = 1000;
deadbeefb10f32f2017-02-08 01:38:21 -0800359
360 ////////////////////////////////////////////////////////////////////////
361 // The below few fields mirror the standard RTCConfiguration dictionary:
Steve Antonab6ea6b2018-02-26 14:23:09 -0800362 // https://w3c.github.io/webrtc-pc/#rtcconfiguration-dictionary
deadbeefb10f32f2017-02-08 01:38:21 -0800363 ////////////////////////////////////////////////////////////////////////
364
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000365 // TODO(pthatcher): Rename this ice_servers, but update Chromium
366 // at the same time.
367 IceServers servers;
deadbeefb10f32f2017-02-08 01:38:21 -0800368 // TODO(pthatcher): Rename this ice_transport_type, but update
369 // Chromium at the same time.
370 IceTransportsType type = kAll;
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700371 BundlePolicy bundle_policy = kBundlePolicyBalanced;
zhihuang4dfb8ce2016-11-23 10:30:12 -0800372 RtcpMuxPolicy rtcp_mux_policy = kRtcpMuxPolicyRequire;
deadbeefb10f32f2017-02-08 01:38:21 -0800373 std::vector<rtc::scoped_refptr<rtc::RTCCertificate>> certificates;
374 int ice_candidate_pool_size = 0;
375
376 //////////////////////////////////////////////////////////////////////////
377 // The below fields correspond to constraints from the deprecated
378 // constraints interface for constructing a PeerConnection.
379 //
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200380 // absl::optional fields can be "missing", in which case the implementation
deadbeefb10f32f2017-02-08 01:38:21 -0800381 // default will be used.
382 //////////////////////////////////////////////////////////////////////////
383
384 // If set to true, don't gather IPv6 ICE candidates.
385 // TODO(deadbeef): Remove this? IPv6 support has long stopped being
386 // experimental
387 bool disable_ipv6 = false;
388
zhihuangb09b3f92017-03-07 14:40:51 -0800389 // If set to true, don't gather IPv6 ICE candidates on Wi-Fi.
390 // Only intended to be used on specific devices. Certain phones disable IPv6
391 // when the screen is turned off and it would be better to just disable the
392 // IPv6 ICE candidates on Wi-Fi in those cases.
393 bool disable_ipv6_on_wifi = false;
394
deadbeefd21eab32017-07-26 16:50:11 -0700395 // By default, the PeerConnection will use a limited number of IPv6 network
396 // interfaces, in order to avoid too many ICE candidate pairs being created
397 // and delaying ICE completion.
398 //
399 // Can be set to INT_MAX to effectively disable the limit.
400 int max_ipv6_networks = cricket::kDefaultMaxIPv6Networks;
401
Daniel Lazarenko2870b0a2018-01-25 10:30:22 +0100402 // Exclude link-local network interfaces
403 // from considertaion for gathering ICE candidates.
404 bool disable_link_local_networks = false;
405
deadbeefb10f32f2017-02-08 01:38:21 -0800406 // If set to true, use RTP data channels instead of SCTP.
407 // TODO(deadbeef): Remove this. We no longer commit to supporting RTP data
408 // channels, though some applications are still working on moving off of
409 // them.
410 bool enable_rtp_data_channel = false;
411
412 // Minimum bitrate at which screencast video tracks will be encoded at.
413 // This means adding padding bits up to this bitrate, which can help
414 // when switching from a static scene to one with motion.
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200415 absl::optional<int> screencast_min_bitrate;
deadbeefb10f32f2017-02-08 01:38:21 -0800416
417 // Use new combined audio/video bandwidth estimation?
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200418 absl::optional<bool> combined_audio_video_bwe;
deadbeefb10f32f2017-02-08 01:38:21 -0800419
Benjamin Wright8c27cca2018-10-25 10:16:44 -0700420 // TODO(bugs.webrtc.org/9891) - Move to crypto_options
deadbeefb10f32f2017-02-08 01:38:21 -0800421 // Can be used to disable DTLS-SRTP. This should never be done, but can be
422 // useful for testing purposes, for example in setting up a loopback call
423 // with a single PeerConnection.
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200424 absl::optional<bool> enable_dtls_srtp;
deadbeefb10f32f2017-02-08 01:38:21 -0800425
426 /////////////////////////////////////////////////
427 // The below fields are not part of the standard.
428 /////////////////////////////////////////////////
429
430 // Can be used to disable TCP candidate generation.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700431 TcpCandidatePolicy tcp_candidate_policy = kTcpCandidatePolicyEnabled;
deadbeefb10f32f2017-02-08 01:38:21 -0800432
433 // Can be used to avoid gathering candidates for a "higher cost" network,
434 // if a lower cost one exists. For example, if both Wi-Fi and cellular
435 // interfaces are available, this could be used to avoid using the cellular
436 // interface.
honghaiz60347052016-05-31 18:29:12 -0700437 CandidateNetworkPolicy candidate_network_policy =
438 kCandidateNetworkPolicyAll;
deadbeefb10f32f2017-02-08 01:38:21 -0800439
440 // The maximum number of packets that can be stored in the NetEq audio
441 // jitter buffer. Can be reduced to lower tolerated audio latency.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700442 int audio_jitter_buffer_max_packets = kAudioJitterBufferMaxPackets;
deadbeefb10f32f2017-02-08 01:38:21 -0800443
444 // Whether to use the NetEq "fast mode" which will accelerate audio quicker
445 // if it falls behind.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700446 bool audio_jitter_buffer_fast_accelerate = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800447
Jakob Ivarsson10403ae2018-11-27 15:45:20 +0100448 // The minimum delay in milliseconds for the audio jitter buffer.
449 int audio_jitter_buffer_min_delay_ms = 0;
450
Jakob Ivarsson53eae872019-01-10 15:58:36 +0100451 // Whether the audio jitter buffer adapts the delay to retransmitted
452 // packets.
453 bool audio_jitter_buffer_enable_rtx_handling = false;
454
deadbeefb10f32f2017-02-08 01:38:21 -0800455 // Timeout in milliseconds before an ICE candidate pair is considered to be
456 // "not receiving", after which a lower priority candidate pair may be
457 // selected.
458 int ice_connection_receiving_timeout = kUndefined;
459
460 // Interval in milliseconds at which an ICE "backup" candidate pair will be
461 // pinged. This is a candidate pair which is not actively in use, but may
462 // be switched to if the active candidate pair becomes unusable.
463 //
464 // This is relevant mainly to Wi-Fi/cell handoff; the application may not
465 // want this backup cellular candidate pair pinged frequently, since it
466 // consumes data/battery.
467 int ice_backup_candidate_pair_ping_interval = kUndefined;
468
469 // Can be used to enable continual gathering, which means new candidates
470 // will be gathered as network interfaces change. Note that if continual
471 // gathering is used, the candidate removal API should also be used, to
472 // avoid an ever-growing list of candidates.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700473 ContinualGatheringPolicy continual_gathering_policy = GATHER_ONCE;
deadbeefb10f32f2017-02-08 01:38:21 -0800474
475 // If set to true, candidate pairs will be pinged in order of most likely
476 // to work (which means using a TURN server, generally), rather than in
477 // standard priority order.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700478 bool prioritize_most_likely_ice_candidate_pairs = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800479
Niels Möller6daa2782018-01-23 10:37:42 +0100480 // Implementation defined settings. A public member only for the benefit of
481 // the implementation. Applications must not access it directly, and should
482 // instead use provided accessor methods, e.g., set_cpu_adaptation.
nissec36b31b2016-04-11 23:25:29 -0700483 struct cricket::MediaConfig media_config;
deadbeefb10f32f2017-02-08 01:38:21 -0800484
deadbeefb10f32f2017-02-08 01:38:21 -0800485 // If set to true, only one preferred TURN allocation will be used per
486 // network interface. UDP is preferred over TCP and IPv6 over IPv4. This
487 // can be used to cut down on the number of candidate pairings.
Honghai Zhangb9e7b4a2016-06-30 20:52:02 -0700488 bool prune_turn_ports = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800489
Taylor Brandstettere9851112016-07-01 11:11:13 -0700490 // If set to true, this means the ICE transport should presume TURN-to-TURN
491 // candidate pairs will succeed, even before a binding response is received.
deadbeefb10f32f2017-02-08 01:38:21 -0800492 // This can be used to optimize the initial connection time, since the DTLS
493 // handshake can begin immediately.
Taylor Brandstettere9851112016-07-01 11:11:13 -0700494 bool presume_writable_when_fully_relayed = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800495
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700496 // If true, "renomination" will be added to the ice options in the transport
497 // description.
deadbeefb10f32f2017-02-08 01:38:21 -0800498 // See: https://tools.ietf.org/html/draft-thatcher-ice-renomination-00
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700499 bool enable_ice_renomination = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800500
501 // If true, the ICE role is re-determined when the PeerConnection sets a
502 // local transport description that indicates an ICE restart.
503 //
504 // This is standard RFC5245 ICE behavior, but causes unnecessary role
505 // thrashing, so an application may wish to avoid it. This role
506 // re-determining was removed in ICEbis (ICE v2).
Honghai Zhangbfd398c2016-08-30 22:07:42 -0700507 bool redetermine_role_on_ice_restart = true;
deadbeefb10f32f2017-02-08 01:38:21 -0800508
Qingsi Wang1fe119f2019-05-31 16:55:33 -0700509 // This flag is only effective when |continual_gathering_policy| is
510 // GATHER_CONTINUALLY.
511 //
512 // If true, after the ICE transport type is changed such that new types of
513 // ICE candidates are allowed by the new transport type, e.g. from
514 // IceTransportsType::kRelay to IceTransportsType::kAll, candidates that
515 // have been gathered by the ICE transport but not matching the previous
516 // transport type and as a result not observed by PeerConnectionObserver,
517 // will be surfaced to the observer.
518 bool surface_ice_candidates_on_ice_transport_type_changed = false;
519
Qingsi Wange6826d22018-03-08 14:55:14 -0800520 // The following fields define intervals in milliseconds at which ICE
521 // connectivity checks are sent.
522 //
523 // We consider ICE is "strongly connected" for an agent when there is at
524 // least one candidate pair that currently succeeds in connectivity check
525 // from its direction i.e. sending a STUN ping and receives a STUN ping
526 // response, AND all candidate pairs have sent a minimum number of pings for
527 // connectivity (this number is implementation-specific). Otherwise, ICE is
528 // considered in "weak connectivity".
529 //
530 // Note that the above notion of strong and weak connectivity is not defined
531 // in RFC 5245, and they apply to our current ICE implementation only.
532 //
533 // 1) ice_check_interval_strong_connectivity defines the interval applied to
534 // ALL candidate pairs when ICE is strongly connected, and it overrides the
535 // default value of this interval in the ICE implementation;
536 // 2) ice_check_interval_weak_connectivity defines the counterpart for ALL
537 // pairs when ICE is weakly connected, and it overrides the default value of
538 // this interval in the ICE implementation;
539 // 3) ice_check_min_interval defines the minimal interval (equivalently the
540 // maximum rate) that overrides the above two intervals when either of them
541 // is less.
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200542 absl::optional<int> ice_check_interval_strong_connectivity;
543 absl::optional<int> ice_check_interval_weak_connectivity;
544 absl::optional<int> ice_check_min_interval;
deadbeefb10f32f2017-02-08 01:38:21 -0800545
Qingsi Wang22e623a2018-03-13 10:53:57 -0700546 // The min time period for which a candidate pair must wait for response to
547 // connectivity checks before it becomes unwritable. This parameter
548 // overrides the default value in the ICE implementation if set.
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200549 absl::optional<int> ice_unwritable_timeout;
Qingsi Wang22e623a2018-03-13 10:53:57 -0700550
551 // The min number of connectivity checks that a candidate pair must sent
552 // without receiving response before it becomes unwritable. This parameter
553 // overrides the default value in the ICE implementation if set.
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200554 absl::optional<int> ice_unwritable_min_checks;
Qingsi Wang22e623a2018-03-13 10:53:57 -0700555
Jiawei Ou9d4fd5552018-12-06 23:30:17 -0800556 // The min time period for which a candidate pair must wait for response to
557 // connectivity checks it becomes inactive. This parameter overrides the
558 // default value in the ICE implementation if set.
559 absl::optional<int> ice_inactive_timeout;
560
Qingsi Wangdb53f8e2018-02-20 14:45:49 -0800561 // The interval in milliseconds at which STUN candidates will resend STUN
562 // binding requests to keep NAT bindings open.
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200563 absl::optional<int> stun_candidate_keepalive_interval;
Qingsi Wangdb53f8e2018-02-20 14:45:49 -0800564
Steve Anton300bf8e2017-07-14 10:13:10 -0700565 // ICE Periodic Regathering
566 // If set, WebRTC will periodically create and propose candidates without
567 // starting a new ICE generation. The regathering happens continuously with
568 // interval specified in milliseconds by the uniform distribution [a, b].
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200569 absl::optional<rtc::IntervalRange> ice_regather_interval_range;
Steve Anton300bf8e2017-07-14 10:13:10 -0700570
Jonas Orelandbdcee282017-10-10 14:01:40 +0200571 // Optional TurnCustomizer.
572 // With this class one can modify outgoing TURN messages.
573 // The object passed in must remain valid until PeerConnection::Close() is
574 // called.
575 webrtc::TurnCustomizer* turn_customizer = nullptr;
576
Qingsi Wang9a5c6f82018-02-01 10:38:40 -0800577 // Preferred network interface.
578 // A candidate pair on a preferred network has a higher precedence in ICE
579 // than one on an un-preferred network, regardless of priority or network
580 // cost.
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200581 absl::optional<rtc::AdapterType> network_preference;
Qingsi Wang9a5c6f82018-02-01 10:38:40 -0800582
Steve Anton79e79602017-11-20 10:25:56 -0800583 // Configure the SDP semantics used by this PeerConnection. Note that the
584 // WebRTC 1.0 specification requires kUnifiedPlan semantics. The
585 // RtpTransceiver API is only available with kUnifiedPlan semantics.
586 //
587 // kPlanB will cause PeerConnection to create offers and answers with at
588 // most one audio and one video m= section with multiple RtpSenders and
589 // RtpReceivers specified as multiple a=ssrc lines within the section. This
Steve Antonab6ea6b2018-02-26 14:23:09 -0800590 // will also cause PeerConnection to ignore all but the first m= section of
591 // the same media type.
Steve Anton79e79602017-11-20 10:25:56 -0800592 //
593 // kUnifiedPlan will cause PeerConnection to create offers and answers with
594 // multiple m= sections where each m= section maps to one RtpSender and one
Steve Antonab6ea6b2018-02-26 14:23:09 -0800595 // RtpReceiver (an RtpTransceiver), either both audio or both video. This
596 // will also cause PeerConnection to ignore all but the first a=ssrc lines
597 // that form a Plan B stream.
Steve Anton79e79602017-11-20 10:25:56 -0800598 //
Steve Anton79e79602017-11-20 10:25:56 -0800599 // For users who wish to send multiple audio/video streams and need to stay
Steve Anton3acffc32018-04-12 17:21:03 -0700600 // interoperable with legacy WebRTC implementations or use legacy APIs,
601 // specify kPlanB.
Steve Anton79e79602017-11-20 10:25:56 -0800602 //
Steve Anton3acffc32018-04-12 17:21:03 -0700603 // For all other users, specify kUnifiedPlan.
604 SdpSemantics sdp_semantics = SdpSemantics::kPlanB;
Steve Anton79e79602017-11-20 10:25:56 -0800605
Benjamin Wright8c27cca2018-10-25 10:16:44 -0700606 // TODO(bugs.webrtc.org/9891) - Move to crypto_options or remove.
Zhi Huangb57e1692018-06-12 11:41:11 -0700607 // Actively reset the SRTP parameters whenever the DTLS transports
608 // underneath are reset for every offer/answer negotiation.
609 // This is only intended to be a workaround for crbug.com/835958
610 // WARNING: This would cause RTP/RTCP packets decryption failure if not used
611 // correctly. This flag will be deprecated soon. Do not rely on it.
612 bool active_reset_srtp_params = false;
613
Piotr (Peter) Slatalae0c2e972018-10-08 09:43:21 -0700614 // If MediaTransportFactory is provided in PeerConnectionFactory, this flag
Piotr (Peter) Slatala55b91b92019-01-25 13:31:15 -0800615 // informs PeerConnection that it should use the MediaTransportInterface for
616 // media (audio/video). It's invalid to set it to |true| if the
617 // MediaTransportFactory wasn't provided.
Piotr (Peter) Slatalae0c2e972018-10-08 09:43:21 -0700618 bool use_media_transport = false;
619
Bjorn Mellema9bbd862018-11-02 09:07:48 -0700620 // If MediaTransportFactory is provided in PeerConnectionFactory, this flag
621 // informs PeerConnection that it should use the MediaTransportInterface for
622 // data channels. It's invalid to set it to |true| if the
623 // MediaTransportFactory wasn't provided. Data channels over media
624 // transport are not compatible with RTP or SCTP data channels. Setting
625 // both |use_media_transport_for_data_channels| and
626 // |enable_rtp_data_channel| is invalid.
627 bool use_media_transport_for_data_channels = false;
628
Anton Sukhanov762076b2019-05-20 14:39:06 -0700629 // If MediaTransportFactory is provided in PeerConnectionFactory, this flag
630 // informs PeerConnection that it should use the DatagramTransportInterface
631 // for packets instead DTLS. It's invalid to set it to |true| if the
632 // MediaTransportFactory wasn't provided.
633 //
634 // TODO(sukhanov): Once we have a working mechanism for negotiating media
635 // transport through SDP, we replace media transport flags in
636 // RTCConfiguration with field trials.
637 bool use_datagram_transport = false;
638
Benjamin Wright8c27cca2018-10-25 10:16:44 -0700639 // Defines advanced optional cryptographic settings related to SRTP and
640 // frame encryption for native WebRTC. Setting this will overwrite any
641 // settings set in PeerConnectionFactory (which is deprecated).
642 absl::optional<CryptoOptions> crypto_options;
643
Johannes Kron89f874e2018-11-12 10:25:48 +0100644 // Configure if we should include the SDP attribute extmap-allow-mixed in
645 // our offer. Although we currently do support this, it's not included in
646 // our offer by default due to a previous bug that caused the SDP parser to
647 // abort parsing if this attribute was present. This is fixed in Chrome 71.
648 // TODO(webrtc:9985): Change default to true once sufficient time has
649 // passed.
650 bool offer_extmap_allow_mixed = false;
651
deadbeef293e9262017-01-11 12:28:30 -0800652 //
653 // Don't forget to update operator== if adding something.
654 //
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000655 };
656
deadbeefb10f32f2017-02-08 01:38:21 -0800657 // See: https://www.w3.org/TR/webrtc/#idl-def-rtcofferansweroptions
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000658 struct RTCOfferAnswerOptions {
659 static const int kUndefined = -1;
660 static const int kMaxOfferToReceiveMedia = 1;
661
662 // The default value for constraint offerToReceiveX:true.
663 static const int kOfferToReceiveMediaTrue = 1;
664
Steve Antonab6ea6b2018-02-26 14:23:09 -0800665 // These options are left as backwards compatibility for clients who need
666 // "Plan B" semantics. Clients who have switched to "Unified Plan" semantics
667 // should use the RtpTransceiver API (AddTransceiver) instead.
deadbeefb10f32f2017-02-08 01:38:21 -0800668 //
669 // offer_to_receive_X set to 1 will cause a media description to be
670 // generated in the offer, even if no tracks of that type have been added.
671 // Values greater than 1 are treated the same.
672 //
673 // If set to 0, the generated directional attribute will not include the
674 // "recv" direction (meaning it will be "sendonly" or "inactive".
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700675 int offer_to_receive_video = kUndefined;
676 int offer_to_receive_audio = kUndefined;
deadbeefb10f32f2017-02-08 01:38:21 -0800677
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700678 bool voice_activity_detection = true;
679 bool ice_restart = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800680
681 // If true, will offer to BUNDLE audio/video/data together. Not to be
682 // confused with RTCP mux (multiplexing RTP and RTCP together).
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700683 bool use_rtp_mux = true;
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000684
Mirta Dvornicic479a3c02019-06-04 15:38:50 +0200685 // If true, "a=packetization:<payload_type> raw" attribute will be offered
686 // in the SDP for all video payload and accepted in the answer if offered.
687 bool raw_packetization_for_video = false;
688
Jonas Orelandfc1acd22018-08-24 10:58:37 +0200689 // This will apply to all video tracks with a Plan B SDP offer/answer.
690 int num_simulcast_layers = 1;
691
Harald Alvestrand4aa11922019-05-14 22:00:01 +0200692 // If true: Use SDP format from draft-ietf-mmusic-scdp-sdp-03
693 // If false: Use SDP format from draft-ietf-mmusic-sdp-sdp-26 or later
694 bool use_obsolete_sctp_sdp = false;
695
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700696 RTCOfferAnswerOptions() = default;
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000697
698 RTCOfferAnswerOptions(int offer_to_receive_video,
699 int offer_to_receive_audio,
700 bool voice_activity_detection,
701 bool ice_restart,
702 bool use_rtp_mux)
703 : offer_to_receive_video(offer_to_receive_video),
704 offer_to_receive_audio(offer_to_receive_audio),
705 voice_activity_detection(voice_activity_detection),
706 ice_restart(ice_restart),
707 use_rtp_mux(use_rtp_mux) {}
708 };
709
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000710 // Used by GetStats to decide which stats to include in the stats reports.
711 // |kStatsOutputLevelStandard| includes the standard stats for Javascript API;
712 // |kStatsOutputLevelDebug| includes both the standard stats and additional
713 // stats for debugging purposes.
714 enum StatsOutputLevel {
715 kStatsOutputLevelStandard,
716 kStatsOutputLevelDebug,
717 };
718
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000719 // Accessor methods to active local streams.
Steve Antonab6ea6b2018-02-26 14:23:09 -0800720 // This method is not supported with kUnifiedPlan semantics. Please use
721 // GetSenders() instead.
Yves Gerey665174f2018-06-19 15:03:05 +0200722 virtual rtc::scoped_refptr<StreamCollectionInterface> local_streams() = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000723
724 // Accessor methods to remote streams.
Steve Antonab6ea6b2018-02-26 14:23:09 -0800725 // This method is not supported with kUnifiedPlan semantics. Please use
726 // GetReceivers() instead.
Yves Gerey665174f2018-06-19 15:03:05 +0200727 virtual rtc::scoped_refptr<StreamCollectionInterface> remote_streams() = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000728
729 // Add a new MediaStream to be sent on this PeerConnection.
730 // Note that a SessionDescription negotiation is needed before the
731 // remote peer can receive the stream.
deadbeefb10f32f2017-02-08 01:38:21 -0800732 //
733 // This has been removed from the standard in favor of a track-based API. So,
734 // this is equivalent to simply calling AddTrack for each track within the
735 // stream, with the one difference that if "stream->AddTrack(...)" is called
736 // later, the PeerConnection will automatically pick up the new track. Though
737 // this functionality will be deprecated in the future.
Steve Antonab6ea6b2018-02-26 14:23:09 -0800738 //
739 // This method is not supported with kUnifiedPlan semantics. Please use
740 // AddTrack instead.
perkj@webrtc.orgfd0efb62014-11-06 12:16:36 +0000741 virtual bool AddStream(MediaStreamInterface* stream) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000742
743 // Remove a MediaStream from this PeerConnection.
deadbeefb10f32f2017-02-08 01:38:21 -0800744 // Note that a SessionDescription negotiation is needed before the
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000745 // remote peer is notified.
Steve Antonab6ea6b2018-02-26 14:23:09 -0800746 //
747 // This method is not supported with kUnifiedPlan semantics. Please use
748 // RemoveTrack instead.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000749 virtual void RemoveStream(MediaStreamInterface* stream) = 0;
750
deadbeefb10f32f2017-02-08 01:38:21 -0800751 // Add a new MediaStreamTrack to be sent on this PeerConnection, and return
Steve Antonf9381f02017-12-14 10:23:57 -0800752 // the newly created RtpSender. The RtpSender will be associated with the
Seth Hampson845e8782018-03-02 11:34:10 -0800753 // streams specified in the |stream_ids| list.
deadbeefb10f32f2017-02-08 01:38:21 -0800754 //
Steve Antonf9381f02017-12-14 10:23:57 -0800755 // Errors:
756 // - INVALID_PARAMETER: |track| is null, has a kind other than audio or video,
757 // or a sender already exists for the track.
758 // - INVALID_STATE: The PeerConnection is closed.
Steve Anton2d6c76a2018-01-05 17:10:52 -0800759 virtual RTCErrorOr<rtc::scoped_refptr<RtpSenderInterface>> AddTrack(
760 rtc::scoped_refptr<MediaStreamTrackInterface> track,
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200761 const std::vector<std::string>& stream_ids);
deadbeefe1f9d832016-01-14 15:35:42 -0800762
763 // Remove an RtpSender from this PeerConnection.
764 // Returns true on success.
Steve Anton24db5732018-07-23 10:27:33 -0700765 // TODO(steveanton): Replace with signature that returns RTCError.
766 virtual bool RemoveTrack(RtpSenderInterface* sender);
767
768 // Plan B semantics: Removes the RtpSender from this PeerConnection.
769 // Unified Plan semantics: Stop sending on the RtpSender and mark the
770 // corresponding RtpTransceiver direction as no longer sending.
771 //
772 // Errors:
773 // - INVALID_PARAMETER: |sender| is null or (Plan B only) the sender is not
774 // associated with this PeerConnection.
775 // - INVALID_STATE: PeerConnection is closed.
776 // TODO(bugs.webrtc.org/9534): Rename to RemoveTrack once the other signature
777 // is removed.
778 virtual RTCError RemoveTrackNew(
779 rtc::scoped_refptr<RtpSenderInterface> sender);
deadbeefe1f9d832016-01-14 15:35:42 -0800780
Steve Anton9158ef62017-11-27 13:01:52 -0800781 // AddTransceiver creates a new RtpTransceiver and adds it to the set of
782 // transceivers. Adding a transceiver will cause future calls to CreateOffer
783 // to add a media description for the corresponding transceiver.
784 //
785 // The initial value of |mid| in the returned transceiver is null. Setting a
786 // new session description may change it to a non-null value.
787 //
788 // https://w3c.github.io/webrtc-pc/#dom-rtcpeerconnection-addtransceiver
789 //
790 // Optionally, an RtpTransceiverInit structure can be specified to configure
791 // the transceiver from construction. If not specified, the transceiver will
792 // default to having a direction of kSendRecv and not be part of any streams.
793 //
794 // These methods are only available when Unified Plan is enabled (see
795 // RTCConfiguration).
796 //
797 // Common errors:
798 // - INTERNAL_ERROR: The configuration does not have Unified Plan enabled.
799 // TODO(steveanton): Make these pure virtual once downstream projects have
800 // updated.
801
802 // Adds a transceiver with a sender set to transmit the given track. The kind
803 // of the transceiver (and sender/receiver) will be derived from the kind of
804 // the track.
805 // Errors:
806 // - INVALID_PARAMETER: |track| is null.
807 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>>
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200808 AddTransceiver(rtc::scoped_refptr<MediaStreamTrackInterface> track);
Steve Anton9158ef62017-11-27 13:01:52 -0800809 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>>
810 AddTransceiver(rtc::scoped_refptr<MediaStreamTrackInterface> track,
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200811 const RtpTransceiverInit& init);
Steve Anton9158ef62017-11-27 13:01:52 -0800812
813 // Adds a transceiver with the given kind. Can either be MEDIA_TYPE_AUDIO or
814 // MEDIA_TYPE_VIDEO.
815 // Errors:
816 // - INVALID_PARAMETER: |media_type| is not MEDIA_TYPE_AUDIO or
817 // MEDIA_TYPE_VIDEO.
818 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>>
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200819 AddTransceiver(cricket::MediaType media_type);
Steve Anton9158ef62017-11-27 13:01:52 -0800820 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>>
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200821 AddTransceiver(cricket::MediaType media_type, const RtpTransceiverInit& init);
Steve Anton9158ef62017-11-27 13:01:52 -0800822
deadbeef70ab1a12015-09-28 16:53:55 -0700823 // TODO(deadbeef): Make these pure virtual once all subclasses implement them.
deadbeefb10f32f2017-02-08 01:38:21 -0800824
825 // Creates a sender without a track. Can be used for "early media"/"warmup"
826 // use cases, where the application may want to negotiate video attributes
827 // before a track is available to send.
828 //
829 // The standard way to do this would be through "addTransceiver", but we
830 // don't support that API yet.
831 //
deadbeeffac06552015-11-25 11:26:01 -0800832 // |kind| must be "audio" or "video".
deadbeefb10f32f2017-02-08 01:38:21 -0800833 //
deadbeefbd7d8f72015-12-18 16:58:44 -0800834 // |stream_id| is used to populate the msid attribute; if empty, one will
835 // be generated automatically.
Steve Antonab6ea6b2018-02-26 14:23:09 -0800836 //
837 // This method is not supported with kUnifiedPlan semantics. Please use
838 // AddTransceiver instead.
deadbeeffac06552015-11-25 11:26:01 -0800839 virtual rtc::scoped_refptr<RtpSenderInterface> CreateSender(
deadbeefbd7d8f72015-12-18 16:58:44 -0800840 const std::string& kind,
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200841 const std::string& stream_id);
deadbeeffac06552015-11-25 11:26:01 -0800842
Steve Antonab6ea6b2018-02-26 14:23:09 -0800843 // If Plan B semantics are specified, gets all RtpSenders, created either
844 // through AddStream, AddTrack, or CreateSender. All senders of a specific
845 // media type share the same media description.
846 //
847 // If Unified Plan semantics are specified, gets the RtpSender for each
848 // RtpTransceiver.
deadbeef70ab1a12015-09-28 16:53:55 -0700849 virtual std::vector<rtc::scoped_refptr<RtpSenderInterface>> GetSenders()
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200850 const;
deadbeef70ab1a12015-09-28 16:53:55 -0700851
Steve Antonab6ea6b2018-02-26 14:23:09 -0800852 // If Plan B semantics are specified, gets all RtpReceivers created when a
853 // remote description is applied. All receivers of a specific media type share
854 // the same media description. It is also possible to have a media description
855 // with no associated RtpReceivers, if the directional attribute does not
856 // indicate that the remote peer is sending any media.
deadbeefb10f32f2017-02-08 01:38:21 -0800857 //
Steve Antonab6ea6b2018-02-26 14:23:09 -0800858 // If Unified Plan semantics are specified, gets the RtpReceiver for each
859 // RtpTransceiver.
deadbeef70ab1a12015-09-28 16:53:55 -0700860 virtual std::vector<rtc::scoped_refptr<RtpReceiverInterface>> GetReceivers()
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200861 const;
deadbeef70ab1a12015-09-28 16:53:55 -0700862
Steve Anton9158ef62017-11-27 13:01:52 -0800863 // Get all RtpTransceivers, created either through AddTransceiver, AddTrack or
864 // by a remote description applied with SetRemoteDescription.
Steve Antonab6ea6b2018-02-26 14:23:09 -0800865 //
Steve Anton9158ef62017-11-27 13:01:52 -0800866 // Note: This method is only available when Unified Plan is enabled (see
867 // RTCConfiguration).
868 virtual std::vector<rtc::scoped_refptr<RtpTransceiverInterface>>
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200869 GetTransceivers() const;
Steve Anton9158ef62017-11-27 13:01:52 -0800870
Henrik Boström1df1bf82018-03-20 13:24:20 +0100871 // The legacy non-compliant GetStats() API. This correspond to the
872 // callback-based version of getStats() in JavaScript. The returned metrics
873 // are UNDOCUMENTED and many of them rely on implementation-specific details.
874 // The goal is to DELETE THIS VERSION but we can't today because it is heavily
875 // relied upon by third parties. See https://crbug.com/822696.
876 //
877 // This version is wired up into Chrome. Any stats implemented are
878 // automatically exposed to the Web Platform. This has BYPASSED the Chrome
879 // release processes for years and lead to cross-browser incompatibility
880 // issues and web application reliance on Chrome-only behavior.
881 //
882 // This API is in "maintenance mode", serious regressions should be fixed but
883 // adding new stats is highly discouraged.
884 //
885 // TODO(hbos): Deprecate and remove this when third parties have migrated to
886 // the spec-compliant GetStats() API. https://crbug.com/822696
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000887 virtual bool GetStats(StatsObserver* observer,
Henrik Boström1df1bf82018-03-20 13:24:20 +0100888 MediaStreamTrackInterface* track, // Optional
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000889 StatsOutputLevel level) = 0;
Henrik Boström1df1bf82018-03-20 13:24:20 +0100890 // The spec-compliant GetStats() API. This correspond to the promise-based
891 // version of getStats() in JavaScript. Implementation status is described in
892 // api/stats/rtcstats_objects.h. For more details on stats, see spec:
893 // https://w3c.github.io/webrtc-pc/#dom-rtcpeerconnection-getstats
894 // TODO(hbos): Takes shared ownership, use rtc::scoped_refptr<> instead. This
895 // requires stop overriding the current version in third party or making third
896 // party calls explicit to avoid ambiguity during switch. Make the future
897 // version abstract as soon as third party projects implement it.
hbose3810152016-12-13 02:35:19 -0800898 virtual void GetStats(RTCStatsCollectorCallback* callback) {}
Henrik Boström1df1bf82018-03-20 13:24:20 +0100899 // Spec-compliant getStats() performing the stats selection algorithm with the
900 // sender. https://w3c.github.io/webrtc-pc/#dom-rtcrtpsender-getstats
901 // TODO(hbos): Make abstract as soon as third party projects implement it.
902 virtual void GetStats(
903 rtc::scoped_refptr<RtpSenderInterface> selector,
904 rtc::scoped_refptr<RTCStatsCollectorCallback> callback) {}
905 // Spec-compliant getStats() performing the stats selection algorithm with the
906 // receiver. https://w3c.github.io/webrtc-pc/#dom-rtcrtpreceiver-getstats
907 // TODO(hbos): Make abstract as soon as third party projects implement it.
908 virtual void GetStats(
909 rtc::scoped_refptr<RtpReceiverInterface> selector,
910 rtc::scoped_refptr<RTCStatsCollectorCallback> callback) {}
Steve Antonab6ea6b2018-02-26 14:23:09 -0800911 // Clear cached stats in the RTCStatsCollector.
Harald Alvestrand89061872018-01-02 14:08:34 +0100912 // Exposed for testing while waiting for automatic cache clear to work.
913 // https://bugs.webrtc.org/8693
914 virtual void ClearStatsCache() {}
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000915
deadbeefb10f32f2017-02-08 01:38:21 -0800916 // Create a data channel with the provided config, or default config if none
917 // is provided. Note that an offer/answer negotiation is still necessary
918 // before the data channel can be used.
919 //
920 // Also, calling CreateDataChannel is the only way to get a data "m=" section
921 // in SDP, so it should be done before CreateOffer is called, if the
922 // application plans to use data channels.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000923 virtual rtc::scoped_refptr<DataChannelInterface> CreateDataChannel(
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000924 const std::string& label,
925 const DataChannelInit* config) = 0;
926
deadbeefb10f32f2017-02-08 01:38:21 -0800927 // Returns the more recently applied description; "pending" if it exists, and
928 // otherwise "current". See below.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000929 virtual const SessionDescriptionInterface* local_description() const = 0;
930 virtual const SessionDescriptionInterface* remote_description() const = 0;
deadbeefb10f32f2017-02-08 01:38:21 -0800931
deadbeeffe4a8a42016-12-20 17:56:17 -0800932 // A "current" description the one currently negotiated from a complete
933 // offer/answer exchange.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200934 virtual const SessionDescriptionInterface* current_local_description() const;
935 virtual const SessionDescriptionInterface* current_remote_description() const;
deadbeefb10f32f2017-02-08 01:38:21 -0800936
deadbeeffe4a8a42016-12-20 17:56:17 -0800937 // A "pending" description is one that's part of an incomplete offer/answer
938 // exchange (thus, either an offer or a pranswer). Once the offer/answer
939 // exchange is finished, the "pending" description will become "current".
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200940 virtual const SessionDescriptionInterface* pending_local_description() const;
941 virtual const SessionDescriptionInterface* pending_remote_description() const;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000942
943 // Create a new offer.
944 // The CreateSessionDescriptionObserver callback will be called when done.
945 virtual void CreateOffer(CreateSessionDescriptionObserver* observer,
Niels Möllerf06f9232018-08-07 12:32:18 +0200946 const RTCOfferAnswerOptions& options) = 0;
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000947
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000948 // Create an answer to an offer.
949 // The CreateSessionDescriptionObserver callback will be called when done.
950 virtual void CreateAnswer(CreateSessionDescriptionObserver* observer,
Niels Möllerf06f9232018-08-07 12:32:18 +0200951 const RTCOfferAnswerOptions& options) = 0;
htaa2a49d92016-03-04 02:51:39 -0800952
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000953 // Sets the local session description.
deadbeef1dcb1642017-03-29 21:08:16 -0700954 // The PeerConnection takes the ownership of |desc| even if it fails.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000955 // The |observer| callback will be called when done.
deadbeef1dcb1642017-03-29 21:08:16 -0700956 // TODO(deadbeef): Change |desc| to be a unique_ptr, to make it clear
957 // that this method always takes ownership of it.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000958 virtual void SetLocalDescription(SetSessionDescriptionObserver* observer,
959 SessionDescriptionInterface* desc) = 0;
960 // Sets the remote session description.
deadbeef1dcb1642017-03-29 21:08:16 -0700961 // The PeerConnection takes the ownership of |desc| even if it fails.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000962 // The |observer| callback will be called when done.
Henrik Boström31638672017-11-23 17:48:32 +0100963 // TODO(hbos): Remove when Chrome implements the new signature.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000964 virtual void SetRemoteDescription(SetSessionDescriptionObserver* observer,
Henrik Boström07109652017-11-27 09:52:02 +0100965 SessionDescriptionInterface* desc) {}
Henrik Boström31638672017-11-23 17:48:32 +0100966 // TODO(hbos): Make pure virtual when Chrome has updated its signature.
967 virtual void SetRemoteDescription(
968 std::unique_ptr<SessionDescriptionInterface> desc,
969 rtc::scoped_refptr<SetRemoteDescriptionObserverInterface> observer) {}
deadbeefb10f32f2017-02-08 01:38:21 -0800970
deadbeef46c73892016-11-16 19:42:04 -0800971 // TODO(deadbeef): Make this pure virtual once all Chrome subclasses of
972 // PeerConnectionInterface implement it.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200973 virtual PeerConnectionInterface::RTCConfiguration GetConfiguration();
deadbeef293e9262017-01-11 12:28:30 -0800974
deadbeefa67696b2015-09-29 11:56:26 -0700975 // Sets the PeerConnection's global configuration to |config|.
deadbeef293e9262017-01-11 12:28:30 -0800976 //
977 // The members of |config| that may be changed are |type|, |servers|,
978 // |ice_candidate_pool_size| and |prune_turn_ports| (though the candidate
979 // pool size can't be changed after the first call to SetLocalDescription).
980 // Note that this means the BUNDLE and RTCP-multiplexing policies cannot be
981 // changed with this method.
982 //
deadbeefa67696b2015-09-29 11:56:26 -0700983 // Any changes to STUN/TURN servers or ICE candidate policy will affect the
984 // next gathering phase, and cause the next call to createOffer to generate
deadbeef293e9262017-01-11 12:28:30 -0800985 // new ICE credentials, as described in JSEP. This also occurs when
986 // |prune_turn_ports| changes, for the same reasoning.
987 //
988 // If an error occurs, returns false and populates |error| if non-null:
989 // - INVALID_MODIFICATION if |config| contains a modified parameter other
990 // than one of the parameters listed above.
991 // - INVALID_RANGE if |ice_candidate_pool_size| is out of range.
992 // - SYNTAX_ERROR if parsing an ICE server URL failed.
993 // - INVALID_PARAMETER if a TURN server is missing |username| or |password|.
994 // - INTERNAL_ERROR if an unexpected error occurred.
995 //
deadbeefa67696b2015-09-29 11:56:26 -0700996 // TODO(deadbeef): Make this pure virtual once all Chrome subclasses of
997 // PeerConnectionInterface implement it.
998 virtual bool SetConfiguration(
deadbeef293e9262017-01-11 12:28:30 -0800999 const PeerConnectionInterface::RTCConfiguration& config,
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001000 RTCError* error);
1001
deadbeef293e9262017-01-11 12:28:30 -08001002 // Version without error output param for backwards compatibility.
1003 // TODO(deadbeef): Remove once chromium is updated.
1004 virtual bool SetConfiguration(
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001005 const PeerConnectionInterface::RTCConfiguration& config);
deadbeefb10f32f2017-02-08 01:38:21 -08001006
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001007 // Provides a remote candidate to the ICE Agent.
1008 // A copy of the |candidate| will be created and added to the remote
1009 // description. So the caller of this method still has the ownership of the
1010 // |candidate|.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001011 virtual bool AddIceCandidate(const IceCandidateInterface* candidate) = 0;
1012
deadbeefb10f32f2017-02-08 01:38:21 -08001013 // Removes a group of remote candidates from the ICE agent. Needed mainly for
1014 // continual gathering, to avoid an ever-growing list of candidates as
1015 // networks come and go.
Honghai Zhang7fb69db2016-03-14 11:59:18 -07001016 virtual bool RemoveIceCandidates(
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001017 const std::vector<cricket::Candidate>& candidates);
Honghai Zhang7fb69db2016-03-14 11:59:18 -07001018
zstein4b979802017-06-02 14:37:37 -07001019 // 0 <= min <= current <= max should hold for set parameters.
1020 struct BitrateParameters {
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001021 BitrateParameters();
1022 ~BitrateParameters();
1023
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +02001024 absl::optional<int> min_bitrate_bps;
1025 absl::optional<int> current_bitrate_bps;
1026 absl::optional<int> max_bitrate_bps;
zstein4b979802017-06-02 14:37:37 -07001027 };
1028
1029 // SetBitrate limits the bandwidth allocated for all RTP streams sent by
1030 // this PeerConnection. Other limitations might affect these limits and
1031 // are respected (for example "b=AS" in SDP).
1032 //
1033 // Setting |current_bitrate_bps| will reset the current bitrate estimate
1034 // to the provided value.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001035 virtual RTCError SetBitrate(const BitrateSettings& bitrate);
Niels Möller0c4f7be2018-05-07 14:01:37 +02001036
1037 // TODO(nisse): Deprecated - use version above. These two default
1038 // implementations require subclasses to implement one or the other
1039 // of the methods.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001040 virtual RTCError SetBitrate(const BitrateParameters& bitrate_parameters);
zstein4b979802017-06-02 14:37:37 -07001041
Alex Narest78609d52017-10-20 10:37:47 +02001042 // Sets current strategy. If not set default WebRTC allocator will be used.
1043 // May be changed during an active session. The strategy
1044 // ownership is passed with std::unique_ptr
1045 // TODO(alexnarest): Make this pure virtual when tests will be updated
1046 virtual void SetBitrateAllocationStrategy(
1047 std::unique_ptr<rtc::BitrateAllocationStrategy>
1048 bitrate_allocation_strategy) {}
1049
henrika5f6bf242017-11-01 11:06:56 +01001050 // Enable/disable playout of received audio streams. Enabled by default. Note
1051 // that even if playout is enabled, streams will only be played out if the
1052 // appropriate SDP is also applied. Setting |playout| to false will stop
1053 // playout of the underlying audio device but starts a task which will poll
1054 // for audio data every 10ms to ensure that audio processing happens and the
1055 // audio statistics are updated.
1056 // TODO(henrika): deprecate and remove this.
1057 virtual void SetAudioPlayout(bool playout) {}
1058
1059 // Enable/disable recording of transmitted audio streams. Enabled by default.
1060 // Note that even if recording is enabled, streams will only be recorded if
1061 // the appropriate SDP is also applied.
1062 // TODO(henrika): deprecate and remove this.
1063 virtual void SetAudioRecording(bool recording) {}
1064
Harald Alvestrandad88c882018-11-28 16:47:46 +01001065 // Looks up the DtlsTransport associated with a MID value.
1066 // In the Javascript API, DtlsTransport is a property of a sender, but
1067 // because the PeerConnection owns the DtlsTransport in this implementation,
1068 // it is better to look them up on the PeerConnection.
Harald Alvestrand41390472018-12-03 18:45:19 +01001069 // TODO(hta): Remove default implementation after updating Chrome.
Harald Alvestrandad88c882018-11-28 16:47:46 +01001070 virtual rtc::scoped_refptr<DtlsTransportInterface> LookupDtlsTransportByMid(
1071 const std::string& mid);
Harald Alvestrandad88c882018-11-28 16:47:46 +01001072
Harald Alvestrandc85328f2019-02-28 07:51:00 +01001073 // Returns the SCTP transport, if any.
1074 // TODO(hta): Remove default implementation after updating Chrome.
1075 virtual rtc::scoped_refptr<SctpTransportInterface> GetSctpTransport() const;
1076
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001077 // Returns the current SignalingState.
1078 virtual SignalingState signaling_state() = 0;
Taylor Brandstettercb423c42017-10-22 11:52:32 -07001079
Jonas Olsson12046902018-12-06 11:25:14 +01001080 // Returns an aggregate state of all ICE *and* DTLS transports.
1081 // This is left in place to avoid breaking native clients who expect our old,
1082 // nonstandard behavior.
1083 // TODO(jonasolsson): deprecate and remove this.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001084 virtual IceConnectionState ice_connection_state() = 0;
Taylor Brandstettercb423c42017-10-22 11:52:32 -07001085
Jonas Olsson12046902018-12-06 11:25:14 +01001086 // Returns an aggregated state of all ICE transports.
1087 virtual IceConnectionState standardized_ice_connection_state();
1088
1089 // Returns an aggregated state of all ICE and DTLS transports.
Jonas Olsson635474e2018-10-18 15:58:17 +02001090 virtual PeerConnectionState peer_connection_state();
1091
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001092 virtual IceGatheringState ice_gathering_state() = 0;
1093
Elad Alon99c3fe52017-10-13 16:29:40 +02001094 // Start RtcEventLog using an existing output-sink. Takes ownership of
1095 // |output| and passes it on to Call, which will take the ownership. If the
Bjorn Tereliusde939432017-11-20 17:38:14 +01001096 // operation fails the output will be closed and deallocated. The event log
1097 // will send serialized events to the output object every |output_period_ms|.
Niels Möllerf00ca1a2019-05-10 11:33:12 +02001098 // Applications using the event log should generally make their own trade-off
1099 // regarding the output period. A long period is generally more efficient,
1100 // with potential drawbacks being more bursty thread usage, and more events
1101 // lost in case the application crashes. If the |output_period_ms| argument is
1102 // omitted, webrtc selects a default deemed to be workable in most cases.
Bjorn Tereliusde939432017-11-20 17:38:14 +01001103 virtual bool StartRtcEventLog(std::unique_ptr<RtcEventLogOutput> output,
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001104 int64_t output_period_ms);
Niels Möllerf00ca1a2019-05-10 11:33:12 +02001105 virtual bool StartRtcEventLog(std::unique_ptr<RtcEventLogOutput> output);
Elad Alon99c3fe52017-10-13 16:29:40 +02001106
ivoc14d5dbe2016-07-04 07:06:55 -07001107 // Stops logging the RtcEventLog.
1108 // TODO(ivoc): Make this pure virtual when Chrome is updated.
1109 virtual void StopRtcEventLog() {}
1110
deadbeefb10f32f2017-02-08 01:38:21 -08001111 // Terminates all media, closes the transports, and in general releases any
1112 // resources used by the PeerConnection. This is an irreversible operation.
deadbeefd07061c2017-04-20 13:19:00 -07001113 //
1114 // Note that after this method completes, the PeerConnection will no longer
1115 // use the PeerConnectionObserver interface passed in on construction, and
1116 // thus the observer object can be safely destroyed.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001117 virtual void Close() = 0;
1118
1119 protected:
1120 // Dtor protected as objects shouldn't be deleted via this interface.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001121 ~PeerConnectionInterface() override = default;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001122};
1123
deadbeefb10f32f2017-02-08 01:38:21 -08001124// PeerConnection callback interface, used for RTCPeerConnection events.
1125// Application should implement these methods.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001126class PeerConnectionObserver {
1127 public:
Sami Kalliomäki02879f92018-01-11 10:02:19 +01001128 virtual ~PeerConnectionObserver() = default;
1129
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001130 // Triggered when the SignalingState changed.
1131 virtual void OnSignalingChange(
perkjdfb769d2016-02-09 03:09:43 -08001132 PeerConnectionInterface::SignalingState new_state) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001133
1134 // Triggered when media is received on a new stream from remote peer.
Steve Anton772eb212018-01-16 10:11:06 -08001135 virtual void OnAddStream(rtc::scoped_refptr<MediaStreamInterface> stream) {}
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001136
Steve Anton3172c032018-05-03 15:30:18 -07001137 // Triggered when a remote peer closes a stream.
Steve Anton772eb212018-01-16 10:11:06 -08001138 virtual void OnRemoveStream(rtc::scoped_refptr<MediaStreamInterface> stream) {
1139 }
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001140
Taylor Brandstetter98cde262016-05-31 13:02:21 -07001141 // Triggered when a remote peer opens a data channel.
1142 virtual void OnDataChannel(
nisse7f067662017-03-08 06:59:45 -08001143 rtc::scoped_refptr<DataChannelInterface> data_channel) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001144
Taylor Brandstetter98cde262016-05-31 13:02:21 -07001145 // Triggered when renegotiation is needed. For example, an ICE restart
1146 // has begun.
fischman@webrtc.orgd7568a02014-01-13 22:04:12 +00001147 virtual void OnRenegotiationNeeded() = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001148
Jonas Olsson12046902018-12-06 11:25:14 +01001149 // Called any time the legacy IceConnectionState changes.
deadbeefb10f32f2017-02-08 01:38:21 -08001150 //
1151 // Note that our ICE states lag behind the standard slightly. The most
1152 // notable differences include the fact that "failed" occurs after 15
1153 // seconds, not 30, and this actually represents a combination ICE + DTLS
1154 // state, so it may be "failed" if DTLS fails while ICE succeeds.
Jonas Olsson12046902018-12-06 11:25:14 +01001155 //
1156 // TODO(jonasolsson): deprecate and remove this.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001157 virtual void OnIceConnectionChange(
perkjdfb769d2016-02-09 03:09:43 -08001158 PeerConnectionInterface::IceConnectionState new_state) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001159
Jonas Olsson12046902018-12-06 11:25:14 +01001160 // Called any time the standards-compliant IceConnectionState changes.
1161 virtual void OnStandardizedIceConnectionChange(
1162 PeerConnectionInterface::IceConnectionState new_state) {}
1163
Jonas Olsson635474e2018-10-18 15:58:17 +02001164 // Called any time the PeerConnectionState changes.
1165 virtual void OnConnectionChange(
1166 PeerConnectionInterface::PeerConnectionState new_state) {}
1167
Taylor Brandstetter98cde262016-05-31 13:02:21 -07001168 // Called any time the IceGatheringState changes.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001169 virtual void OnIceGatheringChange(
perkjdfb769d2016-02-09 03:09:43 -08001170 PeerConnectionInterface::IceGatheringState new_state) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001171
Taylor Brandstetter98cde262016-05-31 13:02:21 -07001172 // A new ICE candidate has been gathered.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001173 virtual void OnIceCandidate(const IceCandidateInterface* candidate) = 0;
1174
Eldar Relloda13ea22019-06-01 12:23:43 +03001175 // Gathering of an ICE candidate failed.
1176 // See https://w3c.github.io/webrtc-pc/#event-icecandidateerror
1177 // |host_candidate| is a stringified socket address.
1178 virtual void OnIceCandidateError(const std::string& host_candidate,
1179 const std::string& url,
1180 int error_code,
1181 const std::string& error_text) {}
1182
Honghai Zhang7fb69db2016-03-14 11:59:18 -07001183 // Ice candidates have been removed.
1184 // TODO(honghaiz): Make this a pure virtual method when all its subclasses
1185 // implement it.
1186 virtual void OnIceCandidatesRemoved(
1187 const std::vector<cricket::Candidate>& candidates) {}
1188
Peter Thatcher54360512015-07-08 11:08:35 -07001189 // Called when the ICE connection receiving status changes.
1190 virtual void OnIceConnectionReceivingChange(bool receiving) {}
1191
Steve Antonab6ea6b2018-02-26 14:23:09 -08001192 // This is called when a receiver and its track are created.
Henrik Boström933d8b02017-10-10 10:05:16 -07001193 // TODO(zhihuang): Make this pure virtual when all subclasses implement it.
Steve Anton8b815cd2018-02-16 16:14:42 -08001194 // Note: This is called with both Plan B and Unified Plan semantics. Unified
1195 // Plan users should prefer OnTrack, OnAddTrack is only called as backwards
1196 // compatibility (and is called in the exact same situations as OnTrack).
zhihuang81c3a032016-11-17 12:06:24 -08001197 virtual void OnAddTrack(
1198 rtc::scoped_refptr<RtpReceiverInterface> receiver,
zhihuangc63b8942016-12-02 15:41:10 -08001199 const std::vector<rtc::scoped_refptr<MediaStreamInterface>>& streams) {}
zhihuang81c3a032016-11-17 12:06:24 -08001200
Steve Anton8b815cd2018-02-16 16:14:42 -08001201 // This is called when signaling indicates a transceiver will be receiving
1202 // media from the remote endpoint. This is fired during a call to
1203 // SetRemoteDescription. The receiving track can be accessed by:
1204 // |transceiver->receiver()->track()| and its associated streams by
1205 // |transceiver->receiver()->streams()|.
1206 // Note: This will only be called if Unified Plan semantics are specified.
1207 // This behavior is specified in section 2.2.8.2.5 of the "Set the
1208 // RTCSessionDescription" algorithm:
1209 // https://w3c.github.io/webrtc-pc/#set-description
1210 virtual void OnTrack(
1211 rtc::scoped_refptr<RtpTransceiverInterface> transceiver) {}
1212
Steve Anton3172c032018-05-03 15:30:18 -07001213 // Called when signaling indicates that media will no longer be received on a
1214 // track.
1215 // With Plan B semantics, the given receiver will have been removed from the
1216 // PeerConnection and the track muted.
1217 // With Unified Plan semantics, the receiver will remain but the transceiver
1218 // will have changed direction to either sendonly or inactive.
Henrik Boström933d8b02017-10-10 10:05:16 -07001219 // https://w3c.github.io/webrtc-pc/#process-remote-track-removal
Henrik Boström933d8b02017-10-10 10:05:16 -07001220 // TODO(hbos,deadbeef): Make pure virtual when all subclasses implement it.
1221 virtual void OnRemoveTrack(
1222 rtc::scoped_refptr<RtpReceiverInterface> receiver) {}
Harald Alvestrandc0e97252018-07-26 10:39:55 +02001223
1224 // Called when an interesting usage is detected by WebRTC.
1225 // An appropriate action is to add information about the context of the
1226 // PeerConnection and write the event to some kind of "interesting events"
1227 // log function.
1228 // The heuristics for defining what constitutes "interesting" are
1229 // implementation-defined.
1230 virtual void OnInterestingUsage(int usage_pattern) {}
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001231};
1232
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001233// PeerConnectionDependencies holds all of PeerConnections dependencies.
1234// A dependency is distinct from a configuration as it defines significant
1235// executable code that can be provided by a user of the API.
1236//
1237// All new dependencies should be added as a unique_ptr to allow the
1238// PeerConnection object to be the definitive owner of the dependencies
1239// lifetime making injection safer.
1240struct PeerConnectionDependencies final {
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001241 explicit PeerConnectionDependencies(PeerConnectionObserver* observer_in);
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001242 // This object is not copyable or assignable.
1243 PeerConnectionDependencies(const PeerConnectionDependencies&) = delete;
1244 PeerConnectionDependencies& operator=(const PeerConnectionDependencies&) =
1245 delete;
1246 // This object is only moveable.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001247 PeerConnectionDependencies(PeerConnectionDependencies&&);
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001248 PeerConnectionDependencies& operator=(PeerConnectionDependencies&&) = default;
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001249 ~PeerConnectionDependencies();
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001250 // Mandatory dependencies
1251 PeerConnectionObserver* observer = nullptr;
1252 // Optional dependencies
1253 std::unique_ptr<cricket::PortAllocator> allocator;
Zach Steine20867f2018-08-02 13:20:15 -07001254 std::unique_ptr<webrtc::AsyncResolverFactory> async_resolver_factory;
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001255 std::unique_ptr<rtc::RTCCertificateGeneratorInterface> cert_generator;
Benjamin Wrightd6f86e82018-05-08 13:12:25 -07001256 std::unique_ptr<rtc::SSLCertificateVerifier> tls_cert_verifier;
Jonas Orelanda3aa9bd2019-04-17 07:38:40 +02001257 std::unique_ptr<webrtc::VideoBitrateAllocatorFactory>
1258 video_bitrate_allocator_factory;
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001259};
1260
Benjamin Wright5234a492018-05-29 15:04:32 -07001261// PeerConnectionFactoryDependencies holds all of the PeerConnectionFactory
1262// dependencies. All new dependencies should be added here instead of
1263// overloading the function. This simplifies dependency injection and makes it
1264// clear which are mandatory and optional. If possible please allow the peer
1265// connection factory to take ownership of the dependency by adding a unique_ptr
1266// to this structure.
1267struct PeerConnectionFactoryDependencies final {
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001268 PeerConnectionFactoryDependencies();
Benjamin Wright5234a492018-05-29 15:04:32 -07001269 // This object is not copyable or assignable.
1270 PeerConnectionFactoryDependencies(const PeerConnectionFactoryDependencies&) =
1271 delete;
1272 PeerConnectionFactoryDependencies& operator=(
1273 const PeerConnectionFactoryDependencies&) = delete;
1274 // This object is only moveable.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001275 PeerConnectionFactoryDependencies(PeerConnectionFactoryDependencies&&);
Benjamin Wright5234a492018-05-29 15:04:32 -07001276 PeerConnectionFactoryDependencies& operator=(
1277 PeerConnectionFactoryDependencies&&) = default;
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001278 ~PeerConnectionFactoryDependencies();
Benjamin Wright5234a492018-05-29 15:04:32 -07001279
1280 // Optional dependencies
1281 rtc::Thread* network_thread = nullptr;
1282 rtc::Thread* worker_thread = nullptr;
1283 rtc::Thread* signaling_thread = nullptr;
Danil Chapovalov9435c612019-04-01 10:33:16 +02001284 std::unique_ptr<TaskQueueFactory> task_queue_factory;
Benjamin Wright5234a492018-05-29 15:04:32 -07001285 std::unique_ptr<cricket::MediaEngineInterface> media_engine;
1286 std::unique_ptr<CallFactoryInterface> call_factory;
1287 std::unique_ptr<RtcEventLogFactoryInterface> event_log_factory;
1288 std::unique_ptr<FecControllerFactoryInterface> fec_controller_factory;
Ying Wang0810a7c2019-04-10 13:48:24 +02001289 std::unique_ptr<NetworkStatePredictorFactoryInterface>
1290 network_state_predictor_factory;
Benjamin Wright5234a492018-05-29 15:04:32 -07001291 std::unique_ptr<NetworkControllerFactoryInterface> network_controller_factory;
Piotr (Peter) Slatalae0c2e972018-10-08 09:43:21 -07001292 std::unique_ptr<MediaTransportFactory> media_transport_factory;
Benjamin Wright5234a492018-05-29 15:04:32 -07001293};
1294
deadbeefb10f32f2017-02-08 01:38:21 -08001295// PeerConnectionFactoryInterface is the factory interface used for creating
1296// PeerConnection, MediaStream and MediaStreamTrack objects.
1297//
1298// The simplest method for obtaiing one, CreatePeerConnectionFactory will
1299// create the required libjingle threads, socket and network manager factory
1300// classes for networking if none are provided, though it requires that the
1301// application runs a message loop on the thread that called the method (see
1302// explanation below)
1303//
1304// If an application decides to provide its own threads and/or implementation
1305// of networking classes, it should use the alternate
1306// CreatePeerConnectionFactory method which accepts threads as input, and use
1307// the CreatePeerConnection version that takes a PortAllocator as an argument.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +00001308class PeerConnectionFactoryInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001309 public:
wu@webrtc.org97077a32013-10-25 21:18:33 +00001310 class Options {
1311 public:
Benjamin Wrighta54daf12018-10-11 15:33:17 -07001312 Options() {}
deadbeefb10f32f2017-02-08 01:38:21 -08001313
1314 // If set to true, created PeerConnections won't enforce any SRTP
1315 // requirement, allowing unsecured media. Should only be used for
1316 // testing/debugging.
1317 bool disable_encryption = false;
1318
1319 // Deprecated. The only effect of setting this to true is that
1320 // CreateDataChannel will fail, which is not that useful.
1321 bool disable_sctp_data_channels = false;
1322
1323 // If set to true, any platform-supported network monitoring capability
1324 // won't be used, and instead networks will only be updated via polling.
1325 //
1326 // This only has an effect if a PeerConnection is created with the default
1327 // PortAllocator implementation.
1328 bool disable_network_monitor = false;
phoglund@webrtc.org006521d2015-02-12 09:23:59 +00001329
1330 // Sets the network types to ignore. For instance, calling this with
1331 // ADAPTER_TYPE_ETHERNET | ADAPTER_TYPE_LOOPBACK will ignore Ethernet and
1332 // loopback interfaces.
deadbeefb10f32f2017-02-08 01:38:21 -08001333 int network_ignore_mask = rtc::kDefaultNetworkIgnoreMask;
Joachim Bauch04e5b492015-05-29 09:40:39 +02001334
1335 // Sets the maximum supported protocol version. The highest version
1336 // supported by both ends will be used for the connection, i.e. if one
1337 // party supports DTLS 1.0 and the other DTLS 1.2, DTLS 1.0 will be used.
deadbeefb10f32f2017-02-08 01:38:21 -08001338 rtc::SSLProtocolVersion ssl_max_version = rtc::SSL_PROTOCOL_DTLS_12;
jbauchcb560652016-08-04 05:20:32 -07001339
1340 // Sets crypto related options, e.g. enabled cipher suites.
Benjamin Wrighta54daf12018-10-11 15:33:17 -07001341 CryptoOptions crypto_options = CryptoOptions::NoGcm();
wu@webrtc.org97077a32013-10-25 21:18:33 +00001342 };
1343
deadbeef7914b8c2017-04-21 03:23:33 -07001344 // Set the options to be used for subsequently created PeerConnections.
wu@webrtc.org97077a32013-10-25 21:18:33 +00001345 virtual void SetOptions(const Options& options) = 0;
buildbot@webrtc.org41451d42014-05-03 05:39:45 +00001346
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001347 // The preferred way to create a new peer connection. Simply provide the
1348 // configuration and a PeerConnectionDependencies structure.
1349 // TODO(benwright): Make pure virtual once downstream mock PC factory classes
1350 // are updated.
1351 virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection(
1352 const PeerConnectionInterface::RTCConfiguration& configuration,
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001353 PeerConnectionDependencies dependencies);
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001354
1355 // Deprecated; |allocator| and |cert_generator| may be null, in which case
1356 // default implementations will be used.
deadbeefd07061c2017-04-20 13:19:00 -07001357 //
1358 // |observer| must not be null.
1359 //
1360 // Note that this method does not take ownership of |observer|; it's the
1361 // responsibility of the caller to delete it. It can be safely deleted after
1362 // Close has been called on the returned PeerConnection, which ensures no
1363 // more observer callbacks will be invoked.
deadbeef41b07982015-12-01 15:01:24 -08001364 virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection(
1365 const PeerConnectionInterface::RTCConfiguration& configuration,
kwibergd1fe2812016-04-27 06:47:29 -07001366 std::unique_ptr<cricket::PortAllocator> allocator,
Henrik Boströmd03c23b2016-06-01 11:44:18 +02001367 std::unique_ptr<rtc::RTCCertificateGeneratorInterface> cert_generator,
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001368 PeerConnectionObserver* observer);
1369
Florent Castelli72b751a2018-06-28 14:09:33 +02001370 // Returns the capabilities of an RTP sender of type |kind|.
1371 // If for some reason you pass in MEDIA_TYPE_DATA, returns an empty structure.
1372 // TODO(orphis): Make pure virtual when all subclasses implement it.
1373 virtual RtpCapabilities GetRtpSenderCapabilities(
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001374 cricket::MediaType kind) const;
Florent Castelli72b751a2018-06-28 14:09:33 +02001375
1376 // Returns the capabilities of an RTP receiver of type |kind|.
1377 // If for some reason you pass in MEDIA_TYPE_DATA, returns an empty structure.
1378 // TODO(orphis): Make pure virtual when all subclasses implement it.
1379 virtual RtpCapabilities GetRtpReceiverCapabilities(
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001380 cricket::MediaType kind) const;
Florent Castelli72b751a2018-06-28 14:09:33 +02001381
Seth Hampson845e8782018-03-02 11:34:10 -08001382 virtual rtc::scoped_refptr<MediaStreamInterface> CreateLocalMediaStream(
1383 const std::string& stream_id) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001384
deadbeefe814a0d2017-02-25 18:15:09 -08001385 // Creates an AudioSourceInterface.
deadbeefb10f32f2017-02-08 01:38:21 -08001386 // |options| decides audio processing settings.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +00001387 virtual rtc::scoped_refptr<AudioSourceInterface> CreateAudioSource(
htaa2a49d92016-03-04 02:51:39 -08001388 const cricket::AudioOptions& options) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001389
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001390 // Creates a new local VideoTrack. The same |source| can be used in several
1391 // tracks.
perkja3ede6c2016-03-08 01:27:48 +01001392 virtual rtc::scoped_refptr<VideoTrackInterface> CreateVideoTrack(
1393 const std::string& label,
1394 VideoTrackSourceInterface* source) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001395
deadbeef8d60a942017-02-27 14:47:33 -08001396 // Creates an new AudioTrack. At the moment |source| can be null.
Yves Gerey665174f2018-06-19 15:03:05 +02001397 virtual rtc::scoped_refptr<AudioTrackInterface> CreateAudioTrack(
1398 const std::string& label,
1399 AudioSourceInterface* source) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001400
wu@webrtc.orga9890802013-12-13 00:21:03 +00001401 // Starts AEC dump using existing file. Takes ownership of |file| and passes
1402 // it on to VoiceEngine (via other objects) immediately, which will take
wu@webrtc.orga8910d22014-01-23 22:12:45 +00001403 // the ownerhip. If the operation fails, the file will be closed.
ivocd66b44d2016-01-15 03:06:36 -08001404 // A maximum file size in bytes can be specified. When the file size limit is
1405 // reached, logging is stopped automatically. If max_size_bytes is set to a
1406 // value <= 0, no limit will be used, and logging will continue until the
1407 // StopAecDump function is called.
1408 virtual bool StartAecDump(rtc::PlatformFile file, int64_t max_size_bytes) = 0;
wu@webrtc.orga9890802013-12-13 00:21:03 +00001409
ivoc797ef122015-10-22 03:25:41 -07001410 // Stops logging the AEC dump.
1411 virtual void StopAecDump() = 0;
1412
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001413 protected:
1414 // Dtor and ctor protected as objects shouldn't be created or deleted via
1415 // this interface.
1416 PeerConnectionFactoryInterface() {}
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001417 ~PeerConnectionFactoryInterface() override = default;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001418};
1419
Danil Chapovalov3b112e22019-05-20 14:36:00 +02001420// CreateModularPeerConnectionFactory is implemented in the "peerconnection"
1421// build target, which doesn't pull in the implementations of every module
1422// webrtc may use.
zhihuang38ede132017-06-15 12:52:32 -07001423//
1424// If an application knows it will only require certain modules, it can reduce
1425// webrtc's impact on its binary size by depending only on the "peerconnection"
1426// target and the modules the application requires, using
Danil Chapovalov3b112e22019-05-20 14:36:00 +02001427// CreateModularPeerConnectionFactory. For example, if an application
zhihuang38ede132017-06-15 12:52:32 -07001428// only uses WebRTC for audio, it can pass in null pointers for the
1429// video-specific interfaces, and omit the corresponding modules from its
1430// build.
1431//
1432// If |network_thread| or |worker_thread| are null, the PeerConnectionFactory
1433// will create the necessary thread internally. If |signaling_thread| is null,
1434// the PeerConnectionFactory will use the thread on which this method is called
1435// as the signaling thread, wrapping it in an rtc::Thread object if needed.
Benjamin Wright5234a492018-05-29 15:04:32 -07001436rtc::scoped_refptr<PeerConnectionFactoryInterface>
1437CreateModularPeerConnectionFactory(
1438 PeerConnectionFactoryDependencies dependencies);
1439
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001440} // namespace webrtc
1441
Steve Anton10542f22019-01-11 09:11:00 -08001442#endif // API_PEER_CONNECTION_INTERFACE_H_