blob: 5784d9500a89f82a3c7d55c5fe07ee7ea64a4c66 [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
12// http://dev.w3.org/2011/webrtc/editor/webrtc.html#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
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020067#ifndef API_PEERCONNECTIONINTERFACE_H_
68#define API_PEERCONNECTIONINTERFACE_H_
henrike@webrtc.org28e20752013-07-10 00:45:36 +000069
Sami Kalliomäki02879f92018-01-11 10:02:19 +010070// TODO(sakal): Remove this define after migration to virtual PeerConnection
71// observer is complete.
72#define VIRTUAL_PEERCONNECTION_OBSERVER_DESTRUCTOR
73
kwibergd1fe2812016-04-27 06:47:29 -070074#include <memory>
henrike@webrtc.org28e20752013-07-10 00:45:36 +000075#include <string>
kwiberg0eb15ed2015-12-17 03:04:15 -080076#include <utility>
henrike@webrtc.org28e20752013-07-10 00:45:36 +000077#include <vector>
78
Niels Möllerd377f042018-02-13 15:03:43 +010079#include "api/audio/audio_mixer.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020080#include "api/audio_codecs/audio_decoder_factory.h"
81#include "api/audio_codecs/audio_encoder_factory.h"
Niels Möllera6fe2612018-01-19 11:28:54 +010082#include "api/audio_options.h"
Niels Möller8366e172018-02-14 12:20:13 +010083#include "api/call/callfactoryinterface.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020084#include "api/datachannelinterface.h"
85#include "api/dtmfsenderinterface.h"
86#include "api/jsep.h"
87#include "api/mediastreaminterface.h"
88#include "api/rtcerror.h"
Elad Alon99c3fe52017-10-13 16:29:40 +020089#include "api/rtceventlogoutput.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020090#include "api/rtpreceiverinterface.h"
91#include "api/rtpsenderinterface.h"
Steve Anton9158ef62017-11-27 13:01:52 -080092#include "api/rtptransceiverinterface.h"
Henrik Boström31638672017-11-23 17:48:32 +010093#include "api/setremotedescriptionobserverinterface.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020094#include "api/stats/rtcstatscollectorcallback.h"
95#include "api/statstypes.h"
Jonas Orelandbdcee282017-10-10 14:01:40 +020096#include "api/turncustomizer.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020097#include "api/umametrics.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020098#include "logging/rtc_event_log/rtc_event_log_factory_interface.h"
Niels Möller6daa2782018-01-23 10:37:42 +010099#include "media/base/mediaconfig.h"
Niels Möller8366e172018-02-14 12:20:13 +0100100// TODO(bugs.webrtc.org/6353): cricket::VideoCapturer is deprecated and should
101// be deleted from the PeerConnection api.
102#include "media/base/videocapturer.h" // nogncheck
103// TODO(bugs.webrtc.org/7447): We plan to provide a way to let applications
104// inject a PacketSocketFactory and/or NetworkManager, and not expose
105// PortAllocator in the PeerConnection api.
106#include "p2p/base/portallocator.h" // nogncheck
107// TODO(nisse): The interface for bitrate allocation strategy belongs in api/.
108#include "rtc_base/bitrateallocationstrategy.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +0200109#include "rtc_base/network.h"
Niels Möller8366e172018-02-14 12:20:13 +0100110#include "rtc_base/platform_file.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +0200111#include "rtc_base/rtccertificate.h"
112#include "rtc_base/rtccertificategenerator.h"
113#include "rtc_base/socketaddress.h"
114#include "rtc_base/sslstreamadapter.h"
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000115
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000116namespace rtc {
jiayl@webrtc.org61e00b02015-03-04 22:17:38 +0000117class SSLIdentity;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000118class Thread;
119}
120
121namespace cricket {
zhihuang38ede132017-06-15 12:52:32 -0700122class MediaEngineInterface;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000123class WebRtcVideoDecoderFactory;
124class WebRtcVideoEncoderFactory;
125}
126
127namespace webrtc {
128class AudioDeviceModule;
gyzhou95aa9642016-12-13 14:06:26 -0800129class AudioMixer;
Niels Möller8366e172018-02-14 12:20:13 +0100130class AudioProcessing;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000131class MediaConstraintsInterface;
Magnus Jedvert58b03162017-09-15 19:02:47 +0200132class VideoDecoderFactory;
133class VideoEncoderFactory;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000134
135// MediaStream container interface.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000136class StreamCollectionInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000137 public:
138 // TODO(ronghuawu): Update the function names to c++ style, e.g. find -> Find.
139 virtual size_t count() = 0;
140 virtual MediaStreamInterface* at(size_t index) = 0;
141 virtual MediaStreamInterface* find(const std::string& label) = 0;
142 virtual MediaStreamTrackInterface* FindAudioTrack(
143 const std::string& id) = 0;
144 virtual MediaStreamTrackInterface* FindVideoTrack(
145 const std::string& id) = 0;
146
147 protected:
148 // Dtor protected as objects shouldn't be deleted via this interface.
149 ~StreamCollectionInterface() {}
150};
151
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000152class StatsObserver : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000153 public:
nissee8abe3e2017-01-18 05:00:34 -0800154 virtual void OnComplete(const StatsReports& reports) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000155
156 protected:
157 virtual ~StatsObserver() {}
158};
159
Steve Anton79e79602017-11-20 10:25:56 -0800160// For now, kDefault is interpreted as kPlanB.
161// TODO(bugs.webrtc.org/8530): Switch default to kUnifiedPlan.
162enum class SdpSemantics { kDefault, kPlanB, kUnifiedPlan };
163
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000164class PeerConnectionInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000165 public:
166 // See http://dev.w3.org/2011/webrtc/editor/webrtc.html#state-definitions .
167 enum SignalingState {
168 kStable,
169 kHaveLocalOffer,
170 kHaveLocalPrAnswer,
171 kHaveRemoteOffer,
172 kHaveRemotePrAnswer,
173 kClosed,
174 };
175
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000176 enum IceGatheringState {
177 kIceGatheringNew,
178 kIceGatheringGathering,
179 kIceGatheringComplete
180 };
181
182 enum IceConnectionState {
183 kIceConnectionNew,
184 kIceConnectionChecking,
185 kIceConnectionConnected,
186 kIceConnectionCompleted,
187 kIceConnectionFailed,
188 kIceConnectionDisconnected,
189 kIceConnectionClosed,
Guo-wei Shieh3d564c12015-08-19 16:51:15 -0700190 kIceConnectionMax,
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000191 };
192
hnsl04833622017-01-09 08:35:45 -0800193 // TLS certificate policy.
194 enum TlsCertPolicy {
195 // For TLS based protocols, ensure the connection is secure by not
196 // circumventing certificate validation.
197 kTlsCertPolicySecure,
198 // For TLS based protocols, disregard security completely by skipping
199 // certificate validation. This is insecure and should never be used unless
200 // security is irrelevant in that particular context.
201 kTlsCertPolicyInsecureNoCheck,
202 };
203
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000204 struct IceServer {
Joachim Bauch7c4e7452015-05-28 23:06:30 +0200205 // TODO(jbauch): Remove uri when all code using it has switched to urls.
Emad Omaradab1d2d2017-06-16 15:43:11 -0700206 // List of URIs associated with this server. Valid formats are described
207 // in RFC7064 and RFC7065, and more may be added in the future. The "host"
208 // part of the URI may contain either an IP address or a hostname.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000209 std::string uri;
Joachim Bauch7c4e7452015-05-28 23:06:30 +0200210 std::vector<std::string> urls;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000211 std::string username;
212 std::string password;
hnsl04833622017-01-09 08:35:45 -0800213 TlsCertPolicy tls_cert_policy = kTlsCertPolicySecure;
Emad Omaradab1d2d2017-06-16 15:43:11 -0700214 // If the URIs in |urls| only contain IP addresses, this field can be used
215 // to indicate the hostname, which may be necessary for TLS (using the SNI
216 // extension). If |urls| itself contains the hostname, this isn't
217 // necessary.
218 std::string hostname;
Diogo Real1dca9d52017-08-29 12:18:32 -0700219 // List of protocols to be used in the TLS ALPN extension.
220 std::vector<std::string> tls_alpn_protocols;
Diogo Real7bd1f1b2017-09-08 12:50:41 -0700221 // List of elliptic curves to be used in the TLS elliptic curves extension.
222 std::vector<std::string> tls_elliptic_curves;
hnsl04833622017-01-09 08:35:45 -0800223
deadbeefd1a38b52016-12-10 13:15:33 -0800224 bool operator==(const IceServer& o) const {
225 return uri == o.uri && urls == o.urls && username == o.username &&
Emad Omaradab1d2d2017-06-16 15:43:11 -0700226 password == o.password && tls_cert_policy == o.tls_cert_policy &&
Diogo Real1dca9d52017-08-29 12:18:32 -0700227 hostname == o.hostname &&
Diogo Real7bd1f1b2017-09-08 12:50:41 -0700228 tls_alpn_protocols == o.tls_alpn_protocols &&
229 tls_elliptic_curves == o.tls_elliptic_curves;
deadbeefd1a38b52016-12-10 13:15:33 -0800230 }
231 bool operator!=(const IceServer& o) const { return !(*this == o); }
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000232 };
233 typedef std::vector<IceServer> IceServers;
234
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000235 enum IceTransportsType {
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000236 // TODO(pthatcher): Rename these kTransporTypeXXX, but update
237 // Chromium at the same time.
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000238 kNone,
239 kRelay,
240 kNoHost,
241 kAll
242 };
243
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000244 // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-08#section-4.1.1
245 enum BundlePolicy {
246 kBundlePolicyBalanced,
247 kBundlePolicyMaxBundle,
248 kBundlePolicyMaxCompat
249 };
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000250
Peter Thatcheraf55ccc2015-05-21 07:48:41 -0700251 // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-09#section-4.1.1
252 enum RtcpMuxPolicy {
253 kRtcpMuxPolicyNegotiate,
254 kRtcpMuxPolicyRequire,
255 };
256
Jiayang Liucac1b382015-04-30 12:35:24 -0700257 enum TcpCandidatePolicy {
258 kTcpCandidatePolicyEnabled,
259 kTcpCandidatePolicyDisabled
260 };
261
honghaiz60347052016-05-31 18:29:12 -0700262 enum CandidateNetworkPolicy {
263 kCandidateNetworkPolicyAll,
264 kCandidateNetworkPolicyLowCost
265 };
266
honghaiz1f429e32015-09-28 07:57:34 -0700267 enum ContinualGatheringPolicy {
268 GATHER_ONCE,
269 GATHER_CONTINUALLY
270 };
271
Honghai Zhangf7ddc062016-09-01 15:34:01 -0700272 enum class RTCConfigurationType {
273 // A configuration that is safer to use, despite not having the best
274 // performance. Currently this is the default configuration.
275 kSafe,
276 // An aggressive configuration that has better performance, although it
277 // may be riskier and may need extra support in the application.
278 kAggressive
279 };
280
Henrik Boström87713d02015-08-25 09:53:21 +0200281 // TODO(hbos): Change into class with private data and public getters.
nissec36b31b2016-04-11 23:25:29 -0700282 // TODO(nisse): In particular, accessing fields directly from an
283 // application is brittle, since the organization mirrors the
284 // organization of the implementation, which isn't stable. So we
285 // need getters and setters at least for fields which applications
286 // are interested in.
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000287 struct RTCConfiguration {
Niels Möller71bdda02016-03-31 12:59:59 +0200288 // This struct is subject to reorganization, both for naming
289 // consistency, and to group settings to match where they are used
290 // in the implementation. To do that, we need getter and setter
291 // methods for all settings which are of interest to applications,
292 // Chrome in particular.
293
Honghai Zhangf7ddc062016-09-01 15:34:01 -0700294 RTCConfiguration() = default;
oprypin803dc292017-02-01 01:55:59 -0800295 explicit RTCConfiguration(RTCConfigurationType type) {
Honghai Zhangf7ddc062016-09-01 15:34:01 -0700296 if (type == RTCConfigurationType::kAggressive) {
Honghai Zhangaecd9822016-09-02 16:58:17 -0700297 // These parameters are also defined in Java and IOS configurations,
298 // so their values may be overwritten by the Java or IOS configuration.
299 bundle_policy = kBundlePolicyMaxBundle;
300 rtcp_mux_policy = kRtcpMuxPolicyRequire;
301 ice_connection_receiving_timeout =
302 kAggressiveIceConnectionReceivingTimeout;
303
304 // These parameters are not defined in Java or IOS configuration,
305 // so their values will not be overwritten.
306 enable_ice_renomination = true;
Honghai Zhangf7ddc062016-09-01 15:34:01 -0700307 redetermine_role_on_ice_restart = false;
308 }
Honghai Zhangbfd398c2016-08-30 22:07:42 -0700309 }
310
deadbeef293e9262017-01-11 12:28:30 -0800311 bool operator==(const RTCConfiguration& o) const;
312 bool operator!=(const RTCConfiguration& o) const;
313
Niels Möller6539f692018-01-18 08:58:50 +0100314 bool dscp() const { return media_config.enable_dscp; }
nissec36b31b2016-04-11 23:25:29 -0700315 void set_dscp(bool enable) { media_config.enable_dscp = enable; }
Niels Möller71bdda02016-03-31 12:59:59 +0200316
Niels Möller6539f692018-01-18 08:58:50 +0100317 bool cpu_adaptation() const {
Niels Möller1d7ecd22018-01-18 15:25:12 +0100318 return media_config.video.enable_cpu_adaptation;
nissec36b31b2016-04-11 23:25:29 -0700319 }
Niels Möller71bdda02016-03-31 12:59:59 +0200320 void set_cpu_adaptation(bool enable) {
Niels Möller1d7ecd22018-01-18 15:25:12 +0100321 media_config.video.enable_cpu_adaptation = enable;
Niels Möller71bdda02016-03-31 12:59:59 +0200322 }
323
Niels Möller6539f692018-01-18 08:58:50 +0100324 bool suspend_below_min_bitrate() const {
nissec36b31b2016-04-11 23:25:29 -0700325 return media_config.video.suspend_below_min_bitrate;
326 }
Niels Möller71bdda02016-03-31 12:59:59 +0200327 void set_suspend_below_min_bitrate(bool enable) {
nissec36b31b2016-04-11 23:25:29 -0700328 media_config.video.suspend_below_min_bitrate = enable;
Niels Möller71bdda02016-03-31 12:59:59 +0200329 }
330
Niels Möller6539f692018-01-18 08:58:50 +0100331 bool prerenderer_smoothing() const {
Niels Möller1d7ecd22018-01-18 15:25:12 +0100332 return media_config.video.enable_prerenderer_smoothing;
nissec36b31b2016-04-11 23:25:29 -0700333 }
Niels Möller71bdda02016-03-31 12:59:59 +0200334 void set_prerenderer_smoothing(bool enable) {
Niels Möller1d7ecd22018-01-18 15:25:12 +0100335 media_config.video.enable_prerenderer_smoothing = enable;
Niels Möller71bdda02016-03-31 12:59:59 +0200336 }
337
Niels Möller6539f692018-01-18 08:58:50 +0100338 bool experiment_cpu_load_estimator() const {
339 return media_config.video.experiment_cpu_load_estimator;
340 }
341 void set_experiment_cpu_load_estimator(bool enable) {
342 media_config.video.experiment_cpu_load_estimator = enable;
343 }
honghaiz4edc39c2015-09-01 09:53:56 -0700344 static const int kUndefined = -1;
345 // Default maximum number of packets in the audio jitter buffer.
346 static const int kAudioJitterBufferMaxPackets = 50;
Honghai Zhangaecd9822016-09-02 16:58:17 -0700347 // ICE connection receiving timeout for aggressive configuration.
348 static const int kAggressiveIceConnectionReceivingTimeout = 1000;
deadbeefb10f32f2017-02-08 01:38:21 -0800349
350 ////////////////////////////////////////////////////////////////////////
351 // The below few fields mirror the standard RTCConfiguration dictionary:
352 // https://www.w3.org/TR/webrtc/#rtcconfiguration-dictionary
353 ////////////////////////////////////////////////////////////////////////
354
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000355 // TODO(pthatcher): Rename this ice_servers, but update Chromium
356 // at the same time.
357 IceServers servers;
deadbeefb10f32f2017-02-08 01:38:21 -0800358 // TODO(pthatcher): Rename this ice_transport_type, but update
359 // Chromium at the same time.
360 IceTransportsType type = kAll;
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700361 BundlePolicy bundle_policy = kBundlePolicyBalanced;
zhihuang4dfb8ce2016-11-23 10:30:12 -0800362 RtcpMuxPolicy rtcp_mux_policy = kRtcpMuxPolicyRequire;
deadbeefb10f32f2017-02-08 01:38:21 -0800363 std::vector<rtc::scoped_refptr<rtc::RTCCertificate>> certificates;
364 int ice_candidate_pool_size = 0;
365
366 //////////////////////////////////////////////////////////////////////////
367 // The below fields correspond to constraints from the deprecated
368 // constraints interface for constructing a PeerConnection.
369 //
370 // rtc::Optional fields can be "missing", in which case the implementation
371 // default will be used.
372 //////////////////////////////////////////////////////////////////////////
373
374 // If set to true, don't gather IPv6 ICE candidates.
375 // TODO(deadbeef): Remove this? IPv6 support has long stopped being
376 // experimental
377 bool disable_ipv6 = false;
378
zhihuangb09b3f92017-03-07 14:40:51 -0800379 // If set to true, don't gather IPv6 ICE candidates on Wi-Fi.
380 // Only intended to be used on specific devices. Certain phones disable IPv6
381 // when the screen is turned off and it would be better to just disable the
382 // IPv6 ICE candidates on Wi-Fi in those cases.
383 bool disable_ipv6_on_wifi = false;
384
deadbeefd21eab32017-07-26 16:50:11 -0700385 // By default, the PeerConnection will use a limited number of IPv6 network
386 // interfaces, in order to avoid too many ICE candidate pairs being created
387 // and delaying ICE completion.
388 //
389 // Can be set to INT_MAX to effectively disable the limit.
390 int max_ipv6_networks = cricket::kDefaultMaxIPv6Networks;
391
Daniel Lazarenko2870b0a2018-01-25 10:30:22 +0100392 // Exclude link-local network interfaces
393 // from considertaion for gathering ICE candidates.
394 bool disable_link_local_networks = false;
395
deadbeefb10f32f2017-02-08 01:38:21 -0800396 // If set to true, use RTP data channels instead of SCTP.
397 // TODO(deadbeef): Remove this. We no longer commit to supporting RTP data
398 // channels, though some applications are still working on moving off of
399 // them.
400 bool enable_rtp_data_channel = false;
401
402 // Minimum bitrate at which screencast video tracks will be encoded at.
403 // This means adding padding bits up to this bitrate, which can help
404 // when switching from a static scene to one with motion.
405 rtc::Optional<int> screencast_min_bitrate;
406
407 // Use new combined audio/video bandwidth estimation?
408 rtc::Optional<bool> combined_audio_video_bwe;
409
410 // Can be used to disable DTLS-SRTP. This should never be done, but can be
411 // useful for testing purposes, for example in setting up a loopback call
412 // with a single PeerConnection.
413 rtc::Optional<bool> enable_dtls_srtp;
414
415 /////////////////////////////////////////////////
416 // The below fields are not part of the standard.
417 /////////////////////////////////////////////////
418
419 // Can be used to disable TCP candidate generation.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700420 TcpCandidatePolicy tcp_candidate_policy = kTcpCandidatePolicyEnabled;
deadbeefb10f32f2017-02-08 01:38:21 -0800421
422 // Can be used to avoid gathering candidates for a "higher cost" network,
423 // if a lower cost one exists. For example, if both Wi-Fi and cellular
424 // interfaces are available, this could be used to avoid using the cellular
425 // interface.
honghaiz60347052016-05-31 18:29:12 -0700426 CandidateNetworkPolicy candidate_network_policy =
427 kCandidateNetworkPolicyAll;
deadbeefb10f32f2017-02-08 01:38:21 -0800428
429 // The maximum number of packets that can be stored in the NetEq audio
430 // jitter buffer. Can be reduced to lower tolerated audio latency.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700431 int audio_jitter_buffer_max_packets = kAudioJitterBufferMaxPackets;
deadbeefb10f32f2017-02-08 01:38:21 -0800432
433 // Whether to use the NetEq "fast mode" which will accelerate audio quicker
434 // if it falls behind.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700435 bool audio_jitter_buffer_fast_accelerate = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800436
437 // Timeout in milliseconds before an ICE candidate pair is considered to be
438 // "not receiving", after which a lower priority candidate pair may be
439 // selected.
440 int ice_connection_receiving_timeout = kUndefined;
441
442 // Interval in milliseconds at which an ICE "backup" candidate pair will be
443 // pinged. This is a candidate pair which is not actively in use, but may
444 // be switched to if the active candidate pair becomes unusable.
445 //
446 // This is relevant mainly to Wi-Fi/cell handoff; the application may not
447 // want this backup cellular candidate pair pinged frequently, since it
448 // consumes data/battery.
449 int ice_backup_candidate_pair_ping_interval = kUndefined;
450
451 // Can be used to enable continual gathering, which means new candidates
452 // will be gathered as network interfaces change. Note that if continual
453 // gathering is used, the candidate removal API should also be used, to
454 // avoid an ever-growing list of candidates.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700455 ContinualGatheringPolicy continual_gathering_policy = GATHER_ONCE;
deadbeefb10f32f2017-02-08 01:38:21 -0800456
457 // If set to true, candidate pairs will be pinged in order of most likely
458 // to work (which means using a TURN server, generally), rather than in
459 // standard priority order.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700460 bool prioritize_most_likely_ice_candidate_pairs = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800461
Niels Möller6daa2782018-01-23 10:37:42 +0100462 // Implementation defined settings. A public member only for the benefit of
463 // the implementation. Applications must not access it directly, and should
464 // instead use provided accessor methods, e.g., set_cpu_adaptation.
nissec36b31b2016-04-11 23:25:29 -0700465 struct cricket::MediaConfig media_config;
deadbeefb10f32f2017-02-08 01:38:21 -0800466
deadbeefb10f32f2017-02-08 01:38:21 -0800467 // If set to true, only one preferred TURN allocation will be used per
468 // network interface. UDP is preferred over TCP and IPv6 over IPv4. This
469 // can be used to cut down on the number of candidate pairings.
Honghai Zhangb9e7b4a2016-06-30 20:52:02 -0700470 bool prune_turn_ports = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800471
Taylor Brandstettere9851112016-07-01 11:11:13 -0700472 // If set to true, this means the ICE transport should presume TURN-to-TURN
473 // candidate pairs will succeed, even before a binding response is received.
deadbeefb10f32f2017-02-08 01:38:21 -0800474 // This can be used to optimize the initial connection time, since the DTLS
475 // handshake can begin immediately.
Taylor Brandstettere9851112016-07-01 11:11:13 -0700476 bool presume_writable_when_fully_relayed = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800477
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700478 // If true, "renomination" will be added to the ice options in the transport
479 // description.
deadbeefb10f32f2017-02-08 01:38:21 -0800480 // See: https://tools.ietf.org/html/draft-thatcher-ice-renomination-00
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700481 bool enable_ice_renomination = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800482
483 // If true, the ICE role is re-determined when the PeerConnection sets a
484 // local transport description that indicates an ICE restart.
485 //
486 // This is standard RFC5245 ICE behavior, but causes unnecessary role
487 // thrashing, so an application may wish to avoid it. This role
488 // re-determining was removed in ICEbis (ICE v2).
Honghai Zhangbfd398c2016-08-30 22:07:42 -0700489 bool redetermine_role_on_ice_restart = true;
deadbeefb10f32f2017-02-08 01:38:21 -0800490
skvlad51072462017-02-02 11:50:14 -0800491 // If set, the min interval (max rate) at which we will send ICE checks
492 // (STUN pings), in milliseconds.
493 rtc::Optional<int> ice_check_min_interval;
deadbeefb10f32f2017-02-08 01:38:21 -0800494
Steve Anton300bf8e2017-07-14 10:13:10 -0700495 // ICE Periodic Regathering
496 // If set, WebRTC will periodically create and propose candidates without
497 // starting a new ICE generation. The regathering happens continuously with
498 // interval specified in milliseconds by the uniform distribution [a, b].
499 rtc::Optional<rtc::IntervalRange> ice_regather_interval_range;
500
Jonas Orelandbdcee282017-10-10 14:01:40 +0200501 // Optional TurnCustomizer.
502 // With this class one can modify outgoing TURN messages.
503 // The object passed in must remain valid until PeerConnection::Close() is
504 // called.
505 webrtc::TurnCustomizer* turn_customizer = nullptr;
506
Qingsi Wang9a5c6f82018-02-01 10:38:40 -0800507 // Preferred network interface.
508 // A candidate pair on a preferred network has a higher precedence in ICE
509 // than one on an un-preferred network, regardless of priority or network
510 // cost.
511 rtc::Optional<rtc::AdapterType> network_preference;
512
Steve Anton79e79602017-11-20 10:25:56 -0800513 // Configure the SDP semantics used by this PeerConnection. Note that the
514 // WebRTC 1.0 specification requires kUnifiedPlan semantics. The
515 // RtpTransceiver API is only available with kUnifiedPlan semantics.
516 //
517 // kPlanB will cause PeerConnection to create offers and answers with at
518 // most one audio and one video m= section with multiple RtpSenders and
519 // RtpReceivers specified as multiple a=ssrc lines within the section. This
520 // will also cause PeerConnection to reject offers/answers with multiple m=
521 // sections of the same media type.
522 //
523 // kUnifiedPlan will cause PeerConnection to create offers and answers with
524 // multiple m= sections where each m= section maps to one RtpSender and one
525 // RtpReceiver (an RtpTransceiver), either both audio or both video. Plan B
526 // style offers or answers will be rejected in calls to SetLocalDescription
527 // or SetRemoteDescription.
528 //
529 // For users who only send at most one audio and one video track, this
530 // choice does not matter and should be left as kDefault.
531 //
532 // For users who wish to send multiple audio/video streams and need to stay
533 // interoperable with legacy WebRTC implementations, specify kPlanB.
534 //
535 // For users who wish to send multiple audio/video streams and/or wish to
536 // use the new RtpTransceiver API, specify kUnifiedPlan.
537 //
538 // TODO(steveanton): Implement support for kUnifiedPlan.
539 SdpSemantics sdp_semantics = SdpSemantics::kDefault;
540
deadbeef293e9262017-01-11 12:28:30 -0800541 //
542 // Don't forget to update operator== if adding something.
543 //
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000544 };
545
deadbeefb10f32f2017-02-08 01:38:21 -0800546 // See: https://www.w3.org/TR/webrtc/#idl-def-rtcofferansweroptions
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000547 struct RTCOfferAnswerOptions {
548 static const int kUndefined = -1;
549 static const int kMaxOfferToReceiveMedia = 1;
550
551 // The default value for constraint offerToReceiveX:true.
552 static const int kOfferToReceiveMediaTrue = 1;
553
deadbeefb10f32f2017-02-08 01:38:21 -0800554 // These have been removed from the standard in favor of the "transceiver"
555 // API, but given that we don't support that API, we still have them here.
556 //
557 // offer_to_receive_X set to 1 will cause a media description to be
558 // generated in the offer, even if no tracks of that type have been added.
559 // Values greater than 1 are treated the same.
560 //
561 // If set to 0, the generated directional attribute will not include the
562 // "recv" direction (meaning it will be "sendonly" or "inactive".
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700563 int offer_to_receive_video = kUndefined;
564 int offer_to_receive_audio = kUndefined;
deadbeefb10f32f2017-02-08 01:38:21 -0800565
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700566 bool voice_activity_detection = true;
567 bool ice_restart = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800568
569 // If true, will offer to BUNDLE audio/video/data together. Not to be
570 // confused with RTCP mux (multiplexing RTP and RTCP together).
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700571 bool use_rtp_mux = true;
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000572
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700573 RTCOfferAnswerOptions() = default;
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000574
575 RTCOfferAnswerOptions(int offer_to_receive_video,
576 int offer_to_receive_audio,
577 bool voice_activity_detection,
578 bool ice_restart,
579 bool use_rtp_mux)
580 : offer_to_receive_video(offer_to_receive_video),
581 offer_to_receive_audio(offer_to_receive_audio),
582 voice_activity_detection(voice_activity_detection),
583 ice_restart(ice_restart),
584 use_rtp_mux(use_rtp_mux) {}
585 };
586
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000587 // Used by GetStats to decide which stats to include in the stats reports.
588 // |kStatsOutputLevelStandard| includes the standard stats for Javascript API;
589 // |kStatsOutputLevelDebug| includes both the standard stats and additional
590 // stats for debugging purposes.
591 enum StatsOutputLevel {
592 kStatsOutputLevelStandard,
593 kStatsOutputLevelDebug,
594 };
595
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000596 // Accessor methods to active local streams.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000597 virtual rtc::scoped_refptr<StreamCollectionInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000598 local_streams() = 0;
599
600 // Accessor methods to remote streams.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000601 virtual rtc::scoped_refptr<StreamCollectionInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000602 remote_streams() = 0;
603
604 // Add a new MediaStream to be sent on this PeerConnection.
605 // Note that a SessionDescription negotiation is needed before the
606 // remote peer can receive the stream.
deadbeefb10f32f2017-02-08 01:38:21 -0800607 //
608 // This has been removed from the standard in favor of a track-based API. So,
609 // this is equivalent to simply calling AddTrack for each track within the
610 // stream, with the one difference that if "stream->AddTrack(...)" is called
611 // later, the PeerConnection will automatically pick up the new track. Though
612 // this functionality will be deprecated in the future.
perkj@webrtc.orgfd0efb62014-11-06 12:16:36 +0000613 virtual bool AddStream(MediaStreamInterface* stream) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000614
615 // Remove a MediaStream from this PeerConnection.
deadbeefb10f32f2017-02-08 01:38:21 -0800616 // Note that a SessionDescription negotiation is needed before the
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000617 // remote peer is notified.
618 virtual void RemoveStream(MediaStreamInterface* stream) = 0;
619
deadbeefb10f32f2017-02-08 01:38:21 -0800620 // Add a new MediaStreamTrack to be sent on this PeerConnection, and return
Steve Antonf9381f02017-12-14 10:23:57 -0800621 // the newly created RtpSender. The RtpSender will be associated with the
622 // streams specified in the |stream_labels| list.
deadbeefb10f32f2017-02-08 01:38:21 -0800623 //
Steve Antonf9381f02017-12-14 10:23:57 -0800624 // Errors:
625 // - INVALID_PARAMETER: |track| is null, has a kind other than audio or video,
626 // or a sender already exists for the track.
627 // - INVALID_STATE: The PeerConnection is closed.
628 // TODO(steveanton): Remove default implementation once downstream
629 // implementations have been updated.
Steve Anton2d6c76a2018-01-05 17:10:52 -0800630 virtual RTCErrorOr<rtc::scoped_refptr<RtpSenderInterface>> AddTrack(
631 rtc::scoped_refptr<MediaStreamTrackInterface> track,
632 const std::vector<std::string>& stream_labels) {
Steve Antonf9381f02017-12-14 10:23:57 -0800633 return RTCError(RTCErrorType::UNSUPPORTED_OPERATION, "Not implemented");
634 }
deadbeefe1f9d832016-01-14 15:35:42 -0800635 // |streams| indicates which stream labels the track should be associated
636 // with.
Steve Antonf9381f02017-12-14 10:23:57 -0800637 // TODO(steveanton): Remove this overload once callers have moved to the
638 // signature with stream labels.
deadbeefe1f9d832016-01-14 15:35:42 -0800639 virtual rtc::scoped_refptr<RtpSenderInterface> AddTrack(
640 MediaStreamTrackInterface* track,
nisse7f067662017-03-08 06:59:45 -0800641 std::vector<MediaStreamInterface*> streams) = 0;
deadbeefe1f9d832016-01-14 15:35:42 -0800642
643 // Remove an RtpSender from this PeerConnection.
644 // Returns true on success.
nisse7f067662017-03-08 06:59:45 -0800645 virtual bool RemoveTrack(RtpSenderInterface* sender) = 0;
deadbeefe1f9d832016-01-14 15:35:42 -0800646
Steve Anton9158ef62017-11-27 13:01:52 -0800647 // AddTransceiver creates a new RtpTransceiver and adds it to the set of
648 // transceivers. Adding a transceiver will cause future calls to CreateOffer
649 // to add a media description for the corresponding transceiver.
650 //
651 // The initial value of |mid| in the returned transceiver is null. Setting a
652 // new session description may change it to a non-null value.
653 //
654 // https://w3c.github.io/webrtc-pc/#dom-rtcpeerconnection-addtransceiver
655 //
656 // Optionally, an RtpTransceiverInit structure can be specified to configure
657 // the transceiver from construction. If not specified, the transceiver will
658 // default to having a direction of kSendRecv and not be part of any streams.
659 //
660 // These methods are only available when Unified Plan is enabled (see
661 // RTCConfiguration).
662 //
663 // Common errors:
664 // - INTERNAL_ERROR: The configuration does not have Unified Plan enabled.
665 // TODO(steveanton): Make these pure virtual once downstream projects have
666 // updated.
667
668 // Adds a transceiver with a sender set to transmit the given track. The kind
669 // of the transceiver (and sender/receiver) will be derived from the kind of
670 // the track.
671 // Errors:
672 // - INVALID_PARAMETER: |track| is null.
673 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>>
674 AddTransceiver(rtc::scoped_refptr<MediaStreamTrackInterface> track) {
675 return RTCError(RTCErrorType::INTERNAL_ERROR, "not implemented");
676 }
677 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>>
678 AddTransceiver(rtc::scoped_refptr<MediaStreamTrackInterface> track,
679 const RtpTransceiverInit& init) {
680 return RTCError(RTCErrorType::INTERNAL_ERROR, "not implemented");
681 }
682
683 // Adds a transceiver with the given kind. Can either be MEDIA_TYPE_AUDIO or
684 // MEDIA_TYPE_VIDEO.
685 // Errors:
686 // - INVALID_PARAMETER: |media_type| is not MEDIA_TYPE_AUDIO or
687 // MEDIA_TYPE_VIDEO.
688 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>>
689 AddTransceiver(cricket::MediaType media_type) {
690 return RTCError(RTCErrorType::INTERNAL_ERROR, "not implemented");
691 }
692 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>>
693 AddTransceiver(cricket::MediaType media_type,
694 const RtpTransceiverInit& init) {
695 return RTCError(RTCErrorType::INTERNAL_ERROR, "not implemented");
696 }
697
deadbeef8d60a942017-02-27 14:47:33 -0800698 // Returns pointer to a DtmfSender on success. Otherwise returns null.
deadbeefb10f32f2017-02-08 01:38:21 -0800699 //
700 // This API is no longer part of the standard; instead DtmfSenders are
701 // obtained from RtpSenders. Which is what the implementation does; it finds
702 // an RtpSender for |track| and just returns its DtmfSender.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000703 virtual rtc::scoped_refptr<DtmfSenderInterface> CreateDtmfSender(
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000704 AudioTrackInterface* track) = 0;
705
deadbeef70ab1a12015-09-28 16:53:55 -0700706 // TODO(deadbeef): Make these pure virtual once all subclasses implement them.
deadbeefb10f32f2017-02-08 01:38:21 -0800707
708 // Creates a sender without a track. Can be used for "early media"/"warmup"
709 // use cases, where the application may want to negotiate video attributes
710 // before a track is available to send.
711 //
712 // The standard way to do this would be through "addTransceiver", but we
713 // don't support that API yet.
714 //
deadbeeffac06552015-11-25 11:26:01 -0800715 // |kind| must be "audio" or "video".
deadbeefb10f32f2017-02-08 01:38:21 -0800716 //
deadbeefbd7d8f72015-12-18 16:58:44 -0800717 // |stream_id| is used to populate the msid attribute; if empty, one will
718 // be generated automatically.
deadbeeffac06552015-11-25 11:26:01 -0800719 virtual rtc::scoped_refptr<RtpSenderInterface> CreateSender(
deadbeefbd7d8f72015-12-18 16:58:44 -0800720 const std::string& kind,
721 const std::string& stream_id) {
deadbeeffac06552015-11-25 11:26:01 -0800722 return rtc::scoped_refptr<RtpSenderInterface>();
723 }
724
deadbeefb10f32f2017-02-08 01:38:21 -0800725 // Get all RtpSenders, created either through AddStream, AddTrack, or
726 // CreateSender. Note that these are "Plan B SDP" RtpSenders, not "Unified
727 // Plan SDP" RtpSenders, which means that all senders of a specific media
728 // type share the same media description.
deadbeef70ab1a12015-09-28 16:53:55 -0700729 virtual std::vector<rtc::scoped_refptr<RtpSenderInterface>> GetSenders()
730 const {
731 return std::vector<rtc::scoped_refptr<RtpSenderInterface>>();
732 }
733
deadbeefb10f32f2017-02-08 01:38:21 -0800734 // Get all RtpReceivers, created when a remote description is applied.
735 // Note that these are "Plan B SDP" RtpReceivers, not "Unified Plan SDP"
736 // RtpReceivers, which means that all receivers of a specific media type
737 // share the same media description.
738 //
739 // It is also possible to have a media description with no associated
740 // RtpReceivers, if the directional attribute does not indicate that the
741 // remote peer is sending any media.
deadbeef70ab1a12015-09-28 16:53:55 -0700742 virtual std::vector<rtc::scoped_refptr<RtpReceiverInterface>> GetReceivers()
743 const {
744 return std::vector<rtc::scoped_refptr<RtpReceiverInterface>>();
745 }
746
Steve Anton9158ef62017-11-27 13:01:52 -0800747 // Get all RtpTransceivers, created either through AddTransceiver, AddTrack or
748 // by a remote description applied with SetRemoteDescription.
749 // Note: This method is only available when Unified Plan is enabled (see
750 // RTCConfiguration).
751 virtual std::vector<rtc::scoped_refptr<RtpTransceiverInterface>>
752 GetTransceivers() const {
753 return {};
754 }
755
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000756 virtual bool GetStats(StatsObserver* observer,
757 MediaStreamTrackInterface* track,
758 StatsOutputLevel level) = 0;
hbos74e1a4f2016-09-15 23:33:01 -0700759 // Gets stats using the new stats collection API, see webrtc/api/stats/. These
760 // will replace old stats collection API when the new API has matured enough.
hbose3810152016-12-13 02:35:19 -0800761 // TODO(hbos): Default implementation that does nothing only exists as to not
762 // break third party projects. As soon as they have been updated this should
763 // be changed to "= 0;".
764 virtual void GetStats(RTCStatsCollectorCallback* callback) {}
Harald Alvestrand89061872018-01-02 14:08:34 +0100765 // Clear cached stats in the rtcstatscollector.
766 // Exposed for testing while waiting for automatic cache clear to work.
767 // https://bugs.webrtc.org/8693
768 virtual void ClearStatsCache() {}
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000769
deadbeefb10f32f2017-02-08 01:38:21 -0800770 // Create a data channel with the provided config, or default config if none
771 // is provided. Note that an offer/answer negotiation is still necessary
772 // before the data channel can be used.
773 //
774 // Also, calling CreateDataChannel is the only way to get a data "m=" section
775 // in SDP, so it should be done before CreateOffer is called, if the
776 // application plans to use data channels.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000777 virtual rtc::scoped_refptr<DataChannelInterface> CreateDataChannel(
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000778 const std::string& label,
779 const DataChannelInit* config) = 0;
780
deadbeefb10f32f2017-02-08 01:38:21 -0800781 // Returns the more recently applied description; "pending" if it exists, and
782 // otherwise "current". See below.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000783 virtual const SessionDescriptionInterface* local_description() const = 0;
784 virtual const SessionDescriptionInterface* remote_description() const = 0;
deadbeefb10f32f2017-02-08 01:38:21 -0800785
deadbeeffe4a8a42016-12-20 17:56:17 -0800786 // A "current" description the one currently negotiated from a complete
787 // offer/answer exchange.
788 virtual const SessionDescriptionInterface* current_local_description() const {
789 return nullptr;
790 }
791 virtual const SessionDescriptionInterface* current_remote_description()
792 const {
793 return nullptr;
794 }
deadbeefb10f32f2017-02-08 01:38:21 -0800795
deadbeeffe4a8a42016-12-20 17:56:17 -0800796 // A "pending" description is one that's part of an incomplete offer/answer
797 // exchange (thus, either an offer or a pranswer). Once the offer/answer
798 // exchange is finished, the "pending" description will become "current".
799 virtual const SessionDescriptionInterface* pending_local_description() const {
800 return nullptr;
801 }
802 virtual const SessionDescriptionInterface* pending_remote_description()
803 const {
804 return nullptr;
805 }
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000806
807 // Create a new offer.
808 // The CreateSessionDescriptionObserver callback will be called when done.
809 virtual void CreateOffer(CreateSessionDescriptionObserver* observer,
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000810 const MediaConstraintsInterface* constraints) {}
811
812 // TODO(jiayl): remove the default impl and the old interface when chromium
813 // code is updated.
814 virtual void CreateOffer(CreateSessionDescriptionObserver* observer,
815 const RTCOfferAnswerOptions& options) {}
816
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000817 // Create an answer to an offer.
818 // The CreateSessionDescriptionObserver callback will be called when done.
819 virtual void CreateAnswer(CreateSessionDescriptionObserver* observer,
htaa2a49d92016-03-04 02:51:39 -0800820 const RTCOfferAnswerOptions& options) {}
821 // Deprecated - use version above.
822 // TODO(hta): Remove and remove default implementations when all callers
823 // are updated.
824 virtual void CreateAnswer(CreateSessionDescriptionObserver* observer,
825 const MediaConstraintsInterface* constraints) {}
826
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000827 // Sets the local session description.
deadbeef1dcb1642017-03-29 21:08:16 -0700828 // The PeerConnection takes the ownership of |desc| even if it fails.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000829 // The |observer| callback will be called when done.
deadbeef1dcb1642017-03-29 21:08:16 -0700830 // TODO(deadbeef): Change |desc| to be a unique_ptr, to make it clear
831 // that this method always takes ownership of it.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000832 virtual void SetLocalDescription(SetSessionDescriptionObserver* observer,
833 SessionDescriptionInterface* desc) = 0;
834 // Sets the remote session description.
deadbeef1dcb1642017-03-29 21:08:16 -0700835 // The PeerConnection takes the ownership of |desc| even if it fails.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000836 // The |observer| callback will be called when done.
Henrik Boström31638672017-11-23 17:48:32 +0100837 // TODO(hbos): Remove when Chrome implements the new signature.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000838 virtual void SetRemoteDescription(SetSessionDescriptionObserver* observer,
Henrik Boström07109652017-11-27 09:52:02 +0100839 SessionDescriptionInterface* desc) {}
Henrik Boström31638672017-11-23 17:48:32 +0100840 // TODO(hbos): Make pure virtual when Chrome has updated its signature.
841 virtual void SetRemoteDescription(
842 std::unique_ptr<SessionDescriptionInterface> desc,
843 rtc::scoped_refptr<SetRemoteDescriptionObserverInterface> observer) {}
deadbeefb10f32f2017-02-08 01:38:21 -0800844 // Deprecated; Replaced by SetConfiguration.
deadbeefa67696b2015-09-29 11:56:26 -0700845 // TODO(deadbeef): Remove once Chrome is moved over to SetConfiguration.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000846 virtual bool UpdateIce(const IceServers& configuration,
deadbeefa67696b2015-09-29 11:56:26 -0700847 const MediaConstraintsInterface* constraints) {
848 return false;
849 }
htaa2a49d92016-03-04 02:51:39 -0800850 virtual bool UpdateIce(const IceServers& configuration) { return false; }
deadbeefb10f32f2017-02-08 01:38:21 -0800851
deadbeef46c73892016-11-16 19:42:04 -0800852 // TODO(deadbeef): Make this pure virtual once all Chrome subclasses of
853 // PeerConnectionInterface implement it.
854 virtual PeerConnectionInterface::RTCConfiguration GetConfiguration() {
855 return PeerConnectionInterface::RTCConfiguration();
856 }
deadbeef293e9262017-01-11 12:28:30 -0800857
deadbeefa67696b2015-09-29 11:56:26 -0700858 // Sets the PeerConnection's global configuration to |config|.
deadbeef293e9262017-01-11 12:28:30 -0800859 //
860 // The members of |config| that may be changed are |type|, |servers|,
861 // |ice_candidate_pool_size| and |prune_turn_ports| (though the candidate
862 // pool size can't be changed after the first call to SetLocalDescription).
863 // Note that this means the BUNDLE and RTCP-multiplexing policies cannot be
864 // changed with this method.
865 //
deadbeefa67696b2015-09-29 11:56:26 -0700866 // Any changes to STUN/TURN servers or ICE candidate policy will affect the
867 // next gathering phase, and cause the next call to createOffer to generate
deadbeef293e9262017-01-11 12:28:30 -0800868 // new ICE credentials, as described in JSEP. This also occurs when
869 // |prune_turn_ports| changes, for the same reasoning.
870 //
871 // If an error occurs, returns false and populates |error| if non-null:
872 // - INVALID_MODIFICATION if |config| contains a modified parameter other
873 // than one of the parameters listed above.
874 // - INVALID_RANGE if |ice_candidate_pool_size| is out of range.
875 // - SYNTAX_ERROR if parsing an ICE server URL failed.
876 // - INVALID_PARAMETER if a TURN server is missing |username| or |password|.
877 // - INTERNAL_ERROR if an unexpected error occurred.
878 //
deadbeefa67696b2015-09-29 11:56:26 -0700879 // TODO(deadbeef): Make this pure virtual once all Chrome subclasses of
880 // PeerConnectionInterface implement it.
881 virtual bool SetConfiguration(
deadbeef293e9262017-01-11 12:28:30 -0800882 const PeerConnectionInterface::RTCConfiguration& config,
883 RTCError* error) {
884 return false;
885 }
886 // Version without error output param for backwards compatibility.
887 // TODO(deadbeef): Remove once chromium is updated.
888 virtual bool SetConfiguration(
deadbeef1e234612016-12-24 01:43:32 -0800889 const PeerConnectionInterface::RTCConfiguration& config) {
deadbeefa67696b2015-09-29 11:56:26 -0700890 return false;
891 }
deadbeefb10f32f2017-02-08 01:38:21 -0800892
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000893 // Provides a remote candidate to the ICE Agent.
894 // A copy of the |candidate| will be created and added to the remote
895 // description. So the caller of this method still has the ownership of the
896 // |candidate|.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000897 virtual bool AddIceCandidate(const IceCandidateInterface* candidate) = 0;
898
deadbeefb10f32f2017-02-08 01:38:21 -0800899 // Removes a group of remote candidates from the ICE agent. Needed mainly for
900 // continual gathering, to avoid an ever-growing list of candidates as
901 // networks come and go.
Honghai Zhang7fb69db2016-03-14 11:59:18 -0700902 virtual bool RemoveIceCandidates(
903 const std::vector<cricket::Candidate>& candidates) {
904 return false;
905 }
906
Taylor Brandstetter215fda72018-01-03 17:14:20 -0800907 // Register a metric observer (used by chromium). It's reference counted, and
908 // this method takes a reference. RegisterUMAObserver(nullptr) will release
909 // the reference.
910 // TODO(deadbeef): Take argument as scoped_refptr?
buildbot@webrtc.org1567b8c2014-05-08 19:54:16 +0000911 virtual void RegisterUMAObserver(UMAObserver* observer) = 0;
912
zstein4b979802017-06-02 14:37:37 -0700913 // 0 <= min <= current <= max should hold for set parameters.
914 struct BitrateParameters {
915 rtc::Optional<int> min_bitrate_bps;
916 rtc::Optional<int> current_bitrate_bps;
917 rtc::Optional<int> max_bitrate_bps;
918 };
919
920 // SetBitrate limits the bandwidth allocated for all RTP streams sent by
921 // this PeerConnection. Other limitations might affect these limits and
922 // are respected (for example "b=AS" in SDP).
923 //
924 // Setting |current_bitrate_bps| will reset the current bitrate estimate
925 // to the provided value.
zstein83dc6b62017-07-17 15:09:30 -0700926 virtual RTCError SetBitrate(const BitrateParameters& bitrate) = 0;
zstein4b979802017-06-02 14:37:37 -0700927
Alex Narest78609d52017-10-20 10:37:47 +0200928 // Sets current strategy. If not set default WebRTC allocator will be used.
929 // May be changed during an active session. The strategy
930 // ownership is passed with std::unique_ptr
931 // TODO(alexnarest): Make this pure virtual when tests will be updated
932 virtual void SetBitrateAllocationStrategy(
933 std::unique_ptr<rtc::BitrateAllocationStrategy>
934 bitrate_allocation_strategy) {}
935
henrika5f6bf242017-11-01 11:06:56 +0100936 // Enable/disable playout of received audio streams. Enabled by default. Note
937 // that even if playout is enabled, streams will only be played out if the
938 // appropriate SDP is also applied. Setting |playout| to false will stop
939 // playout of the underlying audio device but starts a task which will poll
940 // for audio data every 10ms to ensure that audio processing happens and the
941 // audio statistics are updated.
942 // TODO(henrika): deprecate and remove this.
943 virtual void SetAudioPlayout(bool playout) {}
944
945 // Enable/disable recording of transmitted audio streams. Enabled by default.
946 // Note that even if recording is enabled, streams will only be recorded if
947 // the appropriate SDP is also applied.
948 // TODO(henrika): deprecate and remove this.
949 virtual void SetAudioRecording(bool recording) {}
950
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000951 // Returns the current SignalingState.
952 virtual SignalingState signaling_state() = 0;
Taylor Brandstettercb423c42017-10-22 11:52:32 -0700953
954 // Returns the aggregate state of all ICE *and* DTLS transports.
955 // TODO(deadbeef): Implement "PeerConnectionState" according to the standard,
956 // to aggregate ICE+DTLS state, and change the scope of IceConnectionState to
957 // be just the ICE layer. See: crbug.com/webrtc/6145
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000958 virtual IceConnectionState ice_connection_state() = 0;
Taylor Brandstettercb423c42017-10-22 11:52:32 -0700959
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000960 virtual IceGatheringState ice_gathering_state() = 0;
961
ivoc14d5dbe2016-07-04 07:06:55 -0700962 // Starts RtcEventLog using existing file. Takes ownership of |file| and
963 // passes it on to Call, which will take the ownership. If the
964 // operation fails the file will be closed. The logging will stop
965 // automatically after 10 minutes have passed, or when the StopRtcEventLog
966 // function is called.
Elad Alon99c3fe52017-10-13 16:29:40 +0200967 // TODO(eladalon): Deprecate and remove this.
ivoc14d5dbe2016-07-04 07:06:55 -0700968 virtual bool StartRtcEventLog(rtc::PlatformFile file,
969 int64_t max_size_bytes) {
970 return false;
971 }
972
Elad Alon99c3fe52017-10-13 16:29:40 +0200973 // Start RtcEventLog using an existing output-sink. Takes ownership of
974 // |output| and passes it on to Call, which will take the ownership. If the
Bjorn Tereliusde939432017-11-20 17:38:14 +0100975 // operation fails the output will be closed and deallocated. The event log
976 // will send serialized events to the output object every |output_period_ms|.
977 virtual bool StartRtcEventLog(std::unique_ptr<RtcEventLogOutput> output,
978 int64_t output_period_ms) {
Elad Alon99c3fe52017-10-13 16:29:40 +0200979 return false;
980 }
981
ivoc14d5dbe2016-07-04 07:06:55 -0700982 // Stops logging the RtcEventLog.
983 // TODO(ivoc): Make this pure virtual when Chrome is updated.
984 virtual void StopRtcEventLog() {}
985
deadbeefb10f32f2017-02-08 01:38:21 -0800986 // Terminates all media, closes the transports, and in general releases any
987 // resources used by the PeerConnection. This is an irreversible operation.
deadbeefd07061c2017-04-20 13:19:00 -0700988 //
989 // Note that after this method completes, the PeerConnection will no longer
990 // use the PeerConnectionObserver interface passed in on construction, and
991 // thus the observer object can be safely destroyed.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000992 virtual void Close() = 0;
993
994 protected:
995 // Dtor protected as objects shouldn't be deleted via this interface.
996 ~PeerConnectionInterface() {}
997};
998
deadbeefb10f32f2017-02-08 01:38:21 -0800999// PeerConnection callback interface, used for RTCPeerConnection events.
1000// Application should implement these methods.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001001class PeerConnectionObserver {
1002 public:
Sami Kalliomäki02879f92018-01-11 10:02:19 +01001003 virtual ~PeerConnectionObserver() = default;
1004
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001005 // Triggered when the SignalingState changed.
1006 virtual void OnSignalingChange(
perkjdfb769d2016-02-09 03:09:43 -08001007 PeerConnectionInterface::SignalingState new_state) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001008
1009 // Triggered when media is received on a new stream from remote peer.
Steve Anton772eb212018-01-16 10:11:06 -08001010 virtual void OnAddStream(rtc::scoped_refptr<MediaStreamInterface> stream) {}
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001011
1012 // Triggered when a remote peer close a stream.
Steve Anton772eb212018-01-16 10:11:06 -08001013 // Deprecated: This callback will no longer be fired with Unified Plan
1014 // semantics.
1015 virtual void OnRemoveStream(rtc::scoped_refptr<MediaStreamInterface> stream) {
1016 }
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001017
Taylor Brandstetter98cde262016-05-31 13:02:21 -07001018 // Triggered when a remote peer opens a data channel.
1019 virtual void OnDataChannel(
nisse7f067662017-03-08 06:59:45 -08001020 rtc::scoped_refptr<DataChannelInterface> data_channel) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001021
Taylor Brandstetter98cde262016-05-31 13:02:21 -07001022 // Triggered when renegotiation is needed. For example, an ICE restart
1023 // has begun.
fischman@webrtc.orgd7568a02014-01-13 22:04:12 +00001024 virtual void OnRenegotiationNeeded() = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001025
Taylor Brandstetter98cde262016-05-31 13:02:21 -07001026 // Called any time the IceConnectionState changes.
deadbeefb10f32f2017-02-08 01:38:21 -08001027 //
1028 // Note that our ICE states lag behind the standard slightly. The most
1029 // notable differences include the fact that "failed" occurs after 15
1030 // seconds, not 30, and this actually represents a combination ICE + DTLS
1031 // state, so it may be "failed" if DTLS fails while ICE succeeds.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001032 virtual void OnIceConnectionChange(
perkjdfb769d2016-02-09 03:09:43 -08001033 PeerConnectionInterface::IceConnectionState new_state) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001034
Taylor Brandstetter98cde262016-05-31 13:02:21 -07001035 // Called any time the IceGatheringState changes.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001036 virtual void OnIceGatheringChange(
perkjdfb769d2016-02-09 03:09:43 -08001037 PeerConnectionInterface::IceGatheringState new_state) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001038
Taylor Brandstetter98cde262016-05-31 13:02:21 -07001039 // A new ICE candidate has been gathered.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001040 virtual void OnIceCandidate(const IceCandidateInterface* candidate) = 0;
1041
Honghai Zhang7fb69db2016-03-14 11:59:18 -07001042 // Ice candidates have been removed.
1043 // TODO(honghaiz): Make this a pure virtual method when all its subclasses
1044 // implement it.
1045 virtual void OnIceCandidatesRemoved(
1046 const std::vector<cricket::Candidate>& candidates) {}
1047
Peter Thatcher54360512015-07-08 11:08:35 -07001048 // Called when the ICE connection receiving status changes.
1049 virtual void OnIceConnectionReceivingChange(bool receiving) {}
1050
Henrik Boström933d8b02017-10-10 10:05:16 -07001051 // This is called when a receiver and its track is created.
1052 // TODO(zhihuang): Make this pure virtual when all subclasses implement it.
Steve Anton8b815cd2018-02-16 16:14:42 -08001053 // Note: This is called with both Plan B and Unified Plan semantics. Unified
1054 // Plan users should prefer OnTrack, OnAddTrack is only called as backwards
1055 // compatibility (and is called in the exact same situations as OnTrack).
zhihuang81c3a032016-11-17 12:06:24 -08001056 virtual void OnAddTrack(
1057 rtc::scoped_refptr<RtpReceiverInterface> receiver,
zhihuangc63b8942016-12-02 15:41:10 -08001058 const std::vector<rtc::scoped_refptr<MediaStreamInterface>>& streams) {}
zhihuang81c3a032016-11-17 12:06:24 -08001059
Steve Anton8b815cd2018-02-16 16:14:42 -08001060 // This is called when signaling indicates a transceiver will be receiving
1061 // media from the remote endpoint. This is fired during a call to
1062 // SetRemoteDescription. The receiving track can be accessed by:
1063 // |transceiver->receiver()->track()| and its associated streams by
1064 // |transceiver->receiver()->streams()|.
1065 // Note: This will only be called if Unified Plan semantics are specified.
1066 // This behavior is specified in section 2.2.8.2.5 of the "Set the
1067 // RTCSessionDescription" algorithm:
1068 // https://w3c.github.io/webrtc-pc/#set-description
1069 virtual void OnTrack(
1070 rtc::scoped_refptr<RtpTransceiverInterface> transceiver) {}
1071
Henrik Boström933d8b02017-10-10 10:05:16 -07001072 // TODO(hbos,deadbeef): Add |OnAssociatedStreamsUpdated| with |receiver| and
1073 // |streams| as arguments. This should be called when an existing receiver its
1074 // associated streams updated. https://crbug.com/webrtc/8315
1075 // This may be blocked on supporting multiple streams per sender or else
1076 // this may count as the removal and addition of a track?
1077 // https://crbug.com/webrtc/7932
1078
1079 // Called when a receiver is completely removed. This is current (Plan B SDP)
1080 // behavior that occurs when processing the removal of a remote track, and is
1081 // called when the receiver is removed and the track is muted. When Unified
1082 // Plan SDP is supported, transceivers can change direction (and receivers
Steve Anton8b815cd2018-02-16 16:14:42 -08001083 // stopped) but receivers are never removed, so this is never called.
Henrik Boström933d8b02017-10-10 10:05:16 -07001084 // https://w3c.github.io/webrtc-pc/#process-remote-track-removal
1085 // TODO(hbos,deadbeef): When Unified Plan SDP is supported and receivers are
1086 // no longer removed, deprecate and remove this callback.
1087 // TODO(hbos,deadbeef): Make pure virtual when all subclasses implement it.
1088 virtual void OnRemoveTrack(
1089 rtc::scoped_refptr<RtpReceiverInterface> receiver) {}
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001090};
1091
deadbeefb10f32f2017-02-08 01:38:21 -08001092// PeerConnectionFactoryInterface is the factory interface used for creating
1093// PeerConnection, MediaStream and MediaStreamTrack objects.
1094//
1095// The simplest method for obtaiing one, CreatePeerConnectionFactory will
1096// create the required libjingle threads, socket and network manager factory
1097// classes for networking if none are provided, though it requires that the
1098// application runs a message loop on the thread that called the method (see
1099// explanation below)
1100//
1101// If an application decides to provide its own threads and/or implementation
1102// of networking classes, it should use the alternate
1103// CreatePeerConnectionFactory method which accepts threads as input, and use
1104// the CreatePeerConnection version that takes a PortAllocator as an argument.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +00001105class PeerConnectionFactoryInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001106 public:
wu@webrtc.org97077a32013-10-25 21:18:33 +00001107 class Options {
1108 public:
deadbeefb10f32f2017-02-08 01:38:21 -08001109 Options() : crypto_options(rtc::CryptoOptions::NoGcm()) {}
1110
1111 // If set to true, created PeerConnections won't enforce any SRTP
1112 // requirement, allowing unsecured media. Should only be used for
1113 // testing/debugging.
1114 bool disable_encryption = false;
1115
1116 // Deprecated. The only effect of setting this to true is that
1117 // CreateDataChannel will fail, which is not that useful.
1118 bool disable_sctp_data_channels = false;
1119
1120 // If set to true, any platform-supported network monitoring capability
1121 // won't be used, and instead networks will only be updated via polling.
1122 //
1123 // This only has an effect if a PeerConnection is created with the default
1124 // PortAllocator implementation.
1125 bool disable_network_monitor = false;
phoglund@webrtc.org006521d2015-02-12 09:23:59 +00001126
1127 // Sets the network types to ignore. For instance, calling this with
1128 // ADAPTER_TYPE_ETHERNET | ADAPTER_TYPE_LOOPBACK will ignore Ethernet and
1129 // loopback interfaces.
deadbeefb10f32f2017-02-08 01:38:21 -08001130 int network_ignore_mask = rtc::kDefaultNetworkIgnoreMask;
Joachim Bauch04e5b492015-05-29 09:40:39 +02001131
1132 // Sets the maximum supported protocol version. The highest version
1133 // supported by both ends will be used for the connection, i.e. if one
1134 // party supports DTLS 1.0 and the other DTLS 1.2, DTLS 1.0 will be used.
deadbeefb10f32f2017-02-08 01:38:21 -08001135 rtc::SSLProtocolVersion ssl_max_version = rtc::SSL_PROTOCOL_DTLS_12;
jbauchcb560652016-08-04 05:20:32 -07001136
1137 // Sets crypto related options, e.g. enabled cipher suites.
1138 rtc::CryptoOptions crypto_options;
wu@webrtc.org97077a32013-10-25 21:18:33 +00001139 };
1140
deadbeef7914b8c2017-04-21 03:23:33 -07001141 // Set the options to be used for subsequently created PeerConnections.
wu@webrtc.org97077a32013-10-25 21:18:33 +00001142 virtual void SetOptions(const Options& options) = 0;
buildbot@webrtc.org41451d42014-05-03 05:39:45 +00001143
deadbeefd07061c2017-04-20 13:19:00 -07001144 // |allocator| and |cert_generator| may be null, in which case default
1145 // implementations will be used.
1146 //
1147 // |observer| must not be null.
1148 //
1149 // Note that this method does not take ownership of |observer|; it's the
1150 // responsibility of the caller to delete it. It can be safely deleted after
1151 // Close has been called on the returned PeerConnection, which ensures no
1152 // more observer callbacks will be invoked.
deadbeef41b07982015-12-01 15:01:24 -08001153 virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection(
1154 const PeerConnectionInterface::RTCConfiguration& configuration,
kwibergd1fe2812016-04-27 06:47:29 -07001155 std::unique_ptr<cricket::PortAllocator> allocator,
Henrik Boströmd03c23b2016-06-01 11:44:18 +02001156 std::unique_ptr<rtc::RTCCertificateGeneratorInterface> cert_generator,
hbosd7973cc2016-05-27 06:08:53 -07001157 PeerConnectionObserver* observer) = 0;
buildbot@webrtc.org41451d42014-05-03 05:39:45 +00001158
deadbeefb10f32f2017-02-08 01:38:21 -08001159 // Deprecated; should use RTCConfiguration for everything that previously
1160 // used constraints.
htaa2a49d92016-03-04 02:51:39 -08001161 virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection(
1162 const PeerConnectionInterface::RTCConfiguration& configuration,
deadbeefb10f32f2017-02-08 01:38:21 -08001163 const MediaConstraintsInterface* constraints,
kwibergd1fe2812016-04-27 06:47:29 -07001164 std::unique_ptr<cricket::PortAllocator> allocator,
Henrik Boströmd03c23b2016-06-01 11:44:18 +02001165 std::unique_ptr<rtc::RTCCertificateGeneratorInterface> cert_generator,
hbosd7973cc2016-05-27 06:08:53 -07001166 PeerConnectionObserver* observer) = 0;
htaa2a49d92016-03-04 02:51:39 -08001167
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +00001168 virtual rtc::scoped_refptr<MediaStreamInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001169 CreateLocalMediaStream(const std::string& label) = 0;
1170
deadbeefe814a0d2017-02-25 18:15:09 -08001171 // Creates an AudioSourceInterface.
deadbeefb10f32f2017-02-08 01:38:21 -08001172 // |options| decides audio processing settings.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +00001173 virtual rtc::scoped_refptr<AudioSourceInterface> CreateAudioSource(
htaa2a49d92016-03-04 02:51:39 -08001174 const cricket::AudioOptions& options) = 0;
1175 // Deprecated - use version above.
deadbeeffe0fd412017-01-13 11:47:56 -08001176 // Can use CopyConstraintsIntoAudioOptions to bridge the gap.
htaa2a49d92016-03-04 02:51:39 -08001177 virtual rtc::scoped_refptr<AudioSourceInterface> CreateAudioSource(
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001178 const MediaConstraintsInterface* constraints) = 0;
1179
deadbeef39e14da2017-02-13 09:49:58 -08001180 // Creates a VideoTrackSourceInterface from |capturer|.
1181 // TODO(deadbeef): We should aim to remove cricket::VideoCapturer from the
1182 // API. It's mainly used as a wrapper around webrtc's provided
1183 // platform-specific capturers, but these should be refactored to use
1184 // VideoTrackSourceInterface directly.
deadbeef112b2e92017-02-10 20:13:37 -08001185 // TODO(deadbeef): Make pure virtual once downstream mock PC factory classes
1186 // are updated.
perkja3ede6c2016-03-08 01:27:48 +01001187 virtual rtc::scoped_refptr<VideoTrackSourceInterface> CreateVideoSource(
deadbeef112b2e92017-02-10 20:13:37 -08001188 std::unique_ptr<cricket::VideoCapturer> capturer) {
1189 return nullptr;
1190 }
1191
htaa2a49d92016-03-04 02:51:39 -08001192 // A video source creator that allows selection of resolution and frame rate.
deadbeef8d60a942017-02-27 14:47:33 -08001193 // |constraints| decides video resolution and frame rate but can be null.
1194 // In the null case, use the version above.
deadbeef112b2e92017-02-10 20:13:37 -08001195 //
1196 // |constraints| is only used for the invocation of this method, and can
1197 // safely be destroyed afterwards.
1198 virtual rtc::scoped_refptr<VideoTrackSourceInterface> CreateVideoSource(
1199 std::unique_ptr<cricket::VideoCapturer> capturer,
1200 const MediaConstraintsInterface* constraints) {
1201 return nullptr;
1202 }
1203
1204 // Deprecated; please use the versions that take unique_ptrs above.
1205 // TODO(deadbeef): Remove these once safe to do so.
1206 virtual rtc::scoped_refptr<VideoTrackSourceInterface> CreateVideoSource(
1207 cricket::VideoCapturer* capturer) {
1208 return CreateVideoSource(std::unique_ptr<cricket::VideoCapturer>(capturer));
1209 }
perkja3ede6c2016-03-08 01:27:48 +01001210 virtual rtc::scoped_refptr<VideoTrackSourceInterface> CreateVideoSource(
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001211 cricket::VideoCapturer* capturer,
deadbeef112b2e92017-02-10 20:13:37 -08001212 const MediaConstraintsInterface* constraints) {
1213 return CreateVideoSource(std::unique_ptr<cricket::VideoCapturer>(capturer),
1214 constraints);
1215 }
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001216
1217 // Creates a new local VideoTrack. The same |source| can be used in several
1218 // tracks.
perkja3ede6c2016-03-08 01:27:48 +01001219 virtual rtc::scoped_refptr<VideoTrackInterface> CreateVideoTrack(
1220 const std::string& label,
1221 VideoTrackSourceInterface* source) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001222
deadbeef8d60a942017-02-27 14:47:33 -08001223 // Creates an new AudioTrack. At the moment |source| can be null.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +00001224 virtual rtc::scoped_refptr<AudioTrackInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001225 CreateAudioTrack(const std::string& label,
1226 AudioSourceInterface* source) = 0;
1227
wu@webrtc.orga9890802013-12-13 00:21:03 +00001228 // Starts AEC dump using existing file. Takes ownership of |file| and passes
1229 // it on to VoiceEngine (via other objects) immediately, which will take
wu@webrtc.orga8910d22014-01-23 22:12:45 +00001230 // the ownerhip. If the operation fails, the file will be closed.
ivocd66b44d2016-01-15 03:06:36 -08001231 // A maximum file size in bytes can be specified. When the file size limit is
1232 // reached, logging is stopped automatically. If max_size_bytes is set to a
1233 // value <= 0, no limit will be used, and logging will continue until the
1234 // StopAecDump function is called.
1235 virtual bool StartAecDump(rtc::PlatformFile file, int64_t max_size_bytes) = 0;
wu@webrtc.orga9890802013-12-13 00:21:03 +00001236
ivoc797ef122015-10-22 03:25:41 -07001237 // Stops logging the AEC dump.
1238 virtual void StopAecDump() = 0;
1239
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001240 protected:
1241 // Dtor and ctor protected as objects shouldn't be created or deleted via
1242 // this interface.
1243 PeerConnectionFactoryInterface() {}
1244 ~PeerConnectionFactoryInterface() {} // NOLINT
1245};
1246
1247// Create a new instance of PeerConnectionFactoryInterface.
Taylor Brandstettera8415fe2016-03-23 10:38:07 -07001248//
1249// This method relies on the thread it's called on as the "signaling thread"
1250// for the PeerConnectionFactory it creates.
1251//
1252// As such, if the current thread is not already running an rtc::Thread message
1253// loop, an application using this method must eventually either call
1254// rtc::Thread::Current()->Run(), or call
1255// rtc::Thread::Current()->ProcessMessages() within the application's own
1256// message loop.
kwiberg1e4e8cb2017-01-31 01:48:08 -08001257rtc::scoped_refptr<PeerConnectionFactoryInterface> CreatePeerConnectionFactory(
1258 rtc::scoped_refptr<AudioEncoderFactory> audio_encoder_factory,
1259 rtc::scoped_refptr<AudioDecoderFactory> audio_decoder_factory);
1260
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001261// Create a new instance of PeerConnectionFactoryInterface.
Taylor Brandstettera8415fe2016-03-23 10:38:07 -07001262//
danilchape9021a32016-05-17 01:52:02 -07001263// |network_thread|, |worker_thread| and |signaling_thread| are
1264// the only mandatory parameters.
Taylor Brandstettera8415fe2016-03-23 10:38:07 -07001265//
deadbeefb10f32f2017-02-08 01:38:21 -08001266// If non-null, a reference is added to |default_adm|, and ownership of
1267// |video_encoder_factory| and |video_decoder_factory| is transferred to the
1268// returned factory.
1269// TODO(deadbeef): Use rtc::scoped_refptr<> and std::unique_ptr<> to make this
1270// ownership transfer and ref counting more obvious.
danilchape9021a32016-05-17 01:52:02 -07001271rtc::scoped_refptr<PeerConnectionFactoryInterface> CreatePeerConnectionFactory(
1272 rtc::Thread* network_thread,
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +00001273 rtc::Thread* worker_thread,
1274 rtc::Thread* signaling_thread,
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001275 AudioDeviceModule* default_adm,
kwiberg1e4e8cb2017-01-31 01:48:08 -08001276 rtc::scoped_refptr<AudioEncoderFactory> audio_encoder_factory,
1277 rtc::scoped_refptr<AudioDecoderFactory> audio_decoder_factory,
1278 cricket::WebRtcVideoEncoderFactory* video_encoder_factory,
1279 cricket::WebRtcVideoDecoderFactory* video_decoder_factory);
1280
peah17675ce2017-06-30 07:24:04 -07001281// Create a new instance of PeerConnectionFactoryInterface with optional
1282// external audio mixed and audio processing modules.
1283//
1284// If |audio_mixer| is null, an internal audio mixer will be created and used.
1285// If |audio_processing| is null, an internal audio processing module will be
1286// created and used.
1287rtc::scoped_refptr<PeerConnectionFactoryInterface> CreatePeerConnectionFactory(
1288 rtc::Thread* network_thread,
1289 rtc::Thread* worker_thread,
1290 rtc::Thread* signaling_thread,
1291 AudioDeviceModule* default_adm,
1292 rtc::scoped_refptr<AudioEncoderFactory> audio_encoder_factory,
1293 rtc::scoped_refptr<AudioDecoderFactory> audio_decoder_factory,
1294 cricket::WebRtcVideoEncoderFactory* video_encoder_factory,
1295 cricket::WebRtcVideoDecoderFactory* video_decoder_factory,
1296 rtc::scoped_refptr<AudioMixer> audio_mixer,
1297 rtc::scoped_refptr<AudioProcessing> audio_processing);
1298
Magnus Jedvert58b03162017-09-15 19:02:47 +02001299// Create a new instance of PeerConnectionFactoryInterface with optional video
1300// codec factories. These video factories represents all video codecs, i.e. no
1301// extra internal video codecs will be added.
1302rtc::scoped_refptr<PeerConnectionFactoryInterface> CreatePeerConnectionFactory(
1303 rtc::Thread* network_thread,
1304 rtc::Thread* worker_thread,
1305 rtc::Thread* signaling_thread,
1306 rtc::scoped_refptr<AudioDeviceModule> default_adm,
1307 rtc::scoped_refptr<AudioEncoderFactory> audio_encoder_factory,
1308 rtc::scoped_refptr<AudioDecoderFactory> audio_decoder_factory,
1309 std::unique_ptr<VideoEncoderFactory> video_encoder_factory,
1310 std::unique_ptr<VideoDecoderFactory> video_decoder_factory,
1311 rtc::scoped_refptr<AudioMixer> audio_mixer,
1312 rtc::scoped_refptr<AudioProcessing> audio_processing);
1313
gyzhou95aa9642016-12-13 14:06:26 -08001314// Create a new instance of PeerConnectionFactoryInterface with external audio
1315// mixer.
1316//
1317// If |audio_mixer| is null, an internal audio mixer will be created and used.
1318rtc::scoped_refptr<PeerConnectionFactoryInterface>
1319CreatePeerConnectionFactoryWithAudioMixer(
1320 rtc::Thread* network_thread,
1321 rtc::Thread* worker_thread,
1322 rtc::Thread* signaling_thread,
1323 AudioDeviceModule* default_adm,
kwiberg1e4e8cb2017-01-31 01:48:08 -08001324 rtc::scoped_refptr<AudioEncoderFactory> audio_encoder_factory,
1325 rtc::scoped_refptr<AudioDecoderFactory> audio_decoder_factory,
1326 cricket::WebRtcVideoEncoderFactory* video_encoder_factory,
1327 cricket::WebRtcVideoDecoderFactory* video_decoder_factory,
1328 rtc::scoped_refptr<AudioMixer> audio_mixer);
1329
danilchape9021a32016-05-17 01:52:02 -07001330// Create a new instance of PeerConnectionFactoryInterface.
1331// Same thread is used as worker and network thread.
danilchape9021a32016-05-17 01:52:02 -07001332inline rtc::scoped_refptr<PeerConnectionFactoryInterface>
1333CreatePeerConnectionFactory(
1334 rtc::Thread* worker_and_network_thread,
1335 rtc::Thread* signaling_thread,
1336 AudioDeviceModule* default_adm,
kwiberg1e4e8cb2017-01-31 01:48:08 -08001337 rtc::scoped_refptr<AudioEncoderFactory> audio_encoder_factory,
1338 rtc::scoped_refptr<AudioDecoderFactory> audio_decoder_factory,
1339 cricket::WebRtcVideoEncoderFactory* video_encoder_factory,
1340 cricket::WebRtcVideoDecoderFactory* video_decoder_factory) {
1341 return CreatePeerConnectionFactory(
1342 worker_and_network_thread, worker_and_network_thread, signaling_thread,
1343 default_adm, audio_encoder_factory, audio_decoder_factory,
1344 video_encoder_factory, video_decoder_factory);
1345}
1346
zhihuang38ede132017-06-15 12:52:32 -07001347// This is a lower-level version of the CreatePeerConnectionFactory functions
1348// above. It's implemented in the "peerconnection" build target, whereas the
1349// above methods are only implemented in the broader "libjingle_peerconnection"
1350// build target, which pulls in the implementations of every module webrtc may
1351// use.
1352//
1353// If an application knows it will only require certain modules, it can reduce
1354// webrtc's impact on its binary size by depending only on the "peerconnection"
1355// target and the modules the application requires, using
1356// CreateModularPeerConnectionFactory instead of one of the
1357// CreatePeerConnectionFactory methods above. For example, if an application
1358// only uses WebRTC for audio, it can pass in null pointers for the
1359// video-specific interfaces, and omit the corresponding modules from its
1360// build.
1361//
1362// If |network_thread| or |worker_thread| are null, the PeerConnectionFactory
1363// will create the necessary thread internally. If |signaling_thread| is null,
1364// the PeerConnectionFactory will use the thread on which this method is called
1365// as the signaling thread, wrapping it in an rtc::Thread object if needed.
1366//
1367// If non-null, a reference is added to |default_adm|, and ownership of
1368// |video_encoder_factory| and |video_decoder_factory| is transferred to the
1369// returned factory.
1370//
peaha9cc40b2017-06-29 08:32:09 -07001371// If |audio_mixer| is null, an internal audio mixer will be created and used.
1372//
zhihuang38ede132017-06-15 12:52:32 -07001373// TODO(deadbeef): Use rtc::scoped_refptr<> and std::unique_ptr<> to make this
1374// ownership transfer and ref counting more obvious.
1375//
1376// TODO(deadbeef): Encapsulate these modules in a struct, so that when a new
1377// module is inevitably exposed, we can just add a field to the struct instead
1378// of adding a whole new CreateModularPeerConnectionFactory overload.
1379rtc::scoped_refptr<PeerConnectionFactoryInterface>
1380CreateModularPeerConnectionFactory(
1381 rtc::Thread* network_thread,
1382 rtc::Thread* worker_thread,
1383 rtc::Thread* signaling_thread,
zhihuang38ede132017-06-15 12:52:32 -07001384 std::unique_ptr<cricket::MediaEngineInterface> media_engine,
1385 std::unique_ptr<CallFactoryInterface> call_factory,
1386 std::unique_ptr<RtcEventLogFactoryInterface> event_log_factory);
1387
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001388} // namespace webrtc
1389
Mirko Bonadei92ea95e2017-09-15 06:47:31 +02001390#endif // API_PEERCONNECTIONINTERFACE_H_