blob: c6e5a25b5b26da358c96ddb22f77e35c67a94e81 [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
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
kwibergd1fe2812016-04-27 06:47:29 -070070#include <memory>
henrike@webrtc.org28e20752013-07-10 00:45:36 +000071#include <string>
kwiberg0eb15ed2015-12-17 03:04:15 -080072#include <utility>
henrike@webrtc.org28e20752013-07-10 00:45:36 +000073#include <vector>
74
Zach Steine20867f2018-08-02 13:20:15 -070075#include "api/asyncresolverfactory.h"
Niels Möllerd377f042018-02-13 15:03:43 +010076#include "api/audio/audio_mixer.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020077#include "api/audio_codecs/audio_decoder_factory.h"
78#include "api/audio_codecs/audio_encoder_factory.h"
Niels Möllera6fe2612018-01-19 11:28:54 +010079#include "api/audio_options.h"
Niels Möller8366e172018-02-14 12:20:13 +010080#include "api/call/callfactoryinterface.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020081#include "api/datachannelinterface.h"
82#include "api/dtmfsenderinterface.h"
Ying Wang0dd1b0a2018-02-20 12:50:27 +010083#include "api/fec_controller.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020084#include "api/jsep.h"
85#include "api/mediastreaminterface.h"
86#include "api/rtcerror.h"
Elad Alon99c3fe52017-10-13 16:29:40 +020087#include "api/rtceventlogoutput.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020088#include "api/rtpreceiverinterface.h"
89#include "api/rtpsenderinterface.h"
Steve Anton9158ef62017-11-27 13:01:52 -080090#include "api/rtptransceiverinterface.h"
Henrik Boström31638672017-11-23 17:48:32 +010091#include "api/setremotedescriptionobserverinterface.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020092#include "api/stats/rtcstatscollectorcallback.h"
93#include "api/statstypes.h"
Niels Möller0c4f7be2018-05-07 14:01:37 +020094#include "api/transport/bitrate_settings.h"
Sebastian Janssondfce03a2018-05-18 18:05:10 +020095#include "api/transport/network_control.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.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200106#include "media/base/mediaengine.h" // nogncheck
Niels Möller8366e172018-02-14 12:20:13 +0100107#include "p2p/base/portallocator.h" // nogncheck
108// TODO(nisse): The interface for bitrate allocation strategy belongs in api/.
109#include "rtc_base/bitrateallocationstrategy.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +0200110#include "rtc_base/network.h"
Niels Möller8366e172018-02-14 12:20:13 +0100111#include "rtc_base/platform_file.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +0200112#include "rtc_base/rtccertificate.h"
113#include "rtc_base/rtccertificategenerator.h"
114#include "rtc_base/socketaddress.h"
Diogo Real4f085432018-09-11 16:00:22 -0700115#include "rtc_base/ssladapter.h"
Benjamin Wrightd6f86e82018-05-08 13:12:25 -0700116#include "rtc_base/sslcertificate.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +0200117#include "rtc_base/sslstreamadapter.h"
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000118
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000119namespace rtc {
jiayl@webrtc.org61e00b02015-03-04 22:17:38 +0000120class SSLIdentity;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000121class Thread;
Yves Gerey665174f2018-06-19 15:03:05 +0200122} // namespace rtc
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000123
124namespace cricket {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000125class WebRtcVideoDecoderFactory;
126class WebRtcVideoEncoderFactory;
Yves Gerey665174f2018-06-19 15:03:05 +0200127} // namespace cricket
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000128
129namespace webrtc {
130class AudioDeviceModule;
gyzhou95aa9642016-12-13 14:06:26 -0800131class AudioMixer;
Niels Möller8366e172018-02-14 12:20:13 +0100132class AudioProcessing;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000133class MediaConstraintsInterface;
Magnus Jedvert58b03162017-09-15 19:02:47 +0200134class VideoDecoderFactory;
135class VideoEncoderFactory;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000136
137// MediaStream container interface.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000138class StreamCollectionInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000139 public:
140 // TODO(ronghuawu): Update the function names to c++ style, e.g. find -> Find.
141 virtual size_t count() = 0;
142 virtual MediaStreamInterface* at(size_t index) = 0;
143 virtual MediaStreamInterface* find(const std::string& label) = 0;
Yves Gerey665174f2018-06-19 15:03:05 +0200144 virtual MediaStreamTrackInterface* FindAudioTrack(const std::string& id) = 0;
145 virtual MediaStreamTrackInterface* FindVideoTrack(const std::string& id) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000146
147 protected:
148 // Dtor protected as objects shouldn't be deleted via this interface.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200149 ~StreamCollectionInterface() override = default;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000150};
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:
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200157 ~StatsObserver() override = default;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000158};
159
Steve Anton3acffc32018-04-12 17:21:03 -0700160enum class SdpSemantics { kPlanB, kUnifiedPlan };
Steve Anton79e79602017-11-20 10:25:56 -0800161
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000162class PeerConnectionInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000163 public:
Steve Antonab6ea6b2018-02-26 14:23:09 -0800164 // See https://w3c.github.io/webrtc-pc/#state-definitions
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000165 enum SignalingState {
166 kStable,
167 kHaveLocalOffer,
168 kHaveLocalPrAnswer,
169 kHaveRemoteOffer,
170 kHaveRemotePrAnswer,
171 kClosed,
172 };
173
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000174 enum IceGatheringState {
175 kIceGatheringNew,
176 kIceGatheringGathering,
177 kIceGatheringComplete
178 };
179
180 enum IceConnectionState {
181 kIceConnectionNew,
182 kIceConnectionChecking,
183 kIceConnectionConnected,
184 kIceConnectionCompleted,
185 kIceConnectionFailed,
186 kIceConnectionDisconnected,
187 kIceConnectionClosed,
Guo-wei Shieh3d564c12015-08-19 16:51:15 -0700188 kIceConnectionMax,
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000189 };
190
Diogo Real4f085432018-09-11 16:00:22 -0700191 // Deprecated. TODO(diogor, webrtc:9673): Remove from API.
hnsl04833622017-01-09 08:35:45 -0800192 // TLS certificate policy.
193 enum TlsCertPolicy {
194 // For TLS based protocols, ensure the connection is secure by not
195 // circumventing certificate validation.
196 kTlsCertPolicySecure,
197 // For TLS based protocols, disregard security completely by skipping
198 // certificate validation. This is insecure and should never be used unless
199 // security is irrelevant in that particular context.
200 kTlsCertPolicyInsecureNoCheck,
201 };
202
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000203 struct IceServer {
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200204 IceServer();
205 IceServer(const IceServer&);
206 ~IceServer();
207
Joachim Bauch7c4e7452015-05-28 23:06:30 +0200208 // TODO(jbauch): Remove uri when all code using it has switched to urls.
Emad Omaradab1d2d2017-06-16 15:43:11 -0700209 // List of URIs associated with this server. Valid formats are described
210 // in RFC7064 and RFC7065, and more may be added in the future. The "host"
211 // part of the URI may contain either an IP address or a hostname.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000212 std::string uri;
Joachim Bauch7c4e7452015-05-28 23:06:30 +0200213 std::vector<std::string> urls;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000214 std::string username;
215 std::string password;
Diogo Real4f085432018-09-11 16:00:22 -0700216 // Deprecated. rtc::SSLConfig should be used instead.
hnsl04833622017-01-09 08:35:45 -0800217 TlsCertPolicy tls_cert_policy = kTlsCertPolicySecure;
Emad Omaradab1d2d2017-06-16 15:43:11 -0700218 // If the URIs in |urls| only contain IP addresses, this field can be used
219 // to indicate the hostname, which may be necessary for TLS (using the SNI
220 // extension). If |urls| itself contains the hostname, this isn't
221 // necessary.
222 std::string hostname;
Diogo Real4f085432018-09-11 16:00:22 -0700223 // Deprecated. rtc::SSLConfig should be used instead.
Diogo Real1dca9d52017-08-29 12:18:32 -0700224 // List of protocols to be used in the TLS ALPN extension.
225 std::vector<std::string> tls_alpn_protocols;
Diogo Real4f085432018-09-11 16:00:22 -0700226 // Deprecated. rtc::SSLConfig should be used instead.
Diogo Real7bd1f1b2017-09-08 12:50:41 -0700227 // List of elliptic curves to be used in the TLS elliptic curves extension.
228 std::vector<std::string> tls_elliptic_curves;
Diogo Real4f085432018-09-11 16:00:22 -0700229 // SSL configuration options for any SSL/TLS connections to this IceServer.
230 rtc::SSLConfig ssl_config;
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 &&
Diogo Real4f085432018-09-11 16:00:22 -0700237 tls_elliptic_curves == o.tls_elliptic_curves &&
238 ssl_config == o.ssl_config;
deadbeefd1a38b52016-12-10 13:15:33 -0800239 }
240 bool operator!=(const IceServer& o) const { return !(*this == o); }
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000241 };
242 typedef std::vector<IceServer> IceServers;
243
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000244 enum IceTransportsType {
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000245 // TODO(pthatcher): Rename these kTransporTypeXXX, but update
246 // Chromium at the same time.
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000247 kNone,
248 kRelay,
249 kNoHost,
250 kAll
251 };
252
Steve Antonab6ea6b2018-02-26 14:23:09 -0800253 // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-24#section-4.1.1
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000254 enum BundlePolicy {
255 kBundlePolicyBalanced,
256 kBundlePolicyMaxBundle,
257 kBundlePolicyMaxCompat
258 };
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000259
Steve Antonab6ea6b2018-02-26 14:23:09 -0800260 // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-24#section-4.1.1
Peter Thatcheraf55ccc2015-05-21 07:48:41 -0700261 enum RtcpMuxPolicy {
262 kRtcpMuxPolicyNegotiate,
263 kRtcpMuxPolicyRequire,
264 };
265
Jiayang Liucac1b382015-04-30 12:35:24 -0700266 enum TcpCandidatePolicy {
267 kTcpCandidatePolicyEnabled,
268 kTcpCandidatePolicyDisabled
269 };
270
honghaiz60347052016-05-31 18:29:12 -0700271 enum CandidateNetworkPolicy {
272 kCandidateNetworkPolicyAll,
273 kCandidateNetworkPolicyLowCost
274 };
275
Yves Gerey665174f2018-06-19 15:03:05 +0200276 enum ContinualGatheringPolicy { GATHER_ONCE, GATHER_CONTINUALLY };
honghaiz1f429e32015-09-28 07:57:34 -0700277
Honghai Zhangf7ddc062016-09-01 15:34:01 -0700278 enum class RTCConfigurationType {
279 // A configuration that is safer to use, despite not having the best
280 // performance. Currently this is the default configuration.
281 kSafe,
282 // An aggressive configuration that has better performance, although it
283 // may be riskier and may need extra support in the application.
284 kAggressive
285 };
286
Henrik Boström87713d02015-08-25 09:53:21 +0200287 // TODO(hbos): Change into class with private data and public getters.
nissec36b31b2016-04-11 23:25:29 -0700288 // TODO(nisse): In particular, accessing fields directly from an
289 // application is brittle, since the organization mirrors the
290 // organization of the implementation, which isn't stable. So we
291 // need getters and setters at least for fields which applications
292 // are interested in.
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000293 struct RTCConfiguration {
Niels Möller71bdda02016-03-31 12:59:59 +0200294 // This struct is subject to reorganization, both for naming
295 // consistency, and to group settings to match where they are used
296 // in the implementation. To do that, we need getter and setter
297 // methods for all settings which are of interest to applications,
298 // Chrome in particular.
299
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200300 RTCConfiguration();
301 RTCConfiguration(const RTCConfiguration&);
302 explicit RTCConfiguration(RTCConfigurationType type);
303 ~RTCConfiguration();
Honghai Zhangbfd398c2016-08-30 22:07:42 -0700304
deadbeef293e9262017-01-11 12:28:30 -0800305 bool operator==(const RTCConfiguration& o) const;
306 bool operator!=(const RTCConfiguration& o) const;
307
Niels Möller6539f692018-01-18 08:58:50 +0100308 bool dscp() const { return media_config.enable_dscp; }
nissec36b31b2016-04-11 23:25:29 -0700309 void set_dscp(bool enable) { media_config.enable_dscp = enable; }
Niels Möller71bdda02016-03-31 12:59:59 +0200310
Niels Möller6539f692018-01-18 08:58:50 +0100311 bool cpu_adaptation() const {
Niels Möller1d7ecd22018-01-18 15:25:12 +0100312 return media_config.video.enable_cpu_adaptation;
nissec36b31b2016-04-11 23:25:29 -0700313 }
Niels Möller71bdda02016-03-31 12:59:59 +0200314 void set_cpu_adaptation(bool enable) {
Niels Möller1d7ecd22018-01-18 15:25:12 +0100315 media_config.video.enable_cpu_adaptation = enable;
Niels Möller71bdda02016-03-31 12:59:59 +0200316 }
317
Niels Möller6539f692018-01-18 08:58:50 +0100318 bool suspend_below_min_bitrate() const {
nissec36b31b2016-04-11 23:25:29 -0700319 return media_config.video.suspend_below_min_bitrate;
320 }
Niels Möller71bdda02016-03-31 12:59:59 +0200321 void set_suspend_below_min_bitrate(bool enable) {
nissec36b31b2016-04-11 23:25:29 -0700322 media_config.video.suspend_below_min_bitrate = enable;
Niels Möller71bdda02016-03-31 12:59:59 +0200323 }
324
Niels Möller6539f692018-01-18 08:58:50 +0100325 bool prerenderer_smoothing() const {
Niels Möller1d7ecd22018-01-18 15:25:12 +0100326 return media_config.video.enable_prerenderer_smoothing;
nissec36b31b2016-04-11 23:25:29 -0700327 }
Niels Möller71bdda02016-03-31 12:59:59 +0200328 void set_prerenderer_smoothing(bool enable) {
Niels Möller1d7ecd22018-01-18 15:25:12 +0100329 media_config.video.enable_prerenderer_smoothing = enable;
Niels Möller71bdda02016-03-31 12:59:59 +0200330 }
331
Niels Möller6539f692018-01-18 08:58:50 +0100332 bool experiment_cpu_load_estimator() const {
333 return media_config.video.experiment_cpu_load_estimator;
334 }
335 void set_experiment_cpu_load_estimator(bool enable) {
336 media_config.video.experiment_cpu_load_estimator = enable;
337 }
Ilya Nikolaevskiy97b4ee52018-05-28 10:24:22 +0200338
honghaiz4edc39c2015-09-01 09:53:56 -0700339 static const int kUndefined = -1;
340 // Default maximum number of packets in the audio jitter buffer.
341 static const int kAudioJitterBufferMaxPackets = 50;
Honghai Zhangaecd9822016-09-02 16:58:17 -0700342 // ICE connection receiving timeout for aggressive configuration.
343 static const int kAggressiveIceConnectionReceivingTimeout = 1000;
deadbeefb10f32f2017-02-08 01:38:21 -0800344
345 ////////////////////////////////////////////////////////////////////////
346 // The below few fields mirror the standard RTCConfiguration dictionary:
Steve Antonab6ea6b2018-02-26 14:23:09 -0800347 // https://w3c.github.io/webrtc-pc/#rtcconfiguration-dictionary
deadbeefb10f32f2017-02-08 01:38:21 -0800348 ////////////////////////////////////////////////////////////////////////
349
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000350 // TODO(pthatcher): Rename this ice_servers, but update Chromium
351 // at the same time.
352 IceServers servers;
deadbeefb10f32f2017-02-08 01:38:21 -0800353 // TODO(pthatcher): Rename this ice_transport_type, but update
354 // Chromium at the same time.
355 IceTransportsType type = kAll;
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700356 BundlePolicy bundle_policy = kBundlePolicyBalanced;
zhihuang4dfb8ce2016-11-23 10:30:12 -0800357 RtcpMuxPolicy rtcp_mux_policy = kRtcpMuxPolicyRequire;
deadbeefb10f32f2017-02-08 01:38:21 -0800358 std::vector<rtc::scoped_refptr<rtc::RTCCertificate>> certificates;
359 int ice_candidate_pool_size = 0;
360
361 //////////////////////////////////////////////////////////////////////////
362 // The below fields correspond to constraints from the deprecated
363 // constraints interface for constructing a PeerConnection.
364 //
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200365 // absl::optional fields can be "missing", in which case the implementation
deadbeefb10f32f2017-02-08 01:38:21 -0800366 // default will be used.
367 //////////////////////////////////////////////////////////////////////////
368
369 // If set to true, don't gather IPv6 ICE candidates.
370 // TODO(deadbeef): Remove this? IPv6 support has long stopped being
371 // experimental
372 bool disable_ipv6 = false;
373
zhihuangb09b3f92017-03-07 14:40:51 -0800374 // If set to true, don't gather IPv6 ICE candidates on Wi-Fi.
375 // Only intended to be used on specific devices. Certain phones disable IPv6
376 // when the screen is turned off and it would be better to just disable the
377 // IPv6 ICE candidates on Wi-Fi in those cases.
378 bool disable_ipv6_on_wifi = false;
379
deadbeefd21eab32017-07-26 16:50:11 -0700380 // By default, the PeerConnection will use a limited number of IPv6 network
381 // interfaces, in order to avoid too many ICE candidate pairs being created
382 // and delaying ICE completion.
383 //
384 // Can be set to INT_MAX to effectively disable the limit.
385 int max_ipv6_networks = cricket::kDefaultMaxIPv6Networks;
386
Daniel Lazarenko2870b0a2018-01-25 10:30:22 +0100387 // Exclude link-local network interfaces
388 // from considertaion for gathering ICE candidates.
389 bool disable_link_local_networks = false;
390
deadbeefb10f32f2017-02-08 01:38:21 -0800391 // If set to true, use RTP data channels instead of SCTP.
392 // TODO(deadbeef): Remove this. We no longer commit to supporting RTP data
393 // channels, though some applications are still working on moving off of
394 // them.
395 bool enable_rtp_data_channel = false;
396
397 // Minimum bitrate at which screencast video tracks will be encoded at.
398 // This means adding padding bits up to this bitrate, which can help
399 // when switching from a static scene to one with motion.
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200400 absl::optional<int> screencast_min_bitrate;
deadbeefb10f32f2017-02-08 01:38:21 -0800401
402 // Use new combined audio/video bandwidth estimation?
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200403 absl::optional<bool> combined_audio_video_bwe;
deadbeefb10f32f2017-02-08 01:38:21 -0800404
405 // Can be used to disable DTLS-SRTP. This should never be done, but can be
406 // useful for testing purposes, for example in setting up a loopback call
407 // with a single PeerConnection.
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200408 absl::optional<bool> enable_dtls_srtp;
deadbeefb10f32f2017-02-08 01:38:21 -0800409
410 /////////////////////////////////////////////////
411 // The below fields are not part of the standard.
412 /////////////////////////////////////////////////
413
414 // Can be used to disable TCP candidate generation.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700415 TcpCandidatePolicy tcp_candidate_policy = kTcpCandidatePolicyEnabled;
deadbeefb10f32f2017-02-08 01:38:21 -0800416
417 // Can be used to avoid gathering candidates for a "higher cost" network,
418 // if a lower cost one exists. For example, if both Wi-Fi and cellular
419 // interfaces are available, this could be used to avoid using the cellular
420 // interface.
honghaiz60347052016-05-31 18:29:12 -0700421 CandidateNetworkPolicy candidate_network_policy =
422 kCandidateNetworkPolicyAll;
deadbeefb10f32f2017-02-08 01:38:21 -0800423
424 // The maximum number of packets that can be stored in the NetEq audio
425 // jitter buffer. Can be reduced to lower tolerated audio latency.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700426 int audio_jitter_buffer_max_packets = kAudioJitterBufferMaxPackets;
deadbeefb10f32f2017-02-08 01:38:21 -0800427
428 // Whether to use the NetEq "fast mode" which will accelerate audio quicker
429 // if it falls behind.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700430 bool audio_jitter_buffer_fast_accelerate = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800431
432 // Timeout in milliseconds before an ICE candidate pair is considered to be
433 // "not receiving", after which a lower priority candidate pair may be
434 // selected.
435 int ice_connection_receiving_timeout = kUndefined;
436
437 // Interval in milliseconds at which an ICE "backup" candidate pair will be
438 // pinged. This is a candidate pair which is not actively in use, but may
439 // be switched to if the active candidate pair becomes unusable.
440 //
441 // This is relevant mainly to Wi-Fi/cell handoff; the application may not
442 // want this backup cellular candidate pair pinged frequently, since it
443 // consumes data/battery.
444 int ice_backup_candidate_pair_ping_interval = kUndefined;
445
446 // Can be used to enable continual gathering, which means new candidates
447 // will be gathered as network interfaces change. Note that if continual
448 // gathering is used, the candidate removal API should also be used, to
449 // avoid an ever-growing list of candidates.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700450 ContinualGatheringPolicy continual_gathering_policy = GATHER_ONCE;
deadbeefb10f32f2017-02-08 01:38:21 -0800451
452 // If set to true, candidate pairs will be pinged in order of most likely
453 // to work (which means using a TURN server, generally), rather than in
454 // standard priority order.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700455 bool prioritize_most_likely_ice_candidate_pairs = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800456
Niels Möller6daa2782018-01-23 10:37:42 +0100457 // Implementation defined settings. A public member only for the benefit of
458 // the implementation. Applications must not access it directly, and should
459 // instead use provided accessor methods, e.g., set_cpu_adaptation.
nissec36b31b2016-04-11 23:25:29 -0700460 struct cricket::MediaConfig media_config;
deadbeefb10f32f2017-02-08 01:38:21 -0800461
deadbeefb10f32f2017-02-08 01:38:21 -0800462 // If set to true, only one preferred TURN allocation will be used per
463 // network interface. UDP is preferred over TCP and IPv6 over IPv4. This
464 // can be used to cut down on the number of candidate pairings.
Honghai Zhangb9e7b4a2016-06-30 20:52:02 -0700465 bool prune_turn_ports = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800466
Taylor Brandstettere9851112016-07-01 11:11:13 -0700467 // If set to true, this means the ICE transport should presume TURN-to-TURN
468 // candidate pairs will succeed, even before a binding response is received.
deadbeefb10f32f2017-02-08 01:38:21 -0800469 // This can be used to optimize the initial connection time, since the DTLS
470 // handshake can begin immediately.
Taylor Brandstettere9851112016-07-01 11:11:13 -0700471 bool presume_writable_when_fully_relayed = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800472
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700473 // If true, "renomination" will be added to the ice options in the transport
474 // description.
deadbeefb10f32f2017-02-08 01:38:21 -0800475 // See: https://tools.ietf.org/html/draft-thatcher-ice-renomination-00
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700476 bool enable_ice_renomination = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800477
478 // If true, the ICE role is re-determined when the PeerConnection sets a
479 // local transport description that indicates an ICE restart.
480 //
481 // This is standard RFC5245 ICE behavior, but causes unnecessary role
482 // thrashing, so an application may wish to avoid it. This role
483 // re-determining was removed in ICEbis (ICE v2).
Honghai Zhangbfd398c2016-08-30 22:07:42 -0700484 bool redetermine_role_on_ice_restart = true;
deadbeefb10f32f2017-02-08 01:38:21 -0800485
Qingsi Wange6826d22018-03-08 14:55:14 -0800486 // The following fields define intervals in milliseconds at which ICE
487 // connectivity checks are sent.
488 //
489 // We consider ICE is "strongly connected" for an agent when there is at
490 // least one candidate pair that currently succeeds in connectivity check
491 // from its direction i.e. sending a STUN ping and receives a STUN ping
492 // response, AND all candidate pairs have sent a minimum number of pings for
493 // connectivity (this number is implementation-specific). Otherwise, ICE is
494 // considered in "weak connectivity".
495 //
496 // Note that the above notion of strong and weak connectivity is not defined
497 // in RFC 5245, and they apply to our current ICE implementation only.
498 //
499 // 1) ice_check_interval_strong_connectivity defines the interval applied to
500 // ALL candidate pairs when ICE is strongly connected, and it overrides the
501 // default value of this interval in the ICE implementation;
502 // 2) ice_check_interval_weak_connectivity defines the counterpart for ALL
503 // pairs when ICE is weakly connected, and it overrides the default value of
504 // this interval in the ICE implementation;
505 // 3) ice_check_min_interval defines the minimal interval (equivalently the
506 // maximum rate) that overrides the above two intervals when either of them
507 // is less.
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200508 absl::optional<int> ice_check_interval_strong_connectivity;
509 absl::optional<int> ice_check_interval_weak_connectivity;
510 absl::optional<int> ice_check_min_interval;
deadbeefb10f32f2017-02-08 01:38:21 -0800511
Qingsi Wang22e623a2018-03-13 10:53:57 -0700512 // The min time period for which a candidate pair must wait for response to
513 // connectivity checks before it becomes unwritable. This parameter
514 // overrides the default value in the ICE implementation if set.
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200515 absl::optional<int> ice_unwritable_timeout;
Qingsi Wang22e623a2018-03-13 10:53:57 -0700516
517 // The min number of connectivity checks that a candidate pair must sent
518 // without receiving response before it becomes unwritable. This parameter
519 // overrides the default value in the ICE implementation if set.
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200520 absl::optional<int> ice_unwritable_min_checks;
Qingsi Wang22e623a2018-03-13 10:53:57 -0700521
Qingsi Wangdb53f8e2018-02-20 14:45:49 -0800522 // The interval in milliseconds at which STUN candidates will resend STUN
523 // binding requests to keep NAT bindings open.
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200524 absl::optional<int> stun_candidate_keepalive_interval;
Qingsi Wangdb53f8e2018-02-20 14:45:49 -0800525
Steve Anton300bf8e2017-07-14 10:13:10 -0700526 // ICE Periodic Regathering
527 // If set, WebRTC will periodically create and propose candidates without
528 // starting a new ICE generation. The regathering happens continuously with
529 // interval specified in milliseconds by the uniform distribution [a, b].
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200530 absl::optional<rtc::IntervalRange> ice_regather_interval_range;
Steve Anton300bf8e2017-07-14 10:13:10 -0700531
Jonas Orelandbdcee282017-10-10 14:01:40 +0200532 // Optional TurnCustomizer.
533 // With this class one can modify outgoing TURN messages.
534 // The object passed in must remain valid until PeerConnection::Close() is
535 // called.
536 webrtc::TurnCustomizer* turn_customizer = nullptr;
537
Qingsi Wang9a5c6f82018-02-01 10:38:40 -0800538 // Preferred network interface.
539 // A candidate pair on a preferred network has a higher precedence in ICE
540 // than one on an un-preferred network, regardless of priority or network
541 // cost.
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200542 absl::optional<rtc::AdapterType> network_preference;
Qingsi Wang9a5c6f82018-02-01 10:38:40 -0800543
Steve Anton79e79602017-11-20 10:25:56 -0800544 // Configure the SDP semantics used by this PeerConnection. Note that the
545 // WebRTC 1.0 specification requires kUnifiedPlan semantics. The
546 // RtpTransceiver API is only available with kUnifiedPlan semantics.
547 //
548 // kPlanB will cause PeerConnection to create offers and answers with at
549 // most one audio and one video m= section with multiple RtpSenders and
550 // RtpReceivers specified as multiple a=ssrc lines within the section. This
Steve Antonab6ea6b2018-02-26 14:23:09 -0800551 // will also cause PeerConnection to ignore all but the first m= section of
552 // the same media type.
Steve Anton79e79602017-11-20 10:25:56 -0800553 //
554 // kUnifiedPlan will cause PeerConnection to create offers and answers with
555 // multiple m= sections where each m= section maps to one RtpSender and one
Steve Antonab6ea6b2018-02-26 14:23:09 -0800556 // RtpReceiver (an RtpTransceiver), either both audio or both video. This
557 // will also cause PeerConnection to ignore all but the first a=ssrc lines
558 // that form a Plan B stream.
Steve Anton79e79602017-11-20 10:25:56 -0800559 //
Steve Anton79e79602017-11-20 10:25:56 -0800560 // For users who wish to send multiple audio/video streams and need to stay
Steve Anton3acffc32018-04-12 17:21:03 -0700561 // interoperable with legacy WebRTC implementations or use legacy APIs,
562 // specify kPlanB.
Steve Anton79e79602017-11-20 10:25:56 -0800563 //
Steve Anton3acffc32018-04-12 17:21:03 -0700564 // For all other users, specify kUnifiedPlan.
565 SdpSemantics sdp_semantics = SdpSemantics::kPlanB;
Steve Anton79e79602017-11-20 10:25:56 -0800566
Zhi Huangb57e1692018-06-12 11:41:11 -0700567 // Actively reset the SRTP parameters whenever the DTLS transports
568 // underneath are reset for every offer/answer negotiation.
569 // This is only intended to be a workaround for crbug.com/835958
570 // WARNING: This would cause RTP/RTCP packets decryption failure if not used
571 // correctly. This flag will be deprecated soon. Do not rely on it.
572 bool active_reset_srtp_params = false;
573
deadbeef293e9262017-01-11 12:28:30 -0800574 //
575 // Don't forget to update operator== if adding something.
576 //
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000577 };
578
deadbeefb10f32f2017-02-08 01:38:21 -0800579 // See: https://www.w3.org/TR/webrtc/#idl-def-rtcofferansweroptions
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000580 struct RTCOfferAnswerOptions {
581 static const int kUndefined = -1;
582 static const int kMaxOfferToReceiveMedia = 1;
583
584 // The default value for constraint offerToReceiveX:true.
585 static const int kOfferToReceiveMediaTrue = 1;
586
Steve Antonab6ea6b2018-02-26 14:23:09 -0800587 // These options are left as backwards compatibility for clients who need
588 // "Plan B" semantics. Clients who have switched to "Unified Plan" semantics
589 // should use the RtpTransceiver API (AddTransceiver) instead.
deadbeefb10f32f2017-02-08 01:38:21 -0800590 //
591 // offer_to_receive_X set to 1 will cause a media description to be
592 // generated in the offer, even if no tracks of that type have been added.
593 // Values greater than 1 are treated the same.
594 //
595 // If set to 0, the generated directional attribute will not include the
596 // "recv" direction (meaning it will be "sendonly" or "inactive".
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700597 int offer_to_receive_video = kUndefined;
598 int offer_to_receive_audio = kUndefined;
deadbeefb10f32f2017-02-08 01:38:21 -0800599
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700600 bool voice_activity_detection = true;
601 bool ice_restart = false;
deadbeefb10f32f2017-02-08 01:38:21 -0800602
603 // If true, will offer to BUNDLE audio/video/data together. Not to be
604 // confused with RTCP mux (multiplexing RTP and RTCP together).
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700605 bool use_rtp_mux = true;
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000606
Jonas Orelandfc1acd22018-08-24 10:58:37 +0200607 // This will apply to all video tracks with a Plan B SDP offer/answer.
608 int num_simulcast_layers = 1;
609
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700610 RTCOfferAnswerOptions() = default;
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000611
612 RTCOfferAnswerOptions(int offer_to_receive_video,
613 int offer_to_receive_audio,
614 bool voice_activity_detection,
615 bool ice_restart,
616 bool use_rtp_mux)
617 : offer_to_receive_video(offer_to_receive_video),
618 offer_to_receive_audio(offer_to_receive_audio),
619 voice_activity_detection(voice_activity_detection),
620 ice_restart(ice_restart),
621 use_rtp_mux(use_rtp_mux) {}
622 };
623
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000624 // Used by GetStats to decide which stats to include in the stats reports.
625 // |kStatsOutputLevelStandard| includes the standard stats for Javascript API;
626 // |kStatsOutputLevelDebug| includes both the standard stats and additional
627 // stats for debugging purposes.
628 enum StatsOutputLevel {
629 kStatsOutputLevelStandard,
630 kStatsOutputLevelDebug,
631 };
632
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000633 // Accessor methods to active local streams.
Steve Antonab6ea6b2018-02-26 14:23:09 -0800634 // This method is not supported with kUnifiedPlan semantics. Please use
635 // GetSenders() instead.
Yves Gerey665174f2018-06-19 15:03:05 +0200636 virtual rtc::scoped_refptr<StreamCollectionInterface> local_streams() = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000637
638 // Accessor methods to remote streams.
Steve Antonab6ea6b2018-02-26 14:23:09 -0800639 // This method is not supported with kUnifiedPlan semantics. Please use
640 // GetReceivers() instead.
Yves Gerey665174f2018-06-19 15:03:05 +0200641 virtual rtc::scoped_refptr<StreamCollectionInterface> remote_streams() = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000642
643 // Add a new MediaStream to be sent on this PeerConnection.
644 // Note that a SessionDescription negotiation is needed before the
645 // remote peer can receive the stream.
deadbeefb10f32f2017-02-08 01:38:21 -0800646 //
647 // This has been removed from the standard in favor of a track-based API. So,
648 // this is equivalent to simply calling AddTrack for each track within the
649 // stream, with the one difference that if "stream->AddTrack(...)" is called
650 // later, the PeerConnection will automatically pick up the new track. Though
651 // this functionality will be deprecated in the future.
Steve Antonab6ea6b2018-02-26 14:23:09 -0800652 //
653 // This method is not supported with kUnifiedPlan semantics. Please use
654 // AddTrack instead.
perkj@webrtc.orgfd0efb62014-11-06 12:16:36 +0000655 virtual bool AddStream(MediaStreamInterface* stream) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000656
657 // Remove a MediaStream from this PeerConnection.
deadbeefb10f32f2017-02-08 01:38:21 -0800658 // Note that a SessionDescription negotiation is needed before the
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000659 // remote peer is notified.
Steve Antonab6ea6b2018-02-26 14:23:09 -0800660 //
661 // This method is not supported with kUnifiedPlan semantics. Please use
662 // RemoveTrack instead.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000663 virtual void RemoveStream(MediaStreamInterface* stream) = 0;
664
deadbeefb10f32f2017-02-08 01:38:21 -0800665 // Add a new MediaStreamTrack to be sent on this PeerConnection, and return
Steve Antonf9381f02017-12-14 10:23:57 -0800666 // the newly created RtpSender. The RtpSender will be associated with the
Seth Hampson845e8782018-03-02 11:34:10 -0800667 // streams specified in the |stream_ids| list.
deadbeefb10f32f2017-02-08 01:38:21 -0800668 //
Steve Antonf9381f02017-12-14 10:23:57 -0800669 // Errors:
670 // - INVALID_PARAMETER: |track| is null, has a kind other than audio or video,
671 // or a sender already exists for the track.
672 // - INVALID_STATE: The PeerConnection is closed.
Steve Anton2d6c76a2018-01-05 17:10:52 -0800673 virtual RTCErrorOr<rtc::scoped_refptr<RtpSenderInterface>> AddTrack(
674 rtc::scoped_refptr<MediaStreamTrackInterface> track,
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200675 const std::vector<std::string>& stream_ids);
deadbeefe1f9d832016-01-14 15:35:42 -0800676
677 // Remove an RtpSender from this PeerConnection.
678 // Returns true on success.
Steve Anton24db5732018-07-23 10:27:33 -0700679 // TODO(steveanton): Replace with signature that returns RTCError.
680 virtual bool RemoveTrack(RtpSenderInterface* sender);
681
682 // Plan B semantics: Removes the RtpSender from this PeerConnection.
683 // Unified Plan semantics: Stop sending on the RtpSender and mark the
684 // corresponding RtpTransceiver direction as no longer sending.
685 //
686 // Errors:
687 // - INVALID_PARAMETER: |sender| is null or (Plan B only) the sender is not
688 // associated with this PeerConnection.
689 // - INVALID_STATE: PeerConnection is closed.
690 // TODO(bugs.webrtc.org/9534): Rename to RemoveTrack once the other signature
691 // is removed.
692 virtual RTCError RemoveTrackNew(
693 rtc::scoped_refptr<RtpSenderInterface> sender);
deadbeefe1f9d832016-01-14 15:35:42 -0800694
Steve Anton9158ef62017-11-27 13:01:52 -0800695 // AddTransceiver creates a new RtpTransceiver and adds it to the set of
696 // transceivers. Adding a transceiver will cause future calls to CreateOffer
697 // to add a media description for the corresponding transceiver.
698 //
699 // The initial value of |mid| in the returned transceiver is null. Setting a
700 // new session description may change it to a non-null value.
701 //
702 // https://w3c.github.io/webrtc-pc/#dom-rtcpeerconnection-addtransceiver
703 //
704 // Optionally, an RtpTransceiverInit structure can be specified to configure
705 // the transceiver from construction. If not specified, the transceiver will
706 // default to having a direction of kSendRecv and not be part of any streams.
707 //
708 // These methods are only available when Unified Plan is enabled (see
709 // RTCConfiguration).
710 //
711 // Common errors:
712 // - INTERNAL_ERROR: The configuration does not have Unified Plan enabled.
713 // TODO(steveanton): Make these pure virtual once downstream projects have
714 // updated.
715
716 // Adds a transceiver with a sender set to transmit the given track. The kind
717 // of the transceiver (and sender/receiver) will be derived from the kind of
718 // the track.
719 // Errors:
720 // - INVALID_PARAMETER: |track| is null.
721 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>>
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200722 AddTransceiver(rtc::scoped_refptr<MediaStreamTrackInterface> track);
Steve Anton9158ef62017-11-27 13:01:52 -0800723 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>>
724 AddTransceiver(rtc::scoped_refptr<MediaStreamTrackInterface> track,
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200725 const RtpTransceiverInit& init);
Steve Anton9158ef62017-11-27 13:01:52 -0800726
727 // Adds a transceiver with the given kind. Can either be MEDIA_TYPE_AUDIO or
728 // MEDIA_TYPE_VIDEO.
729 // Errors:
730 // - INVALID_PARAMETER: |media_type| is not MEDIA_TYPE_AUDIO or
731 // MEDIA_TYPE_VIDEO.
732 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>>
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200733 AddTransceiver(cricket::MediaType media_type);
Steve Anton9158ef62017-11-27 13:01:52 -0800734 virtual RTCErrorOr<rtc::scoped_refptr<RtpTransceiverInterface>>
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200735 AddTransceiver(cricket::MediaType media_type, const RtpTransceiverInit& init);
Steve Anton9158ef62017-11-27 13:01:52 -0800736
deadbeef70ab1a12015-09-28 16:53:55 -0700737 // TODO(deadbeef): Make these pure virtual once all subclasses implement them.
deadbeefb10f32f2017-02-08 01:38:21 -0800738
739 // Creates a sender without a track. Can be used for "early media"/"warmup"
740 // use cases, where the application may want to negotiate video attributes
741 // before a track is available to send.
742 //
743 // The standard way to do this would be through "addTransceiver", but we
744 // don't support that API yet.
745 //
deadbeeffac06552015-11-25 11:26:01 -0800746 // |kind| must be "audio" or "video".
deadbeefb10f32f2017-02-08 01:38:21 -0800747 //
deadbeefbd7d8f72015-12-18 16:58:44 -0800748 // |stream_id| is used to populate the msid attribute; if empty, one will
749 // be generated automatically.
Steve Antonab6ea6b2018-02-26 14:23:09 -0800750 //
751 // This method is not supported with kUnifiedPlan semantics. Please use
752 // AddTransceiver instead.
deadbeeffac06552015-11-25 11:26:01 -0800753 virtual rtc::scoped_refptr<RtpSenderInterface> CreateSender(
deadbeefbd7d8f72015-12-18 16:58:44 -0800754 const std::string& kind,
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200755 const std::string& stream_id);
deadbeeffac06552015-11-25 11:26:01 -0800756
Steve Antonab6ea6b2018-02-26 14:23:09 -0800757 // If Plan B semantics are specified, gets all RtpSenders, created either
758 // through AddStream, AddTrack, or CreateSender. All senders of a specific
759 // media type share the same media description.
760 //
761 // If Unified Plan semantics are specified, gets the RtpSender for each
762 // RtpTransceiver.
deadbeef70ab1a12015-09-28 16:53:55 -0700763 virtual std::vector<rtc::scoped_refptr<RtpSenderInterface>> GetSenders()
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200764 const;
deadbeef70ab1a12015-09-28 16:53:55 -0700765
Steve Antonab6ea6b2018-02-26 14:23:09 -0800766 // If Plan B semantics are specified, gets all RtpReceivers created when a
767 // remote description is applied. All receivers of a specific media type share
768 // the same media description. It is also possible to have a media description
769 // with no associated RtpReceivers, if the directional attribute does not
770 // indicate that the remote peer is sending any media.
deadbeefb10f32f2017-02-08 01:38:21 -0800771 //
Steve Antonab6ea6b2018-02-26 14:23:09 -0800772 // If Unified Plan semantics are specified, gets the RtpReceiver for each
773 // RtpTransceiver.
deadbeef70ab1a12015-09-28 16:53:55 -0700774 virtual std::vector<rtc::scoped_refptr<RtpReceiverInterface>> GetReceivers()
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200775 const;
deadbeef70ab1a12015-09-28 16:53:55 -0700776
Steve Anton9158ef62017-11-27 13:01:52 -0800777 // Get all RtpTransceivers, created either through AddTransceiver, AddTrack or
778 // by a remote description applied with SetRemoteDescription.
Steve Antonab6ea6b2018-02-26 14:23:09 -0800779 //
Steve Anton9158ef62017-11-27 13:01:52 -0800780 // Note: This method is only available when Unified Plan is enabled (see
781 // RTCConfiguration).
782 virtual std::vector<rtc::scoped_refptr<RtpTransceiverInterface>>
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200783 GetTransceivers() const;
Steve Anton9158ef62017-11-27 13:01:52 -0800784
Henrik Boström1df1bf82018-03-20 13:24:20 +0100785 // The legacy non-compliant GetStats() API. This correspond to the
786 // callback-based version of getStats() in JavaScript. The returned metrics
787 // are UNDOCUMENTED and many of them rely on implementation-specific details.
788 // The goal is to DELETE THIS VERSION but we can't today because it is heavily
789 // relied upon by third parties. See https://crbug.com/822696.
790 //
791 // This version is wired up into Chrome. Any stats implemented are
792 // automatically exposed to the Web Platform. This has BYPASSED the Chrome
793 // release processes for years and lead to cross-browser incompatibility
794 // issues and web application reliance on Chrome-only behavior.
795 //
796 // This API is in "maintenance mode", serious regressions should be fixed but
797 // adding new stats is highly discouraged.
798 //
799 // TODO(hbos): Deprecate and remove this when third parties have migrated to
800 // the spec-compliant GetStats() API. https://crbug.com/822696
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000801 virtual bool GetStats(StatsObserver* observer,
Henrik Boström1df1bf82018-03-20 13:24:20 +0100802 MediaStreamTrackInterface* track, // Optional
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000803 StatsOutputLevel level) = 0;
Henrik Boström1df1bf82018-03-20 13:24:20 +0100804 // The spec-compliant GetStats() API. This correspond to the promise-based
805 // version of getStats() in JavaScript. Implementation status is described in
806 // api/stats/rtcstats_objects.h. For more details on stats, see spec:
807 // https://w3c.github.io/webrtc-pc/#dom-rtcpeerconnection-getstats
808 // TODO(hbos): Takes shared ownership, use rtc::scoped_refptr<> instead. This
809 // requires stop overriding the current version in third party or making third
810 // party calls explicit to avoid ambiguity during switch. Make the future
811 // version abstract as soon as third party projects implement it.
hbose3810152016-12-13 02:35:19 -0800812 virtual void GetStats(RTCStatsCollectorCallback* callback) {}
Henrik Boström1df1bf82018-03-20 13:24:20 +0100813 // Spec-compliant getStats() performing the stats selection algorithm with the
814 // sender. https://w3c.github.io/webrtc-pc/#dom-rtcrtpsender-getstats
815 // TODO(hbos): Make abstract as soon as third party projects implement it.
816 virtual void GetStats(
817 rtc::scoped_refptr<RtpSenderInterface> selector,
818 rtc::scoped_refptr<RTCStatsCollectorCallback> callback) {}
819 // Spec-compliant getStats() performing the stats selection algorithm with the
820 // receiver. https://w3c.github.io/webrtc-pc/#dom-rtcrtpreceiver-getstats
821 // TODO(hbos): Make abstract as soon as third party projects implement it.
822 virtual void GetStats(
823 rtc::scoped_refptr<RtpReceiverInterface> selector,
824 rtc::scoped_refptr<RTCStatsCollectorCallback> callback) {}
Steve Antonab6ea6b2018-02-26 14:23:09 -0800825 // Clear cached stats in the RTCStatsCollector.
Harald Alvestrand89061872018-01-02 14:08:34 +0100826 // Exposed for testing while waiting for automatic cache clear to work.
827 // https://bugs.webrtc.org/8693
828 virtual void ClearStatsCache() {}
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000829
deadbeefb10f32f2017-02-08 01:38:21 -0800830 // Create a data channel with the provided config, or default config if none
831 // is provided. Note that an offer/answer negotiation is still necessary
832 // before the data channel can be used.
833 //
834 // Also, calling CreateDataChannel is the only way to get a data "m=" section
835 // in SDP, so it should be done before CreateOffer is called, if the
836 // application plans to use data channels.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000837 virtual rtc::scoped_refptr<DataChannelInterface> CreateDataChannel(
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000838 const std::string& label,
839 const DataChannelInit* config) = 0;
840
deadbeefb10f32f2017-02-08 01:38:21 -0800841 // Returns the more recently applied description; "pending" if it exists, and
842 // otherwise "current". See below.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000843 virtual const SessionDescriptionInterface* local_description() const = 0;
844 virtual const SessionDescriptionInterface* remote_description() const = 0;
deadbeefb10f32f2017-02-08 01:38:21 -0800845
deadbeeffe4a8a42016-12-20 17:56:17 -0800846 // A "current" description the one currently negotiated from a complete
847 // offer/answer exchange.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200848 virtual const SessionDescriptionInterface* current_local_description() const;
849 virtual const SessionDescriptionInterface* current_remote_description() const;
deadbeefb10f32f2017-02-08 01:38:21 -0800850
deadbeeffe4a8a42016-12-20 17:56:17 -0800851 // A "pending" description is one that's part of an incomplete offer/answer
852 // exchange (thus, either an offer or a pranswer). Once the offer/answer
853 // exchange is finished, the "pending" description will become "current".
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200854 virtual const SessionDescriptionInterface* pending_local_description() const;
855 virtual const SessionDescriptionInterface* pending_remote_description() const;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000856
857 // Create a new offer.
858 // The CreateSessionDescriptionObserver callback will be called when done.
859 virtual void CreateOffer(CreateSessionDescriptionObserver* observer,
Niels Möllerf06f9232018-08-07 12:32:18 +0200860 const RTCOfferAnswerOptions& options) = 0;
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000861
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000862 // Create an answer to an offer.
863 // The CreateSessionDescriptionObserver callback will be called when done.
864 virtual void CreateAnswer(CreateSessionDescriptionObserver* observer,
Niels Möllerf06f9232018-08-07 12:32:18 +0200865 const RTCOfferAnswerOptions& options) = 0;
htaa2a49d92016-03-04 02:51:39 -0800866
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000867 // Sets the local session description.
deadbeef1dcb1642017-03-29 21:08:16 -0700868 // The PeerConnection takes the ownership of |desc| even if it fails.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000869 // The |observer| callback will be called when done.
deadbeef1dcb1642017-03-29 21:08:16 -0700870 // TODO(deadbeef): Change |desc| to be a unique_ptr, to make it clear
871 // that this method always takes ownership of it.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000872 virtual void SetLocalDescription(SetSessionDescriptionObserver* observer,
873 SessionDescriptionInterface* desc) = 0;
874 // Sets the remote session description.
deadbeef1dcb1642017-03-29 21:08:16 -0700875 // The PeerConnection takes the ownership of |desc| even if it fails.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000876 // The |observer| callback will be called when done.
Henrik Boström31638672017-11-23 17:48:32 +0100877 // TODO(hbos): Remove when Chrome implements the new signature.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000878 virtual void SetRemoteDescription(SetSessionDescriptionObserver* observer,
Henrik Boström07109652017-11-27 09:52:02 +0100879 SessionDescriptionInterface* desc) {}
Henrik Boström31638672017-11-23 17:48:32 +0100880 // TODO(hbos): Make pure virtual when Chrome has updated its signature.
881 virtual void SetRemoteDescription(
882 std::unique_ptr<SessionDescriptionInterface> desc,
883 rtc::scoped_refptr<SetRemoteDescriptionObserverInterface> observer) {}
deadbeefb10f32f2017-02-08 01:38:21 -0800884
deadbeef46c73892016-11-16 19:42:04 -0800885 // TODO(deadbeef): Make this pure virtual once all Chrome subclasses of
886 // PeerConnectionInterface implement it.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200887 virtual PeerConnectionInterface::RTCConfiguration GetConfiguration();
deadbeef293e9262017-01-11 12:28:30 -0800888
deadbeefa67696b2015-09-29 11:56:26 -0700889 // Sets the PeerConnection's global configuration to |config|.
deadbeef293e9262017-01-11 12:28:30 -0800890 //
891 // The members of |config| that may be changed are |type|, |servers|,
892 // |ice_candidate_pool_size| and |prune_turn_ports| (though the candidate
893 // pool size can't be changed after the first call to SetLocalDescription).
894 // Note that this means the BUNDLE and RTCP-multiplexing policies cannot be
895 // changed with this method.
896 //
deadbeefa67696b2015-09-29 11:56:26 -0700897 // Any changes to STUN/TURN servers or ICE candidate policy will affect the
898 // next gathering phase, and cause the next call to createOffer to generate
deadbeef293e9262017-01-11 12:28:30 -0800899 // new ICE credentials, as described in JSEP. This also occurs when
900 // |prune_turn_ports| changes, for the same reasoning.
901 //
902 // If an error occurs, returns false and populates |error| if non-null:
903 // - INVALID_MODIFICATION if |config| contains a modified parameter other
904 // than one of the parameters listed above.
905 // - INVALID_RANGE if |ice_candidate_pool_size| is out of range.
906 // - SYNTAX_ERROR if parsing an ICE server URL failed.
907 // - INVALID_PARAMETER if a TURN server is missing |username| or |password|.
908 // - INTERNAL_ERROR if an unexpected error occurred.
909 //
deadbeefa67696b2015-09-29 11:56:26 -0700910 // TODO(deadbeef): Make this pure virtual once all Chrome subclasses of
911 // PeerConnectionInterface implement it.
912 virtual bool SetConfiguration(
deadbeef293e9262017-01-11 12:28:30 -0800913 const PeerConnectionInterface::RTCConfiguration& config,
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200914 RTCError* error);
915
deadbeef293e9262017-01-11 12:28:30 -0800916 // Version without error output param for backwards compatibility.
917 // TODO(deadbeef): Remove once chromium is updated.
918 virtual bool SetConfiguration(
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200919 const PeerConnectionInterface::RTCConfiguration& config);
deadbeefb10f32f2017-02-08 01:38:21 -0800920
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000921 // Provides a remote candidate to the ICE Agent.
922 // A copy of the |candidate| will be created and added to the remote
923 // description. So the caller of this method still has the ownership of the
924 // |candidate|.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000925 virtual bool AddIceCandidate(const IceCandidateInterface* candidate) = 0;
926
deadbeefb10f32f2017-02-08 01:38:21 -0800927 // Removes a group of remote candidates from the ICE agent. Needed mainly for
928 // continual gathering, to avoid an ever-growing list of candidates as
929 // networks come and go.
Honghai Zhang7fb69db2016-03-14 11:59:18 -0700930 virtual bool RemoveIceCandidates(
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200931 const std::vector<cricket::Candidate>& candidates);
Honghai Zhang7fb69db2016-03-14 11:59:18 -0700932
zstein4b979802017-06-02 14:37:37 -0700933 // 0 <= min <= current <= max should hold for set parameters.
934 struct BitrateParameters {
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200935 BitrateParameters();
936 ~BitrateParameters();
937
Danil Chapovalov0bc58cf2018-06-21 13:32:56 +0200938 absl::optional<int> min_bitrate_bps;
939 absl::optional<int> current_bitrate_bps;
940 absl::optional<int> max_bitrate_bps;
zstein4b979802017-06-02 14:37:37 -0700941 };
942
943 // SetBitrate limits the bandwidth allocated for all RTP streams sent by
944 // this PeerConnection. Other limitations might affect these limits and
945 // are respected (for example "b=AS" in SDP).
946 //
947 // Setting |current_bitrate_bps| will reset the current bitrate estimate
948 // to the provided value.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200949 virtual RTCError SetBitrate(const BitrateSettings& bitrate);
Niels Möller0c4f7be2018-05-07 14:01:37 +0200950
951 // TODO(nisse): Deprecated - use version above. These two default
952 // implementations require subclasses to implement one or the other
953 // of the methods.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200954 virtual RTCError SetBitrate(const BitrateParameters& bitrate_parameters);
zstein4b979802017-06-02 14:37:37 -0700955
Alex Narest78609d52017-10-20 10:37:47 +0200956 // Sets current strategy. If not set default WebRTC allocator will be used.
957 // May be changed during an active session. The strategy
958 // ownership is passed with std::unique_ptr
959 // TODO(alexnarest): Make this pure virtual when tests will be updated
960 virtual void SetBitrateAllocationStrategy(
961 std::unique_ptr<rtc::BitrateAllocationStrategy>
962 bitrate_allocation_strategy) {}
963
henrika5f6bf242017-11-01 11:06:56 +0100964 // Enable/disable playout of received audio streams. Enabled by default. Note
965 // that even if playout is enabled, streams will only be played out if the
966 // appropriate SDP is also applied. Setting |playout| to false will stop
967 // playout of the underlying audio device but starts a task which will poll
968 // for audio data every 10ms to ensure that audio processing happens and the
969 // audio statistics are updated.
970 // TODO(henrika): deprecate and remove this.
971 virtual void SetAudioPlayout(bool playout) {}
972
973 // Enable/disable recording of transmitted audio streams. Enabled by default.
974 // Note that even if recording is enabled, streams will only be recorded if
975 // the appropriate SDP is also applied.
976 // TODO(henrika): deprecate and remove this.
977 virtual void SetAudioRecording(bool recording) {}
978
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000979 // Returns the current SignalingState.
980 virtual SignalingState signaling_state() = 0;
Taylor Brandstettercb423c42017-10-22 11:52:32 -0700981
982 // Returns the aggregate state of all ICE *and* DTLS transports.
983 // TODO(deadbeef): Implement "PeerConnectionState" according to the standard,
984 // to aggregate ICE+DTLS state, and change the scope of IceConnectionState to
985 // be just the ICE layer. See: crbug.com/webrtc/6145
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000986 virtual IceConnectionState ice_connection_state() = 0;
Taylor Brandstettercb423c42017-10-22 11:52:32 -0700987
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000988 virtual IceGatheringState ice_gathering_state() = 0;
989
ivoc14d5dbe2016-07-04 07:06:55 -0700990 // Starts RtcEventLog using existing file. Takes ownership of |file| and
991 // passes it on to Call, which will take the ownership. If the
992 // operation fails the file will be closed. The logging will stop
993 // automatically after 10 minutes have passed, or when the StopRtcEventLog
994 // function is called.
Elad Alon99c3fe52017-10-13 16:29:40 +0200995 // TODO(eladalon): Deprecate and remove this.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +0200996 virtual bool StartRtcEventLog(rtc::PlatformFile file, int64_t max_size_bytes);
ivoc14d5dbe2016-07-04 07:06:55 -0700997
Elad Alon99c3fe52017-10-13 16:29:40 +0200998 // Start RtcEventLog using an existing output-sink. Takes ownership of
999 // |output| and passes it on to Call, which will take the ownership. If the
Bjorn Tereliusde939432017-11-20 17:38:14 +01001000 // operation fails the output will be closed and deallocated. The event log
1001 // will send serialized events to the output object every |output_period_ms|.
1002 virtual bool StartRtcEventLog(std::unique_ptr<RtcEventLogOutput> output,
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001003 int64_t output_period_ms);
Elad Alon99c3fe52017-10-13 16:29:40 +02001004
ivoc14d5dbe2016-07-04 07:06:55 -07001005 // Stops logging the RtcEventLog.
1006 // TODO(ivoc): Make this pure virtual when Chrome is updated.
1007 virtual void StopRtcEventLog() {}
1008
deadbeefb10f32f2017-02-08 01:38:21 -08001009 // Terminates all media, closes the transports, and in general releases any
1010 // resources used by the PeerConnection. This is an irreversible operation.
deadbeefd07061c2017-04-20 13:19:00 -07001011 //
1012 // Note that after this method completes, the PeerConnection will no longer
1013 // use the PeerConnectionObserver interface passed in on construction, and
1014 // thus the observer object can be safely destroyed.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001015 virtual void Close() = 0;
1016
1017 protected:
1018 // Dtor protected as objects shouldn't be deleted via this interface.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001019 ~PeerConnectionInterface() override = default;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001020};
1021
deadbeefb10f32f2017-02-08 01:38:21 -08001022// PeerConnection callback interface, used for RTCPeerConnection events.
1023// Application should implement these methods.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001024class PeerConnectionObserver {
1025 public:
Sami Kalliomäki02879f92018-01-11 10:02:19 +01001026 virtual ~PeerConnectionObserver() = default;
1027
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001028 // Triggered when the SignalingState changed.
1029 virtual void OnSignalingChange(
perkjdfb769d2016-02-09 03:09:43 -08001030 PeerConnectionInterface::SignalingState new_state) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001031
1032 // Triggered when media is received on a new stream from remote peer.
Steve Anton772eb212018-01-16 10:11:06 -08001033 virtual void OnAddStream(rtc::scoped_refptr<MediaStreamInterface> stream) {}
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001034
Steve Anton3172c032018-05-03 15:30:18 -07001035 // Triggered when a remote peer closes a stream.
Steve Anton772eb212018-01-16 10:11:06 -08001036 virtual void OnRemoveStream(rtc::scoped_refptr<MediaStreamInterface> stream) {
1037 }
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001038
Taylor Brandstetter98cde262016-05-31 13:02:21 -07001039 // Triggered when a remote peer opens a data channel.
1040 virtual void OnDataChannel(
nisse7f067662017-03-08 06:59:45 -08001041 rtc::scoped_refptr<DataChannelInterface> data_channel) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001042
Taylor Brandstetter98cde262016-05-31 13:02:21 -07001043 // Triggered when renegotiation is needed. For example, an ICE restart
1044 // has begun.
fischman@webrtc.orgd7568a02014-01-13 22:04:12 +00001045 virtual void OnRenegotiationNeeded() = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001046
Taylor Brandstetter98cde262016-05-31 13:02:21 -07001047 // Called any time the IceConnectionState changes.
deadbeefb10f32f2017-02-08 01:38:21 -08001048 //
1049 // Note that our ICE states lag behind the standard slightly. The most
1050 // notable differences include the fact that "failed" occurs after 15
1051 // seconds, not 30, and this actually represents a combination ICE + DTLS
1052 // state, so it may be "failed" if DTLS fails while ICE succeeds.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001053 virtual void OnIceConnectionChange(
perkjdfb769d2016-02-09 03:09:43 -08001054 PeerConnectionInterface::IceConnectionState new_state) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001055
Taylor Brandstetter98cde262016-05-31 13:02:21 -07001056 // Called any time the IceGatheringState changes.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001057 virtual void OnIceGatheringChange(
perkjdfb769d2016-02-09 03:09:43 -08001058 PeerConnectionInterface::IceGatheringState new_state) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001059
Taylor Brandstetter98cde262016-05-31 13:02:21 -07001060 // A new ICE candidate has been gathered.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001061 virtual void OnIceCandidate(const IceCandidateInterface* candidate) = 0;
1062
Honghai Zhang7fb69db2016-03-14 11:59:18 -07001063 // Ice candidates have been removed.
1064 // TODO(honghaiz): Make this a pure virtual method when all its subclasses
1065 // implement it.
1066 virtual void OnIceCandidatesRemoved(
1067 const std::vector<cricket::Candidate>& candidates) {}
1068
Peter Thatcher54360512015-07-08 11:08:35 -07001069 // Called when the ICE connection receiving status changes.
1070 virtual void OnIceConnectionReceivingChange(bool receiving) {}
1071
Steve Antonab6ea6b2018-02-26 14:23:09 -08001072 // This is called when a receiver and its track are created.
Henrik Boström933d8b02017-10-10 10:05:16 -07001073 // TODO(zhihuang): Make this pure virtual when all subclasses implement it.
Steve Anton8b815cd2018-02-16 16:14:42 -08001074 // Note: This is called with both Plan B and Unified Plan semantics. Unified
1075 // Plan users should prefer OnTrack, OnAddTrack is only called as backwards
1076 // compatibility (and is called in the exact same situations as OnTrack).
zhihuang81c3a032016-11-17 12:06:24 -08001077 virtual void OnAddTrack(
1078 rtc::scoped_refptr<RtpReceiverInterface> receiver,
zhihuangc63b8942016-12-02 15:41:10 -08001079 const std::vector<rtc::scoped_refptr<MediaStreamInterface>>& streams) {}
zhihuang81c3a032016-11-17 12:06:24 -08001080
Steve Anton8b815cd2018-02-16 16:14:42 -08001081 // This is called when signaling indicates a transceiver will be receiving
1082 // media from the remote endpoint. This is fired during a call to
1083 // SetRemoteDescription. The receiving track can be accessed by:
1084 // |transceiver->receiver()->track()| and its associated streams by
1085 // |transceiver->receiver()->streams()|.
1086 // Note: This will only be called if Unified Plan semantics are specified.
1087 // This behavior is specified in section 2.2.8.2.5 of the "Set the
1088 // RTCSessionDescription" algorithm:
1089 // https://w3c.github.io/webrtc-pc/#set-description
1090 virtual void OnTrack(
1091 rtc::scoped_refptr<RtpTransceiverInterface> transceiver) {}
1092
Steve Anton3172c032018-05-03 15:30:18 -07001093 // Called when signaling indicates that media will no longer be received on a
1094 // track.
1095 // With Plan B semantics, the given receiver will have been removed from the
1096 // PeerConnection and the track muted.
1097 // With Unified Plan semantics, the receiver will remain but the transceiver
1098 // will have changed direction to either sendonly or inactive.
Henrik Boström933d8b02017-10-10 10:05:16 -07001099 // https://w3c.github.io/webrtc-pc/#process-remote-track-removal
Henrik Boström933d8b02017-10-10 10:05:16 -07001100 // TODO(hbos,deadbeef): Make pure virtual when all subclasses implement it.
1101 virtual void OnRemoveTrack(
1102 rtc::scoped_refptr<RtpReceiverInterface> receiver) {}
Harald Alvestrandc0e97252018-07-26 10:39:55 +02001103
1104 // Called when an interesting usage is detected by WebRTC.
1105 // An appropriate action is to add information about the context of the
1106 // PeerConnection and write the event to some kind of "interesting events"
1107 // log function.
1108 // The heuristics for defining what constitutes "interesting" are
1109 // implementation-defined.
1110 virtual void OnInterestingUsage(int usage_pattern) {}
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001111};
1112
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001113// PeerConnectionDependencies holds all of PeerConnections dependencies.
1114// A dependency is distinct from a configuration as it defines significant
1115// executable code that can be provided by a user of the API.
1116//
1117// All new dependencies should be added as a unique_ptr to allow the
1118// PeerConnection object to be the definitive owner of the dependencies
1119// lifetime making injection safer.
1120struct PeerConnectionDependencies final {
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001121 explicit PeerConnectionDependencies(PeerConnectionObserver* observer_in);
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001122 // This object is not copyable or assignable.
1123 PeerConnectionDependencies(const PeerConnectionDependencies&) = delete;
1124 PeerConnectionDependencies& operator=(const PeerConnectionDependencies&) =
1125 delete;
1126 // This object is only moveable.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001127 PeerConnectionDependencies(PeerConnectionDependencies&&);
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001128 PeerConnectionDependencies& operator=(PeerConnectionDependencies&&) = default;
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001129 ~PeerConnectionDependencies();
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001130 // Mandatory dependencies
1131 PeerConnectionObserver* observer = nullptr;
1132 // Optional dependencies
1133 std::unique_ptr<cricket::PortAllocator> allocator;
Zach Steine20867f2018-08-02 13:20:15 -07001134 std::unique_ptr<webrtc::AsyncResolverFactory> async_resolver_factory;
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001135 std::unique_ptr<rtc::RTCCertificateGeneratorInterface> cert_generator;
Benjamin Wrightd6f86e82018-05-08 13:12:25 -07001136 std::unique_ptr<rtc::SSLCertificateVerifier> tls_cert_verifier;
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001137};
1138
Benjamin Wright5234a492018-05-29 15:04:32 -07001139// PeerConnectionFactoryDependencies holds all of the PeerConnectionFactory
1140// dependencies. All new dependencies should be added here instead of
1141// overloading the function. This simplifies dependency injection and makes it
1142// clear which are mandatory and optional. If possible please allow the peer
1143// connection factory to take ownership of the dependency by adding a unique_ptr
1144// to this structure.
1145struct PeerConnectionFactoryDependencies final {
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001146 PeerConnectionFactoryDependencies();
Benjamin Wright5234a492018-05-29 15:04:32 -07001147 // This object is not copyable or assignable.
1148 PeerConnectionFactoryDependencies(const PeerConnectionFactoryDependencies&) =
1149 delete;
1150 PeerConnectionFactoryDependencies& operator=(
1151 const PeerConnectionFactoryDependencies&) = delete;
1152 // This object is only moveable.
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001153 PeerConnectionFactoryDependencies(PeerConnectionFactoryDependencies&&);
Benjamin Wright5234a492018-05-29 15:04:32 -07001154 PeerConnectionFactoryDependencies& operator=(
1155 PeerConnectionFactoryDependencies&&) = default;
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001156 ~PeerConnectionFactoryDependencies();
Benjamin Wright5234a492018-05-29 15:04:32 -07001157
1158 // Optional dependencies
1159 rtc::Thread* network_thread = nullptr;
1160 rtc::Thread* worker_thread = nullptr;
1161 rtc::Thread* signaling_thread = nullptr;
1162 std::unique_ptr<cricket::MediaEngineInterface> media_engine;
1163 std::unique_ptr<CallFactoryInterface> call_factory;
1164 std::unique_ptr<RtcEventLogFactoryInterface> event_log_factory;
1165 std::unique_ptr<FecControllerFactoryInterface> fec_controller_factory;
1166 std::unique_ptr<NetworkControllerFactoryInterface> network_controller_factory;
1167};
1168
deadbeefb10f32f2017-02-08 01:38:21 -08001169// PeerConnectionFactoryInterface is the factory interface used for creating
1170// PeerConnection, MediaStream and MediaStreamTrack objects.
1171//
1172// The simplest method for obtaiing one, CreatePeerConnectionFactory will
1173// create the required libjingle threads, socket and network manager factory
1174// classes for networking if none are provided, though it requires that the
1175// application runs a message loop on the thread that called the method (see
1176// explanation below)
1177//
1178// If an application decides to provide its own threads and/or implementation
1179// of networking classes, it should use the alternate
1180// CreatePeerConnectionFactory method which accepts threads as input, and use
1181// the CreatePeerConnection version that takes a PortAllocator as an argument.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +00001182class PeerConnectionFactoryInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001183 public:
wu@webrtc.org97077a32013-10-25 21:18:33 +00001184 class Options {
1185 public:
deadbeefb10f32f2017-02-08 01:38:21 -08001186 Options() : crypto_options(rtc::CryptoOptions::NoGcm()) {}
1187
1188 // If set to true, created PeerConnections won't enforce any SRTP
1189 // requirement, allowing unsecured media. Should only be used for
1190 // testing/debugging.
1191 bool disable_encryption = false;
1192
1193 // Deprecated. The only effect of setting this to true is that
1194 // CreateDataChannel will fail, which is not that useful.
1195 bool disable_sctp_data_channels = false;
1196
1197 // If set to true, any platform-supported network monitoring capability
1198 // won't be used, and instead networks will only be updated via polling.
1199 //
1200 // This only has an effect if a PeerConnection is created with the default
1201 // PortAllocator implementation.
1202 bool disable_network_monitor = false;
phoglund@webrtc.org006521d2015-02-12 09:23:59 +00001203
1204 // Sets the network types to ignore. For instance, calling this with
1205 // ADAPTER_TYPE_ETHERNET | ADAPTER_TYPE_LOOPBACK will ignore Ethernet and
1206 // loopback interfaces.
deadbeefb10f32f2017-02-08 01:38:21 -08001207 int network_ignore_mask = rtc::kDefaultNetworkIgnoreMask;
Joachim Bauch04e5b492015-05-29 09:40:39 +02001208
1209 // Sets the maximum supported protocol version. The highest version
1210 // supported by both ends will be used for the connection, i.e. if one
1211 // party supports DTLS 1.0 and the other DTLS 1.2, DTLS 1.0 will be used.
deadbeefb10f32f2017-02-08 01:38:21 -08001212 rtc::SSLProtocolVersion ssl_max_version = rtc::SSL_PROTOCOL_DTLS_12;
jbauchcb560652016-08-04 05:20:32 -07001213
1214 // Sets crypto related options, e.g. enabled cipher suites.
1215 rtc::CryptoOptions crypto_options;
wu@webrtc.org97077a32013-10-25 21:18:33 +00001216 };
1217
deadbeef7914b8c2017-04-21 03:23:33 -07001218 // Set the options to be used for subsequently created PeerConnections.
wu@webrtc.org97077a32013-10-25 21:18:33 +00001219 virtual void SetOptions(const Options& options) = 0;
buildbot@webrtc.org41451d42014-05-03 05:39:45 +00001220
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001221 // The preferred way to create a new peer connection. Simply provide the
1222 // configuration and a PeerConnectionDependencies structure.
1223 // TODO(benwright): Make pure virtual once downstream mock PC factory classes
1224 // are updated.
1225 virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection(
1226 const PeerConnectionInterface::RTCConfiguration& configuration,
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001227 PeerConnectionDependencies dependencies);
Benjamin Wright6f7e6d62018-05-02 13:46:31 -07001228
1229 // Deprecated; |allocator| and |cert_generator| may be null, in which case
1230 // default implementations will be used.
deadbeefd07061c2017-04-20 13:19:00 -07001231 //
1232 // |observer| must not be null.
1233 //
1234 // Note that this method does not take ownership of |observer|; it's the
1235 // responsibility of the caller to delete it. It can be safely deleted after
1236 // Close has been called on the returned PeerConnection, which ensures no
1237 // more observer callbacks will be invoked.
deadbeef41b07982015-12-01 15:01:24 -08001238 virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection(
1239 const PeerConnectionInterface::RTCConfiguration& configuration,
kwibergd1fe2812016-04-27 06:47:29 -07001240 std::unique_ptr<cricket::PortAllocator> allocator,
Henrik Boströmd03c23b2016-06-01 11:44:18 +02001241 std::unique_ptr<rtc::RTCCertificateGeneratorInterface> cert_generator,
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001242 PeerConnectionObserver* observer);
1243
Florent Castelli72b751a2018-06-28 14:09:33 +02001244 // Returns the capabilities of an RTP sender of type |kind|.
1245 // If for some reason you pass in MEDIA_TYPE_DATA, returns an empty structure.
1246 // TODO(orphis): Make pure virtual when all subclasses implement it.
1247 virtual RtpCapabilities GetRtpSenderCapabilities(
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001248 cricket::MediaType kind) const;
Florent Castelli72b751a2018-06-28 14:09:33 +02001249
1250 // Returns the capabilities of an RTP receiver of type |kind|.
1251 // If for some reason you pass in MEDIA_TYPE_DATA, returns an empty structure.
1252 // TODO(orphis): Make pure virtual when all subclasses implement it.
1253 virtual RtpCapabilities GetRtpReceiverCapabilities(
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001254 cricket::MediaType kind) const;
Florent Castelli72b751a2018-06-28 14:09:33 +02001255
Seth Hampson845e8782018-03-02 11:34:10 -08001256 virtual rtc::scoped_refptr<MediaStreamInterface> CreateLocalMediaStream(
1257 const std::string& stream_id) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001258
deadbeefe814a0d2017-02-25 18:15:09 -08001259 // Creates an AudioSourceInterface.
deadbeefb10f32f2017-02-08 01:38:21 -08001260 // |options| decides audio processing settings.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +00001261 virtual rtc::scoped_refptr<AudioSourceInterface> CreateAudioSource(
htaa2a49d92016-03-04 02:51:39 -08001262 const cricket::AudioOptions& options) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001263
deadbeef39e14da2017-02-13 09:49:58 -08001264 // Creates a VideoTrackSourceInterface from |capturer|.
1265 // TODO(deadbeef): We should aim to remove cricket::VideoCapturer from the
1266 // API. It's mainly used as a wrapper around webrtc's provided
1267 // platform-specific capturers, but these should be refactored to use
1268 // VideoTrackSourceInterface directly.
deadbeef112b2e92017-02-10 20:13:37 -08001269 // TODO(deadbeef): Make pure virtual once downstream mock PC factory classes
1270 // are updated.
perkja3ede6c2016-03-08 01:27:48 +01001271 virtual rtc::scoped_refptr<VideoTrackSourceInterface> CreateVideoSource(
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001272 std::unique_ptr<cricket::VideoCapturer> capturer);
deadbeef112b2e92017-02-10 20:13:37 -08001273
htaa2a49d92016-03-04 02:51:39 -08001274 // A video source creator that allows selection of resolution and frame rate.
deadbeef8d60a942017-02-27 14:47:33 -08001275 // |constraints| decides video resolution and frame rate but can be null.
1276 // In the null case, use the version above.
deadbeef112b2e92017-02-10 20:13:37 -08001277 //
1278 // |constraints| is only used for the invocation of this method, and can
1279 // safely be destroyed afterwards.
1280 virtual rtc::scoped_refptr<VideoTrackSourceInterface> CreateVideoSource(
1281 std::unique_ptr<cricket::VideoCapturer> capturer,
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001282 const MediaConstraintsInterface* constraints);
deadbeef112b2e92017-02-10 20:13:37 -08001283
1284 // Deprecated; please use the versions that take unique_ptrs above.
1285 // TODO(deadbeef): Remove these once safe to do so.
1286 virtual rtc::scoped_refptr<VideoTrackSourceInterface> CreateVideoSource(
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001287 cricket::VideoCapturer* capturer);
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001288 // Creates a new local VideoTrack. The same |source| can be used in several
1289 // tracks.
perkja3ede6c2016-03-08 01:27:48 +01001290 virtual rtc::scoped_refptr<VideoTrackInterface> CreateVideoTrack(
1291 const std::string& label,
1292 VideoTrackSourceInterface* source) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001293
deadbeef8d60a942017-02-27 14:47:33 -08001294 // Creates an new AudioTrack. At the moment |source| can be null.
Yves Gerey665174f2018-06-19 15:03:05 +02001295 virtual rtc::scoped_refptr<AudioTrackInterface> CreateAudioTrack(
1296 const std::string& label,
1297 AudioSourceInterface* source) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001298
wu@webrtc.orga9890802013-12-13 00:21:03 +00001299 // Starts AEC dump using existing file. Takes ownership of |file| and passes
1300 // it on to VoiceEngine (via other objects) immediately, which will take
wu@webrtc.orga8910d22014-01-23 22:12:45 +00001301 // the ownerhip. If the operation fails, the file will be closed.
ivocd66b44d2016-01-15 03:06:36 -08001302 // A maximum file size in bytes can be specified. When the file size limit is
1303 // reached, logging is stopped automatically. If max_size_bytes is set to a
1304 // value <= 0, no limit will be used, and logging will continue until the
1305 // StopAecDump function is called.
1306 virtual bool StartAecDump(rtc::PlatformFile file, int64_t max_size_bytes) = 0;
wu@webrtc.orga9890802013-12-13 00:21:03 +00001307
ivoc797ef122015-10-22 03:25:41 -07001308 // Stops logging the AEC dump.
1309 virtual void StopAecDump() = 0;
1310
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001311 protected:
1312 // Dtor and ctor protected as objects shouldn't be created or deleted via
1313 // this interface.
1314 PeerConnectionFactoryInterface() {}
Mirko Bonadei79eb4dd2018-07-19 10:39:30 +02001315 ~PeerConnectionFactoryInterface() override = default;
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001316};
1317
Anders Carlsson50635032018-08-09 15:01:10 -07001318#if defined(USE_BUILTIN_SW_CODECS)
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001319// Create a new instance of PeerConnectionFactoryInterface.
Taylor Brandstettera8415fe2016-03-23 10:38:07 -07001320//
1321// This method relies on the thread it's called on as the "signaling thread"
1322// for the PeerConnectionFactory it creates.
1323//
1324// As such, if the current thread is not already running an rtc::Thread message
1325// loop, an application using this method must eventually either call
1326// rtc::Thread::Current()->Run(), or call
1327// rtc::Thread::Current()->ProcessMessages() within the application's own
1328// message loop.
kwiberg1e4e8cb2017-01-31 01:48:08 -08001329rtc::scoped_refptr<PeerConnectionFactoryInterface> CreatePeerConnectionFactory(
1330 rtc::scoped_refptr<AudioEncoderFactory> audio_encoder_factory,
1331 rtc::scoped_refptr<AudioDecoderFactory> audio_decoder_factory);
1332
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001333// Create a new instance of PeerConnectionFactoryInterface.
Taylor Brandstettera8415fe2016-03-23 10:38:07 -07001334//
danilchape9021a32016-05-17 01:52:02 -07001335// |network_thread|, |worker_thread| and |signaling_thread| are
1336// the only mandatory parameters.
Taylor Brandstettera8415fe2016-03-23 10:38:07 -07001337//
deadbeefb10f32f2017-02-08 01:38:21 -08001338// If non-null, a reference is added to |default_adm|, and ownership of
1339// |video_encoder_factory| and |video_decoder_factory| is transferred to the
1340// returned factory.
1341// TODO(deadbeef): Use rtc::scoped_refptr<> and std::unique_ptr<> to make this
1342// ownership transfer and ref counting more obvious.
danilchape9021a32016-05-17 01:52:02 -07001343rtc::scoped_refptr<PeerConnectionFactoryInterface> CreatePeerConnectionFactory(
1344 rtc::Thread* network_thread,
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +00001345 rtc::Thread* worker_thread,
1346 rtc::Thread* signaling_thread,
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001347 AudioDeviceModule* default_adm,
kwiberg1e4e8cb2017-01-31 01:48:08 -08001348 rtc::scoped_refptr<AudioEncoderFactory> audio_encoder_factory,
1349 rtc::scoped_refptr<AudioDecoderFactory> audio_decoder_factory,
1350 cricket::WebRtcVideoEncoderFactory* video_encoder_factory,
1351 cricket::WebRtcVideoDecoderFactory* video_decoder_factory);
1352
peah17675ce2017-06-30 07:24:04 -07001353// Create a new instance of PeerConnectionFactoryInterface with optional
1354// external audio mixed and audio processing modules.
1355//
1356// If |audio_mixer| is null, an internal audio mixer will be created and used.
1357// If |audio_processing| is null, an internal audio processing module will be
1358// created and used.
1359rtc::scoped_refptr<PeerConnectionFactoryInterface> CreatePeerConnectionFactory(
1360 rtc::Thread* network_thread,
1361 rtc::Thread* worker_thread,
1362 rtc::Thread* signaling_thread,
1363 AudioDeviceModule* default_adm,
1364 rtc::scoped_refptr<AudioEncoderFactory> audio_encoder_factory,
1365 rtc::scoped_refptr<AudioDecoderFactory> audio_decoder_factory,
1366 cricket::WebRtcVideoEncoderFactory* video_encoder_factory,
1367 cricket::WebRtcVideoDecoderFactory* video_decoder_factory,
1368 rtc::scoped_refptr<AudioMixer> audio_mixer,
1369 rtc::scoped_refptr<AudioProcessing> audio_processing);
1370
Ying Wang0dd1b0a2018-02-20 12:50:27 +01001371// Create a new instance of PeerConnectionFactoryInterface with optional
1372// external audio mixer, audio processing, and fec controller modules.
1373//
1374// If |audio_mixer| is null, an internal audio mixer will be created and used.
1375// If |audio_processing| is null, an internal audio processing module will be
1376// created and used.
1377// If |fec_controller_factory| is null, an internal fec controller module will
1378// be created and used.
Sebastian Janssondfce03a2018-05-18 18:05:10 +02001379// If |network_controller_factory| is provided, it will be used if enabled via
1380// field trial.
Ying Wang0dd1b0a2018-02-20 12:50:27 +01001381rtc::scoped_refptr<PeerConnectionFactoryInterface> CreatePeerConnectionFactory(
1382 rtc::Thread* network_thread,
1383 rtc::Thread* worker_thread,
1384 rtc::Thread* signaling_thread,
1385 AudioDeviceModule* default_adm,
1386 rtc::scoped_refptr<AudioEncoderFactory> audio_encoder_factory,
1387 rtc::scoped_refptr<AudioDecoderFactory> audio_decoder_factory,
1388 cricket::WebRtcVideoEncoderFactory* video_encoder_factory,
1389 cricket::WebRtcVideoDecoderFactory* video_decoder_factory,
1390 rtc::scoped_refptr<AudioMixer> audio_mixer,
1391 rtc::scoped_refptr<AudioProcessing> audio_processing,
Sebastian Janssondfce03a2018-05-18 18:05:10 +02001392 std::unique_ptr<FecControllerFactoryInterface> fec_controller_factory,
1393 std::unique_ptr<NetworkControllerFactoryInterface>
1394 network_controller_factory = nullptr);
Anders Carlsson50635032018-08-09 15:01:10 -07001395#endif
Ying Wang0dd1b0a2018-02-20 12:50:27 +01001396
Magnus Jedvert58b03162017-09-15 19:02:47 +02001397// Create a new instance of PeerConnectionFactoryInterface with optional video
1398// codec factories. These video factories represents all video codecs, i.e. no
1399// extra internal video codecs will be added.
Anders Carlssonb3306882018-05-14 10:11:42 +02001400// When building WebRTC with rtc_use_builtin_sw_codecs = false, this is the
1401// only available CreatePeerConnectionFactory overload.
Magnus Jedvert58b03162017-09-15 19:02:47 +02001402rtc::scoped_refptr<PeerConnectionFactoryInterface> CreatePeerConnectionFactory(
1403 rtc::Thread* network_thread,
1404 rtc::Thread* worker_thread,
1405 rtc::Thread* signaling_thread,
1406 rtc::scoped_refptr<AudioDeviceModule> default_adm,
1407 rtc::scoped_refptr<AudioEncoderFactory> audio_encoder_factory,
1408 rtc::scoped_refptr<AudioDecoderFactory> audio_decoder_factory,
1409 std::unique_ptr<VideoEncoderFactory> video_encoder_factory,
1410 std::unique_ptr<VideoDecoderFactory> video_decoder_factory,
1411 rtc::scoped_refptr<AudioMixer> audio_mixer,
1412 rtc::scoped_refptr<AudioProcessing> audio_processing);
1413
Anders Carlsson50635032018-08-09 15:01:10 -07001414#if defined(USE_BUILTIN_SW_CODECS)
gyzhou95aa9642016-12-13 14:06:26 -08001415// Create a new instance of PeerConnectionFactoryInterface with external audio
1416// mixer.
1417//
1418// If |audio_mixer| is null, an internal audio mixer will be created and used.
1419rtc::scoped_refptr<PeerConnectionFactoryInterface>
1420CreatePeerConnectionFactoryWithAudioMixer(
1421 rtc::Thread* network_thread,
1422 rtc::Thread* worker_thread,
1423 rtc::Thread* signaling_thread,
1424 AudioDeviceModule* default_adm,
kwiberg1e4e8cb2017-01-31 01:48:08 -08001425 rtc::scoped_refptr<AudioEncoderFactory> audio_encoder_factory,
1426 rtc::scoped_refptr<AudioDecoderFactory> audio_decoder_factory,
1427 cricket::WebRtcVideoEncoderFactory* video_encoder_factory,
1428 cricket::WebRtcVideoDecoderFactory* video_decoder_factory,
1429 rtc::scoped_refptr<AudioMixer> audio_mixer);
1430
danilchape9021a32016-05-17 01:52:02 -07001431// Create a new instance of PeerConnectionFactoryInterface.
1432// Same thread is used as worker and network thread.
danilchape9021a32016-05-17 01:52:02 -07001433inline rtc::scoped_refptr<PeerConnectionFactoryInterface>
1434CreatePeerConnectionFactory(
1435 rtc::Thread* worker_and_network_thread,
1436 rtc::Thread* signaling_thread,
1437 AudioDeviceModule* default_adm,
kwiberg1e4e8cb2017-01-31 01:48:08 -08001438 rtc::scoped_refptr<AudioEncoderFactory> audio_encoder_factory,
1439 rtc::scoped_refptr<AudioDecoderFactory> audio_decoder_factory,
1440 cricket::WebRtcVideoEncoderFactory* video_encoder_factory,
1441 cricket::WebRtcVideoDecoderFactory* video_decoder_factory) {
1442 return CreatePeerConnectionFactory(
1443 worker_and_network_thread, worker_and_network_thread, signaling_thread,
1444 default_adm, audio_encoder_factory, audio_decoder_factory,
1445 video_encoder_factory, video_decoder_factory);
1446}
Anders Carlsson50635032018-08-09 15:01:10 -07001447#endif
kwiberg1e4e8cb2017-01-31 01:48:08 -08001448
zhihuang38ede132017-06-15 12:52:32 -07001449// This is a lower-level version of the CreatePeerConnectionFactory functions
1450// above. It's implemented in the "peerconnection" build target, whereas the
1451// above methods are only implemented in the broader "libjingle_peerconnection"
1452// build target, which pulls in the implementations of every module webrtc may
1453// use.
1454//
1455// If an application knows it will only require certain modules, it can reduce
1456// webrtc's impact on its binary size by depending only on the "peerconnection"
1457// target and the modules the application requires, using
1458// CreateModularPeerConnectionFactory instead of one of the
1459// CreatePeerConnectionFactory methods above. For example, if an application
1460// only uses WebRTC for audio, it can pass in null pointers for the
1461// video-specific interfaces, and omit the corresponding modules from its
1462// build.
1463//
1464// If |network_thread| or |worker_thread| are null, the PeerConnectionFactory
1465// will create the necessary thread internally. If |signaling_thread| is null,
1466// the PeerConnectionFactory will use the thread on which this method is called
1467// as the signaling thread, wrapping it in an rtc::Thread object if needed.
1468//
1469// If non-null, a reference is added to |default_adm|, and ownership of
1470// |video_encoder_factory| and |video_decoder_factory| is transferred to the
1471// returned factory.
1472//
peaha9cc40b2017-06-29 08:32:09 -07001473// If |audio_mixer| is null, an internal audio mixer will be created and used.
1474//
zhihuang38ede132017-06-15 12:52:32 -07001475// TODO(deadbeef): Use rtc::scoped_refptr<> and std::unique_ptr<> to make this
1476// ownership transfer and ref counting more obvious.
1477//
1478// TODO(deadbeef): Encapsulate these modules in a struct, so that when a new
1479// module is inevitably exposed, we can just add a field to the struct instead
1480// of adding a whole new CreateModularPeerConnectionFactory overload.
1481rtc::scoped_refptr<PeerConnectionFactoryInterface>
1482CreateModularPeerConnectionFactory(
1483 rtc::Thread* network_thread,
1484 rtc::Thread* worker_thread,
1485 rtc::Thread* signaling_thread,
zhihuang38ede132017-06-15 12:52:32 -07001486 std::unique_ptr<cricket::MediaEngineInterface> media_engine,
1487 std::unique_ptr<CallFactoryInterface> call_factory,
1488 std::unique_ptr<RtcEventLogFactoryInterface> event_log_factory);
1489
Ying Wang0dd1b0a2018-02-20 12:50:27 +01001490rtc::scoped_refptr<PeerConnectionFactoryInterface>
1491CreateModularPeerConnectionFactory(
1492 rtc::Thread* network_thread,
1493 rtc::Thread* worker_thread,
1494 rtc::Thread* signaling_thread,
1495 std::unique_ptr<cricket::MediaEngineInterface> media_engine,
1496 std::unique_ptr<CallFactoryInterface> call_factory,
1497 std::unique_ptr<RtcEventLogFactoryInterface> event_log_factory,
Sebastian Janssondfce03a2018-05-18 18:05:10 +02001498 std::unique_ptr<FecControllerFactoryInterface> fec_controller_factory,
1499 std::unique_ptr<NetworkControllerFactoryInterface>
1500 network_controller_factory = nullptr);
Ying Wang0dd1b0a2018-02-20 12:50:27 +01001501
Benjamin Wright5234a492018-05-29 15:04:32 -07001502rtc::scoped_refptr<PeerConnectionFactoryInterface>
1503CreateModularPeerConnectionFactory(
1504 PeerConnectionFactoryDependencies dependencies);
1505
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001506} // namespace webrtc
1507
Mirko Bonadei92ea95e2017-09-15 06:47:31 +02001508#endif // API_PEERCONNECTIONINTERFACE_H_