blob: 624c67f9cba562bbc111fb79fe80ca2d6eafe31c [file] [log] [blame]
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001/*
kjellanderb24317b2016-02-10 07:54:43 -08002 * Copyright 2012 The WebRTC project authors. All Rights Reserved.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00003 *
kjellanderb24317b2016-02-10 07:54:43 -08004 * Use of this source code is governed by a BSD-style license
5 * that can be found in the LICENSE file in the root of the source
6 * tree. An additional intellectual property rights grant can be found
7 * in the file PATENTS. All contributing project authors may
8 * be found in the AUTHORS file in the root of the source tree.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00009 */
10
11// This file contains the PeerConnection interface as defined in
12// http://dev.w3.org/2011/webrtc/editor/webrtc.html#peer-to-peer-connections.
13// Applications must use this interface to implement peerconnection.
14// PeerConnectionFactory class provides factory methods to create
15// peerconnection, mediastream and media tracks objects.
16//
17// The Following steps are needed to setup a typical call using Jsep.
18// 1. Create a PeerConnectionFactoryInterface. Check constructors for more
19// information about input parameters.
20// 2. Create a PeerConnection object. Provide a configuration string which
21// points either to stun or turn server to generate ICE candidates and provide
22// an object that implements the PeerConnectionObserver interface.
23// 3. Create local MediaStream and MediaTracks using the PeerConnectionFactory
24// and add it to PeerConnection by calling AddStream.
25// 4. Create an offer and serialize it and send it to the remote peer.
26// 5. Once an ice candidate have been found PeerConnection will call the
27// observer function OnIceCandidate. The candidates must also be serialized and
28// sent to the remote peer.
29// 6. Once an answer is received from the remote peer, call
30// SetLocalSessionDescription with the offer and SetRemoteSessionDescription
31// with the remote answer.
32// 7. Once a remote candidate is received from the remote peer, provide it to
33// the peerconnection by calling AddIceCandidate.
34
35
36// The Receiver of a call can decide to accept or reject the call.
37// This decision will be taken by the application not peerconnection.
38// If application decides to accept the call
39// 1. Create PeerConnectionFactoryInterface if it doesn't exist.
40// 2. Create a new PeerConnection.
41// 3. Provide the remote offer to the new PeerConnection object by calling
42// SetRemoteSessionDescription.
43// 4. Generate an answer to the remote offer by calling CreateAnswer and send it
44// back to the remote peer.
45// 5. Provide the local answer to the new PeerConnection by calling
46// SetLocalSessionDescription with the answer.
47// 6. Provide the remote ice candidates by calling AddIceCandidate.
48// 7. Once a candidate have been found PeerConnection will call the observer
49// function OnIceCandidate. Send these candidates to the remote peer.
50
Henrik Kjellander15583c12016-02-10 10:53:12 +010051#ifndef WEBRTC_API_PEERCONNECTIONINTERFACE_H_
52#define WEBRTC_API_PEERCONNECTIONINTERFACE_H_
henrike@webrtc.org28e20752013-07-10 00:45:36 +000053
kwibergd1fe2812016-04-27 06:47:29 -070054#include <memory>
henrike@webrtc.org28e20752013-07-10 00:45:36 +000055#include <string>
kwiberg0eb15ed2015-12-17 03:04:15 -080056#include <utility>
henrike@webrtc.org28e20752013-07-10 00:45:36 +000057#include <vector>
58
Henrik Kjellander15583c12016-02-10 10:53:12 +010059#include "webrtc/api/datachannelinterface.h"
Henrik Kjellander15583c12016-02-10 10:53:12 +010060#include "webrtc/api/dtmfsenderinterface.h"
61#include "webrtc/api/jsep.h"
62#include "webrtc/api/mediastreaminterface.h"
63#include "webrtc/api/rtpreceiverinterface.h"
64#include "webrtc/api/rtpsenderinterface.h"
65#include "webrtc/api/statstypes.h"
66#include "webrtc/api/umametrics.h"
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +000067#include "webrtc/base/fileutils.h"
phoglund@webrtc.org006521d2015-02-12 09:23:59 +000068#include "webrtc/base/network.h"
Henrik Boström87713d02015-08-25 09:53:21 +020069#include "webrtc/base/rtccertificate.h"
Henrik Boströmd03c23b2016-06-01 11:44:18 +020070#include "webrtc/base/rtccertificategenerator.h"
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +000071#include "webrtc/base/socketaddress.h"
kjellandera96e2d72016-02-04 23:52:28 -080072#include "webrtc/base/sslstreamadapter.h"
nissec36b31b2016-04-11 23:25:29 -070073#include "webrtc/media/base/mediachannel.h"
deadbeef41b07982015-12-01 15:01:24 -080074#include "webrtc/p2p/base/portallocator.h"
henrike@webrtc.org28e20752013-07-10 00:45:36 +000075
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +000076namespace rtc {
jiayl@webrtc.org61e00b02015-03-04 22:17:38 +000077class SSLIdentity;
henrike@webrtc.org28e20752013-07-10 00:45:36 +000078class Thread;
79}
80
81namespace cricket {
henrike@webrtc.org28e20752013-07-10 00:45:36 +000082class WebRtcVideoDecoderFactory;
83class WebRtcVideoEncoderFactory;
84}
85
86namespace webrtc {
87class AudioDeviceModule;
88class MediaConstraintsInterface;
89
90// MediaStream container interface.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +000091class StreamCollectionInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +000092 public:
93 // TODO(ronghuawu): Update the function names to c++ style, e.g. find -> Find.
94 virtual size_t count() = 0;
95 virtual MediaStreamInterface* at(size_t index) = 0;
96 virtual MediaStreamInterface* find(const std::string& label) = 0;
97 virtual MediaStreamTrackInterface* FindAudioTrack(
98 const std::string& id) = 0;
99 virtual MediaStreamTrackInterface* FindVideoTrack(
100 const std::string& id) = 0;
101
102 protected:
103 // Dtor protected as objects shouldn't be deleted via this interface.
104 ~StreamCollectionInterface() {}
105};
106
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000107class StatsObserver : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000108 public:
tommi@webrtc.orge2e199b2014-12-15 13:22:54 +0000109 virtual void OnComplete(const StatsReports& reports) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000110
111 protected:
112 virtual ~StatsObserver() {}
113};
114
guoweis@webrtc.org7169afd2014-12-04 17:59:29 +0000115class MetricsObserverInterface : public rtc::RefCountInterface {
buildbot@webrtc.org1567b8c2014-05-08 19:54:16 +0000116 public:
Guo-wei Shieh3d564c12015-08-19 16:51:15 -0700117
118 // |type| is the type of the enum counter to be incremented. |counter|
119 // is the particular counter in that type. |counter_max| is the next sequence
120 // number after the highest counter.
121 virtual void IncrementEnumCounter(PeerConnectionEnumCounterType type,
122 int counter,
123 int counter_max) {}
124
Guo-wei Shieh456696a2015-09-30 21:48:54 -0700125 // This is used to handle sparse counters like SSL cipher suites.
126 // TODO(guoweis): Remove the implementation once the dependency's interface
127 // definition is updated.
128 virtual void IncrementSparseEnumCounter(PeerConnectionEnumCounterType type,
129 int counter) {
130 IncrementEnumCounter(type, counter, 0 /* Ignored */);
131 }
132
guoweis@webrtc.org7169afd2014-12-04 17:59:29 +0000133 virtual void AddHistogramSample(PeerConnectionMetricsName type,
mallinath@webrtc.orgd37bcfa2014-05-12 23:10:18 +0000134 int value) = 0;
buildbot@webrtc.org1567b8c2014-05-08 19:54:16 +0000135
136 protected:
guoweis@webrtc.org7169afd2014-12-04 17:59:29 +0000137 virtual ~MetricsObserverInterface() {}
buildbot@webrtc.org1567b8c2014-05-08 19:54:16 +0000138};
139
guoweis@webrtc.org7169afd2014-12-04 17:59:29 +0000140typedef MetricsObserverInterface UMAObserver;
141
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000142class PeerConnectionInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000143 public:
144 // See http://dev.w3.org/2011/webrtc/editor/webrtc.html#state-definitions .
145 enum SignalingState {
146 kStable,
147 kHaveLocalOffer,
148 kHaveLocalPrAnswer,
149 kHaveRemoteOffer,
150 kHaveRemotePrAnswer,
151 kClosed,
152 };
153
perkj68343a82016-08-29 23:51:13 -0700154 // TODO(bemasc): Remove IceState when callers are changed to
155 // IceConnection/GatheringState.
156 enum IceState {
157 kIceNew,
158 kIceGathering,
159 kIceWaiting,
160 kIceChecking,
161 kIceConnected,
162 kIceCompleted,
163 kIceFailed,
164 kIceClosed,
165 };
166
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000167 enum IceGatheringState {
168 kIceGatheringNew,
169 kIceGatheringGathering,
170 kIceGatheringComplete
171 };
172
173 enum IceConnectionState {
174 kIceConnectionNew,
175 kIceConnectionChecking,
176 kIceConnectionConnected,
177 kIceConnectionCompleted,
178 kIceConnectionFailed,
179 kIceConnectionDisconnected,
180 kIceConnectionClosed,
Guo-wei Shieh3d564c12015-08-19 16:51:15 -0700181 kIceConnectionMax,
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000182 };
183
184 struct IceServer {
Joachim Bauch7c4e7452015-05-28 23:06:30 +0200185 // TODO(jbauch): Remove uri when all code using it has switched to urls.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000186 std::string uri;
Joachim Bauch7c4e7452015-05-28 23:06:30 +0200187 std::vector<std::string> urls;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000188 std::string username;
189 std::string password;
190 };
191 typedef std::vector<IceServer> IceServers;
192
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000193 enum IceTransportsType {
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000194 // TODO(pthatcher): Rename these kTransporTypeXXX, but update
195 // Chromium at the same time.
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000196 kNone,
197 kRelay,
198 kNoHost,
199 kAll
200 };
201
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000202 // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-08#section-4.1.1
203 enum BundlePolicy {
204 kBundlePolicyBalanced,
205 kBundlePolicyMaxBundle,
206 kBundlePolicyMaxCompat
207 };
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000208
Peter Thatcheraf55ccc2015-05-21 07:48:41 -0700209 // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-09#section-4.1.1
210 enum RtcpMuxPolicy {
211 kRtcpMuxPolicyNegotiate,
212 kRtcpMuxPolicyRequire,
213 };
214
Jiayang Liucac1b382015-04-30 12:35:24 -0700215 enum TcpCandidatePolicy {
216 kTcpCandidatePolicyEnabled,
217 kTcpCandidatePolicyDisabled
218 };
219
honghaiz60347052016-05-31 18:29:12 -0700220 enum CandidateNetworkPolicy {
221 kCandidateNetworkPolicyAll,
222 kCandidateNetworkPolicyLowCost
223 };
224
honghaiz1f429e32015-09-28 07:57:34 -0700225 enum ContinualGatheringPolicy {
226 GATHER_ONCE,
227 GATHER_CONTINUALLY
228 };
229
Henrik Boström87713d02015-08-25 09:53:21 +0200230 // TODO(hbos): Change into class with private data and public getters.
nissec36b31b2016-04-11 23:25:29 -0700231 // TODO(nisse): In particular, accessing fields directly from an
232 // application is brittle, since the organization mirrors the
233 // organization of the implementation, which isn't stable. So we
234 // need getters and setters at least for fields which applications
235 // are interested in.
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000236 struct RTCConfiguration {
Niels Möller71bdda02016-03-31 12:59:59 +0200237 // This struct is subject to reorganization, both for naming
238 // consistency, and to group settings to match where they are used
239 // in the implementation. To do that, we need getter and setter
240 // methods for all settings which are of interest to applications,
241 // Chrome in particular.
242
Honghai Zhangbfd398c2016-08-30 22:07:42 -0700243 // A configuration that is safer to use, despite it may not have the best
244 // performance.
245 static RTCConfiguration SafeConfiguration() { return RTCConfiguration(); }
246
247 // An aggressive configuration that has better performance, although it
248 // may be riskier and may need extra support in the application.
249 static RTCConfiguration AggressiveConfiguration() {
250 RTCConfiguration config;
251 config.redetermine_role_on_ice_restart = false;
252 return config;
253 }
254
nissec36b31b2016-04-11 23:25:29 -0700255 bool dscp() { return media_config.enable_dscp; }
256 void set_dscp(bool enable) { media_config.enable_dscp = enable; }
Niels Möller71bdda02016-03-31 12:59:59 +0200257
258 // TODO(nisse): The corresponding flag in MediaConfig and
259 // elsewhere should be renamed enable_cpu_adaptation.
nissec36b31b2016-04-11 23:25:29 -0700260 bool cpu_adaptation() {
261 return media_config.video.enable_cpu_overuse_detection;
262 }
Niels Möller71bdda02016-03-31 12:59:59 +0200263 void set_cpu_adaptation(bool enable) {
nissec36b31b2016-04-11 23:25:29 -0700264 media_config.video.enable_cpu_overuse_detection = enable;
Niels Möller71bdda02016-03-31 12:59:59 +0200265 }
266
nissec36b31b2016-04-11 23:25:29 -0700267 bool suspend_below_min_bitrate() {
268 return media_config.video.suspend_below_min_bitrate;
269 }
Niels Möller71bdda02016-03-31 12:59:59 +0200270 void set_suspend_below_min_bitrate(bool enable) {
nissec36b31b2016-04-11 23:25:29 -0700271 media_config.video.suspend_below_min_bitrate = enable;
Niels Möller71bdda02016-03-31 12:59:59 +0200272 }
273
274 // TODO(nisse): The negation in the corresponding MediaConfig
275 // attribute is inconsistent, and it should be renamed at some
276 // point.
nissec36b31b2016-04-11 23:25:29 -0700277 bool prerenderer_smoothing() {
278 return !media_config.video.disable_prerenderer_smoothing;
279 }
Niels Möller71bdda02016-03-31 12:59:59 +0200280 void set_prerenderer_smoothing(bool enable) {
nissec36b31b2016-04-11 23:25:29 -0700281 media_config.video.disable_prerenderer_smoothing = !enable;
Niels Möller71bdda02016-03-31 12:59:59 +0200282 }
283
honghaiz4edc39c2015-09-01 09:53:56 -0700284 static const int kUndefined = -1;
285 // Default maximum number of packets in the audio jitter buffer.
286 static const int kAudioJitterBufferMaxPackets = 50;
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000287 // TODO(pthatcher): Rename this ice_transport_type, but update
288 // Chromium at the same time.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700289 IceTransportsType type = kAll;
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000290 // TODO(pthatcher): Rename this ice_servers, but update Chromium
291 // at the same time.
292 IceServers servers;
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700293 BundlePolicy bundle_policy = kBundlePolicyBalanced;
294 RtcpMuxPolicy rtcp_mux_policy = kRtcpMuxPolicyNegotiate;
295 TcpCandidatePolicy tcp_candidate_policy = kTcpCandidatePolicyEnabled;
honghaiz60347052016-05-31 18:29:12 -0700296 CandidateNetworkPolicy candidate_network_policy =
297 kCandidateNetworkPolicyAll;
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700298 int audio_jitter_buffer_max_packets = kAudioJitterBufferMaxPackets;
299 bool audio_jitter_buffer_fast_accelerate = false;
300 int ice_connection_receiving_timeout = kUndefined; // ms
301 int ice_backup_candidate_pair_ping_interval = kUndefined; // ms
302 ContinualGatheringPolicy continual_gathering_policy = GATHER_ONCE;
Henrik Boström87713d02015-08-25 09:53:21 +0200303 std::vector<rtc::scoped_refptr<rtc::RTCCertificate>> certificates;
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700304 bool prioritize_most_likely_ice_candidate_pairs = false;
nissec36b31b2016-04-11 23:25:29 -0700305 struct cricket::MediaConfig media_config;
htaa2a49d92016-03-04 02:51:39 -0800306 // Flags corresponding to values set by constraint flags.
307 // rtc::Optional flags can be "missing", in which case the webrtc
308 // default applies.
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700309 bool disable_ipv6 = false;
310 bool enable_rtp_data_channel = false;
zhihuang9763d562016-08-05 11:14:50 -0700311 bool enable_quic = false;
htaa2a49d92016-03-04 02:51:39 -0800312 rtc::Optional<int> screencast_min_bitrate;
313 rtc::Optional<bool> combined_audio_video_bwe;
314 rtc::Optional<bool> enable_dtls_srtp;
Taylor Brandstettera1c30352016-05-13 08:15:11 -0700315 int ice_candidate_pool_size = 0;
Honghai Zhangb9e7b4a2016-06-30 20:52:02 -0700316 bool prune_turn_ports = false;
Taylor Brandstettere9851112016-07-01 11:11:13 -0700317 // If set to true, this means the ICE transport should presume TURN-to-TURN
318 // candidate pairs will succeed, even before a binding response is received.
319 bool presume_writable_when_fully_relayed = false;
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700320 // If true, "renomination" will be added to the ice options in the transport
321 // description.
322 bool enable_ice_renomination = false;
Honghai Zhangbfd398c2016-08-30 22:07:42 -0700323 // If true, ICE role is redetermined when peerconnection sets a local
324 // transport description that indicates an ICE restart.
325 bool redetermine_role_on_ice_restart = true;
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000326 };
327
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000328 struct RTCOfferAnswerOptions {
329 static const int kUndefined = -1;
330 static const int kMaxOfferToReceiveMedia = 1;
331
332 // The default value for constraint offerToReceiveX:true.
333 static const int kOfferToReceiveMediaTrue = 1;
334
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700335 int offer_to_receive_video = kUndefined;
336 int offer_to_receive_audio = kUndefined;
337 bool voice_activity_detection = true;
338 bool ice_restart = false;
339 bool use_rtp_mux = true;
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000340
Honghai Zhang4cedf2b2016-08-31 08:18:11 -0700341 RTCOfferAnswerOptions() = default;
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000342
343 RTCOfferAnswerOptions(int offer_to_receive_video,
344 int offer_to_receive_audio,
345 bool voice_activity_detection,
346 bool ice_restart,
347 bool use_rtp_mux)
348 : offer_to_receive_video(offer_to_receive_video),
349 offer_to_receive_audio(offer_to_receive_audio),
350 voice_activity_detection(voice_activity_detection),
351 ice_restart(ice_restart),
352 use_rtp_mux(use_rtp_mux) {}
353 };
354
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000355 // Used by GetStats to decide which stats to include in the stats reports.
356 // |kStatsOutputLevelStandard| includes the standard stats for Javascript API;
357 // |kStatsOutputLevelDebug| includes both the standard stats and additional
358 // stats for debugging purposes.
359 enum StatsOutputLevel {
360 kStatsOutputLevelStandard,
361 kStatsOutputLevelDebug,
362 };
363
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000364 // Accessor methods to active local streams.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000365 virtual rtc::scoped_refptr<StreamCollectionInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000366 local_streams() = 0;
367
368 // Accessor methods to remote streams.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000369 virtual rtc::scoped_refptr<StreamCollectionInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000370 remote_streams() = 0;
371
372 // Add a new MediaStream to be sent on this PeerConnection.
373 // Note that a SessionDescription negotiation is needed before the
374 // remote peer can receive the stream.
perkj@webrtc.orgfd0efb62014-11-06 12:16:36 +0000375 virtual bool AddStream(MediaStreamInterface* stream) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000376
377 // Remove a MediaStream from this PeerConnection.
378 // Note that a SessionDescription negotiation is need before the
379 // remote peer is notified.
380 virtual void RemoveStream(MediaStreamInterface* stream) = 0;
381
deadbeefe1f9d832016-01-14 15:35:42 -0800382 // TODO(deadbeef): Make the following two methods pure virtual once
383 // implemented by all subclasses of PeerConnectionInterface.
384 // Add a new MediaStreamTrack to be sent on this PeerConnection.
385 // |streams| indicates which stream labels the track should be associated
386 // with.
387 virtual rtc::scoped_refptr<RtpSenderInterface> AddTrack(
388 MediaStreamTrackInterface* track,
389 std::vector<MediaStreamInterface*> streams) {
390 return nullptr;
391 }
392
393 // Remove an RtpSender from this PeerConnection.
394 // Returns true on success.
395 virtual bool RemoveTrack(RtpSenderInterface* sender) {
396 return false;
397 }
398
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000399 // Returns pointer to the created DtmfSender on success.
400 // Otherwise returns NULL.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000401 virtual rtc::scoped_refptr<DtmfSenderInterface> CreateDtmfSender(
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000402 AudioTrackInterface* track) = 0;
403
deadbeef70ab1a12015-09-28 16:53:55 -0700404 // TODO(deadbeef): Make these pure virtual once all subclasses implement them.
deadbeeffac06552015-11-25 11:26:01 -0800405 // |kind| must be "audio" or "video".
deadbeefbd7d8f72015-12-18 16:58:44 -0800406 // |stream_id| is used to populate the msid attribute; if empty, one will
407 // be generated automatically.
deadbeeffac06552015-11-25 11:26:01 -0800408 virtual rtc::scoped_refptr<RtpSenderInterface> CreateSender(
deadbeefbd7d8f72015-12-18 16:58:44 -0800409 const std::string& kind,
410 const std::string& stream_id) {
deadbeeffac06552015-11-25 11:26:01 -0800411 return rtc::scoped_refptr<RtpSenderInterface>();
412 }
413
deadbeef70ab1a12015-09-28 16:53:55 -0700414 virtual std::vector<rtc::scoped_refptr<RtpSenderInterface>> GetSenders()
415 const {
416 return std::vector<rtc::scoped_refptr<RtpSenderInterface>>();
417 }
418
419 virtual std::vector<rtc::scoped_refptr<RtpReceiverInterface>> GetReceivers()
420 const {
421 return std::vector<rtc::scoped_refptr<RtpReceiverInterface>>();
422 }
423
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000424 virtual bool GetStats(StatsObserver* observer,
425 MediaStreamTrackInterface* track,
426 StatsOutputLevel level) = 0;
427
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000428 virtual rtc::scoped_refptr<DataChannelInterface> CreateDataChannel(
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000429 const std::string& label,
430 const DataChannelInit* config) = 0;
431
432 virtual const SessionDescriptionInterface* local_description() const = 0;
433 virtual const SessionDescriptionInterface* remote_description() const = 0;
434
435 // Create a new offer.
436 // The CreateSessionDescriptionObserver callback will be called when done.
437 virtual void CreateOffer(CreateSessionDescriptionObserver* observer,
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000438 const MediaConstraintsInterface* constraints) {}
439
440 // TODO(jiayl): remove the default impl and the old interface when chromium
441 // code is updated.
442 virtual void CreateOffer(CreateSessionDescriptionObserver* observer,
443 const RTCOfferAnswerOptions& options) {}
444
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000445 // Create an answer to an offer.
446 // The CreateSessionDescriptionObserver callback will be called when done.
447 virtual void CreateAnswer(CreateSessionDescriptionObserver* observer,
htaa2a49d92016-03-04 02:51:39 -0800448 const RTCOfferAnswerOptions& options) {}
449 // Deprecated - use version above.
450 // TODO(hta): Remove and remove default implementations when all callers
451 // are updated.
452 virtual void CreateAnswer(CreateSessionDescriptionObserver* observer,
453 const MediaConstraintsInterface* constraints) {}
454
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000455 // Sets the local session description.
456 // JsepInterface takes the ownership of |desc| even if it fails.
457 // The |observer| callback will be called when done.
458 virtual void SetLocalDescription(SetSessionDescriptionObserver* observer,
459 SessionDescriptionInterface* desc) = 0;
460 // Sets the remote session description.
461 // JsepInterface takes the ownership of |desc| even if it fails.
462 // The |observer| callback will be called when done.
463 virtual void SetRemoteDescription(SetSessionDescriptionObserver* observer,
464 SessionDescriptionInterface* desc) = 0;
465 // Restarts or updates the ICE Agent process of gathering local candidates
466 // and pinging remote candidates.
deadbeefa67696b2015-09-29 11:56:26 -0700467 // TODO(deadbeef): Remove once Chrome is moved over to SetConfiguration.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000468 virtual bool UpdateIce(const IceServers& configuration,
deadbeefa67696b2015-09-29 11:56:26 -0700469 const MediaConstraintsInterface* constraints) {
470 return false;
471 }
htaa2a49d92016-03-04 02:51:39 -0800472 virtual bool UpdateIce(const IceServers& configuration) { return false; }
deadbeefa67696b2015-09-29 11:56:26 -0700473 // Sets the PeerConnection's global configuration to |config|.
474 // Any changes to STUN/TURN servers or ICE candidate policy will affect the
475 // next gathering phase, and cause the next call to createOffer to generate
476 // new ICE credentials. Note that the BUNDLE and RTCP-multiplexing policies
477 // cannot be changed with this method.
478 // TODO(deadbeef): Make this pure virtual once all Chrome subclasses of
479 // PeerConnectionInterface implement it.
480 virtual bool SetConfiguration(
481 const PeerConnectionInterface::RTCConfiguration& config) {
482 return false;
483 }
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000484 // Provides a remote candidate to the ICE Agent.
485 // A copy of the |candidate| will be created and added to the remote
486 // description. So the caller of this method still has the ownership of the
487 // |candidate|.
488 // TODO(ronghuawu): Consider to change this so that the AddIceCandidate will
489 // take the ownership of the |candidate|.
490 virtual bool AddIceCandidate(const IceCandidateInterface* candidate) = 0;
491
Honghai Zhang7fb69db2016-03-14 11:59:18 -0700492 // Removes a group of remote candidates from the ICE agent.
493 virtual bool RemoveIceCandidates(
494 const std::vector<cricket::Candidate>& candidates) {
495 return false;
496 }
497
buildbot@webrtc.org1567b8c2014-05-08 19:54:16 +0000498 virtual void RegisterUMAObserver(UMAObserver* observer) = 0;
499
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000500 // Returns the current SignalingState.
501 virtual SignalingState signaling_state() = 0;
502
perkj68343a82016-08-29 23:51:13 -0700503 // TODO(bemasc): Remove ice_state when callers are changed to
504 // IceConnection/GatheringState.
505 // Returns the current IceState.
506 virtual IceState ice_state() = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000507 virtual IceConnectionState ice_connection_state() = 0;
508 virtual IceGatheringState ice_gathering_state() = 0;
509
ivoc14d5dbe2016-07-04 07:06:55 -0700510 // Starts RtcEventLog using existing file. Takes ownership of |file| and
511 // passes it on to Call, which will take the ownership. If the
512 // operation fails the file will be closed. The logging will stop
513 // automatically after 10 minutes have passed, or when the StopRtcEventLog
514 // function is called.
515 // TODO(ivoc): Make this pure virtual when Chrome is updated.
516 virtual bool StartRtcEventLog(rtc::PlatformFile file,
517 int64_t max_size_bytes) {
518 return false;
519 }
520
521 // Stops logging the RtcEventLog.
522 // TODO(ivoc): Make this pure virtual when Chrome is updated.
523 virtual void StopRtcEventLog() {}
524
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000525 // Terminates all media and closes the transport.
526 virtual void Close() = 0;
527
528 protected:
529 // Dtor protected as objects shouldn't be deleted via this interface.
530 ~PeerConnectionInterface() {}
531};
532
533// PeerConnection callback interface. Application should implement these
534// methods.
535class PeerConnectionObserver {
536 public:
537 enum StateType {
538 kSignalingState,
539 kIceState,
540 };
541
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000542 // Triggered when the SignalingState changed.
543 virtual void OnSignalingChange(
perkjdfb769d2016-02-09 03:09:43 -0800544 PeerConnectionInterface::SignalingState new_state) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000545
Taylor Brandstetter98cde262016-05-31 13:02:21 -0700546 // TODO(deadbeef): Once all subclasses override the scoped_refptr versions
547 // of the below three methods, make them pure virtual and remove the raw
548 // pointer version.
549
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000550 // Triggered when media is received on a new stream from remote peer.
Taylor Brandstetter98cde262016-05-31 13:02:21 -0700551 virtual void OnAddStream(rtc::scoped_refptr<MediaStreamInterface> stream) {}
552 // Deprecated; please use the version that uses a scoped_refptr.
553 virtual void OnAddStream(MediaStreamInterface* stream) {}
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000554
555 // Triggered when a remote peer close a stream.
Taylor Brandstetter98cde262016-05-31 13:02:21 -0700556 virtual void OnRemoveStream(rtc::scoped_refptr<MediaStreamInterface> stream) {
557 }
558 // Deprecated; please use the version that uses a scoped_refptr.
559 virtual void OnRemoveStream(MediaStreamInterface* stream) {}
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000560
Taylor Brandstetter98cde262016-05-31 13:02:21 -0700561 // Triggered when a remote peer opens a data channel.
562 virtual void OnDataChannel(
563 rtc::scoped_refptr<DataChannelInterface> data_channel){};
564 // Deprecated; please use the version that uses a scoped_refptr.
565 virtual void OnDataChannel(DataChannelInterface* data_channel) {}
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000566
Taylor Brandstetter98cde262016-05-31 13:02:21 -0700567 // Triggered when renegotiation is needed. For example, an ICE restart
568 // has begun.
fischman@webrtc.orgd7568a02014-01-13 22:04:12 +0000569 virtual void OnRenegotiationNeeded() = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000570
Taylor Brandstetter98cde262016-05-31 13:02:21 -0700571 // Called any time the IceConnectionState changes.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000572 virtual void OnIceConnectionChange(
perkjdfb769d2016-02-09 03:09:43 -0800573 PeerConnectionInterface::IceConnectionState new_state) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000574
Taylor Brandstetter98cde262016-05-31 13:02:21 -0700575 // Called any time the IceGatheringState changes.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000576 virtual void OnIceGatheringChange(
perkjdfb769d2016-02-09 03:09:43 -0800577 PeerConnectionInterface::IceGatheringState new_state) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000578
Taylor Brandstetter98cde262016-05-31 13:02:21 -0700579 // A new ICE candidate has been gathered.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000580 virtual void OnIceCandidate(const IceCandidateInterface* candidate) = 0;
581
Honghai Zhang7fb69db2016-03-14 11:59:18 -0700582 // Ice candidates have been removed.
583 // TODO(honghaiz): Make this a pure virtual method when all its subclasses
584 // implement it.
585 virtual void OnIceCandidatesRemoved(
586 const std::vector<cricket::Candidate>& candidates) {}
587
Peter Thatcher54360512015-07-08 11:08:35 -0700588 // Called when the ICE connection receiving status changes.
589 virtual void OnIceConnectionReceivingChange(bool receiving) {}
590
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000591 protected:
592 // Dtor protected as objects shouldn't be deleted via this interface.
593 ~PeerConnectionObserver() {}
594};
595
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000596// PeerConnectionFactoryInterface is the factory interface use for creating
597// PeerConnection, MediaStream and media tracks.
598// PeerConnectionFactoryInterface will create required libjingle threads,
599// socket and network manager factory classes for networking.
600// If an application decides to provide its own threads and network
601// implementation of these classes it should use the alternate
602// CreatePeerConnectionFactory method which accepts threads as input and use the
Taylor Brandstetter0c7e9f52015-12-29 14:14:52 -0800603// CreatePeerConnection version that takes a PortAllocator as an
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000604// argument.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000605class PeerConnectionFactoryInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000606 public:
wu@webrtc.org97077a32013-10-25 21:18:33 +0000607 class Options {
608 public:
Guo-wei Shieha7446d22016-01-11 15:27:03 -0800609 Options()
610 : disable_encryption(false),
611 disable_sctp_data_channels(false),
612 disable_network_monitor(false),
613 network_ignore_mask(rtc::kDefaultNetworkIgnoreMask),
jbauchcb560652016-08-04 05:20:32 -0700614 ssl_max_version(rtc::SSL_PROTOCOL_DTLS_12),
615 crypto_options(rtc::CryptoOptions::NoGcm()) {}
wu@webrtc.org97077a32013-10-25 21:18:33 +0000616 bool disable_encryption;
617 bool disable_sctp_data_channels;
honghaiz023f3ef2015-10-19 09:39:32 -0700618 bool disable_network_monitor;
phoglund@webrtc.org006521d2015-02-12 09:23:59 +0000619
620 // Sets the network types to ignore. For instance, calling this with
621 // ADAPTER_TYPE_ETHERNET | ADAPTER_TYPE_LOOPBACK will ignore Ethernet and
622 // loopback interfaces.
623 int network_ignore_mask;
Joachim Bauch04e5b492015-05-29 09:40:39 +0200624
625 // Sets the maximum supported protocol version. The highest version
626 // supported by both ends will be used for the connection, i.e. if one
627 // party supports DTLS 1.0 and the other DTLS 1.2, DTLS 1.0 will be used.
628 rtc::SSLProtocolVersion ssl_max_version;
jbauchcb560652016-08-04 05:20:32 -0700629
630 // Sets crypto related options, e.g. enabled cipher suites.
631 rtc::CryptoOptions crypto_options;
wu@webrtc.org97077a32013-10-25 21:18:33 +0000632 };
633
634 virtual void SetOptions(const Options& options) = 0;
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000635
deadbeef41b07982015-12-01 15:01:24 -0800636 virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection(
637 const PeerConnectionInterface::RTCConfiguration& configuration,
638 const MediaConstraintsInterface* constraints,
kwibergd1fe2812016-04-27 06:47:29 -0700639 std::unique_ptr<cricket::PortAllocator> allocator,
Henrik Boströmd03c23b2016-06-01 11:44:18 +0200640 std::unique_ptr<rtc::RTCCertificateGeneratorInterface> cert_generator,
hbosd7973cc2016-05-27 06:08:53 -0700641 PeerConnectionObserver* observer) = 0;
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000642
htaa2a49d92016-03-04 02:51:39 -0800643 virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection(
644 const PeerConnectionInterface::RTCConfiguration& configuration,
kwibergd1fe2812016-04-27 06:47:29 -0700645 std::unique_ptr<cricket::PortAllocator> allocator,
Henrik Boströmd03c23b2016-06-01 11:44:18 +0200646 std::unique_ptr<rtc::RTCCertificateGeneratorInterface> cert_generator,
hbosd7973cc2016-05-27 06:08:53 -0700647 PeerConnectionObserver* observer) = 0;
htaa2a49d92016-03-04 02:51:39 -0800648
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000649 virtual rtc::scoped_refptr<MediaStreamInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000650 CreateLocalMediaStream(const std::string& label) = 0;
651
652 // Creates a AudioSourceInterface.
653 // |constraints| decides audio processing settings but can be NULL.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000654 virtual rtc::scoped_refptr<AudioSourceInterface> CreateAudioSource(
htaa2a49d92016-03-04 02:51:39 -0800655 const cricket::AudioOptions& options) = 0;
656 // Deprecated - use version above.
657 virtual rtc::scoped_refptr<AudioSourceInterface> CreateAudioSource(
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000658 const MediaConstraintsInterface* constraints) = 0;
659
perkja3ede6c2016-03-08 01:27:48 +0100660 // Creates a VideoTrackSourceInterface. The new source take ownership of
htaa2a49d92016-03-04 02:51:39 -0800661 // |capturer|.
perkja3ede6c2016-03-08 01:27:48 +0100662 virtual rtc::scoped_refptr<VideoTrackSourceInterface> CreateVideoSource(
htaa2a49d92016-03-04 02:51:39 -0800663 cricket::VideoCapturer* capturer) = 0;
664 // A video source creator that allows selection of resolution and frame rate.
665 // |constraints| decides video resolution and frame rate but can
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000666 // be NULL.
htaa2a49d92016-03-04 02:51:39 -0800667 // In the NULL case, use the version above.
perkja3ede6c2016-03-08 01:27:48 +0100668 virtual rtc::scoped_refptr<VideoTrackSourceInterface> CreateVideoSource(
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000669 cricket::VideoCapturer* capturer,
670 const MediaConstraintsInterface* constraints) = 0;
671
672 // Creates a new local VideoTrack. The same |source| can be used in several
673 // tracks.
perkja3ede6c2016-03-08 01:27:48 +0100674 virtual rtc::scoped_refptr<VideoTrackInterface> CreateVideoTrack(
675 const std::string& label,
676 VideoTrackSourceInterface* source) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000677
678 // Creates an new AudioTrack. At the moment |source| can be NULL.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000679 virtual rtc::scoped_refptr<AudioTrackInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000680 CreateAudioTrack(const std::string& label,
681 AudioSourceInterface* source) = 0;
682
wu@webrtc.orga9890802013-12-13 00:21:03 +0000683 // Starts AEC dump using existing file. Takes ownership of |file| and passes
684 // it on to VoiceEngine (via other objects) immediately, which will take
wu@webrtc.orga8910d22014-01-23 22:12:45 +0000685 // the ownerhip. If the operation fails, the file will be closed.
ivocd66b44d2016-01-15 03:06:36 -0800686 // A maximum file size in bytes can be specified. When the file size limit is
687 // reached, logging is stopped automatically. If max_size_bytes is set to a
688 // value <= 0, no limit will be used, and logging will continue until the
689 // StopAecDump function is called.
690 virtual bool StartAecDump(rtc::PlatformFile file, int64_t max_size_bytes) = 0;
wu@webrtc.orga9890802013-12-13 00:21:03 +0000691
ivoc797ef122015-10-22 03:25:41 -0700692 // Stops logging the AEC dump.
693 virtual void StopAecDump() = 0;
694
ivoc14d5dbe2016-07-04 07:06:55 -0700695 // This function is deprecated and will be removed when Chrome is updated to
696 // use the equivalent function on PeerConnectionInterface.
697 // TODO(ivoc) Remove after Chrome is updated.
ivocc1513ee2016-05-13 08:30:39 -0700698 virtual bool StartRtcEventLog(rtc::PlatformFile file,
699 int64_t max_size_bytes) = 0;
ivoc14d5dbe2016-07-04 07:06:55 -0700700 // This function is deprecated and will be removed when Chrome is updated to
701 // use the equivalent function on PeerConnectionInterface.
702 // TODO(ivoc) Remove after Chrome is updated.
ivoc112a3d82015-10-16 02:22:18 -0700703 virtual bool StartRtcEventLog(rtc::PlatformFile file) = 0;
704
ivoc14d5dbe2016-07-04 07:06:55 -0700705 // This function is deprecated and will be removed when Chrome is updated to
706 // use the equivalent function on PeerConnectionInterface.
707 // TODO(ivoc) Remove after Chrome is updated.
ivoc112a3d82015-10-16 02:22:18 -0700708 virtual void StopRtcEventLog() = 0;
709
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000710 protected:
711 // Dtor and ctor protected as objects shouldn't be created or deleted via
712 // this interface.
713 PeerConnectionFactoryInterface() {}
714 ~PeerConnectionFactoryInterface() {} // NOLINT
715};
716
717// Create a new instance of PeerConnectionFactoryInterface.
Taylor Brandstettera8415fe2016-03-23 10:38:07 -0700718//
719// This method relies on the thread it's called on as the "signaling thread"
720// for the PeerConnectionFactory it creates.
721//
722// As such, if the current thread is not already running an rtc::Thread message
723// loop, an application using this method must eventually either call
724// rtc::Thread::Current()->Run(), or call
725// rtc::Thread::Current()->ProcessMessages() within the application's own
726// message loop.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000727rtc::scoped_refptr<PeerConnectionFactoryInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000728CreatePeerConnectionFactory();
729
730// Create a new instance of PeerConnectionFactoryInterface.
Taylor Brandstettera8415fe2016-03-23 10:38:07 -0700731//
danilchape9021a32016-05-17 01:52:02 -0700732// |network_thread|, |worker_thread| and |signaling_thread| are
733// the only mandatory parameters.
Taylor Brandstettera8415fe2016-03-23 10:38:07 -0700734//
735// If non-null, ownership of |default_adm|, |encoder_factory| and
736// |decoder_factory| are transferred to the returned factory.
danilchape9021a32016-05-17 01:52:02 -0700737rtc::scoped_refptr<PeerConnectionFactoryInterface> CreatePeerConnectionFactory(
738 rtc::Thread* network_thread,
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000739 rtc::Thread* worker_thread,
740 rtc::Thread* signaling_thread,
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000741 AudioDeviceModule* default_adm,
742 cricket::WebRtcVideoEncoderFactory* encoder_factory,
743 cricket::WebRtcVideoDecoderFactory* decoder_factory);
744
danilchape9021a32016-05-17 01:52:02 -0700745// Create a new instance of PeerConnectionFactoryInterface.
746// Same thread is used as worker and network thread.
danilchape9021a32016-05-17 01:52:02 -0700747inline rtc::scoped_refptr<PeerConnectionFactoryInterface>
748CreatePeerConnectionFactory(
749 rtc::Thread* worker_and_network_thread,
750 rtc::Thread* signaling_thread,
751 AudioDeviceModule* default_adm,
752 cricket::WebRtcVideoEncoderFactory* encoder_factory,
753 cricket::WebRtcVideoDecoderFactory* decoder_factory) {
754 return CreatePeerConnectionFactory(
755 worker_and_network_thread, worker_and_network_thread, signaling_thread,
756 default_adm, encoder_factory, decoder_factory);
757}
758
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000759} // namespace webrtc
760
Henrik Kjellander15583c12016-02-10 10:53:12 +0100761#endif // WEBRTC_API_PEERCONNECTIONINTERFACE_H_