blob: 9259275b86a99071131fc5beeb9b422c71920269 [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
54#include <string>
kwiberg0eb15ed2015-12-17 03:04:15 -080055#include <utility>
henrike@webrtc.org28e20752013-07-10 00:45:36 +000056#include <vector>
57
Henrik Kjellander15583c12016-02-10 10:53:12 +010058#include "webrtc/api/datachannelinterface.h"
59#include "webrtc/api/dtlsidentitystore.h"
60#include "webrtc/api/dtlsidentitystore.h"
61#include "webrtc/api/dtmfsenderinterface.h"
62#include "webrtc/api/jsep.h"
63#include "webrtc/api/mediastreaminterface.h"
64#include "webrtc/api/rtpreceiverinterface.h"
65#include "webrtc/api/rtpsenderinterface.h"
66#include "webrtc/api/statstypes.h"
67#include "webrtc/api/umametrics.h"
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +000068#include "webrtc/base/fileutils.h"
phoglund@webrtc.org006521d2015-02-12 09:23:59 +000069#include "webrtc/base/network.h"
Henrik Boström87713d02015-08-25 09:53:21 +020070#include "webrtc/base/rtccertificate.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"
deadbeef41b07982015-12-01 15:01:24 -080073#include "webrtc/p2p/base/portallocator.h"
henrike@webrtc.org28e20752013-07-10 00:45:36 +000074
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +000075namespace rtc {
jiayl@webrtc.org61e00b02015-03-04 22:17:38 +000076class SSLIdentity;
henrike@webrtc.org28e20752013-07-10 00:45:36 +000077class Thread;
78}
79
80namespace cricket {
henrike@webrtc.org28e20752013-07-10 00:45:36 +000081class WebRtcVideoDecoderFactory;
82class WebRtcVideoEncoderFactory;
83}
84
85namespace webrtc {
86class AudioDeviceModule;
87class MediaConstraintsInterface;
88
89// MediaStream container interface.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +000090class StreamCollectionInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +000091 public:
92 // TODO(ronghuawu): Update the function names to c++ style, e.g. find -> Find.
93 virtual size_t count() = 0;
94 virtual MediaStreamInterface* at(size_t index) = 0;
95 virtual MediaStreamInterface* find(const std::string& label) = 0;
96 virtual MediaStreamTrackInterface* FindAudioTrack(
97 const std::string& id) = 0;
98 virtual MediaStreamTrackInterface* FindVideoTrack(
99 const std::string& id) = 0;
100
101 protected:
102 // Dtor protected as objects shouldn't be deleted via this interface.
103 ~StreamCollectionInterface() {}
104};
105
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000106class StatsObserver : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000107 public:
tommi@webrtc.orge2e199b2014-12-15 13:22:54 +0000108 virtual void OnComplete(const StatsReports& reports) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000109
110 protected:
111 virtual ~StatsObserver() {}
112};
113
guoweis@webrtc.org7169afd2014-12-04 17:59:29 +0000114class MetricsObserverInterface : public rtc::RefCountInterface {
buildbot@webrtc.org1567b8c2014-05-08 19:54:16 +0000115 public:
Guo-wei Shieh3d564c12015-08-19 16:51:15 -0700116
117 // |type| is the type of the enum counter to be incremented. |counter|
118 // is the particular counter in that type. |counter_max| is the next sequence
119 // number after the highest counter.
120 virtual void IncrementEnumCounter(PeerConnectionEnumCounterType type,
121 int counter,
122 int counter_max) {}
123
Guo-wei Shieh456696a2015-09-30 21:48:54 -0700124 // This is used to handle sparse counters like SSL cipher suites.
125 // TODO(guoweis): Remove the implementation once the dependency's interface
126 // definition is updated.
127 virtual void IncrementSparseEnumCounter(PeerConnectionEnumCounterType type,
128 int counter) {
129 IncrementEnumCounter(type, counter, 0 /* Ignored */);
130 }
131
guoweis@webrtc.org7169afd2014-12-04 17:59:29 +0000132 virtual void AddHistogramSample(PeerConnectionMetricsName type,
mallinath@webrtc.orgd37bcfa2014-05-12 23:10:18 +0000133 int value) = 0;
buildbot@webrtc.org1567b8c2014-05-08 19:54:16 +0000134
135 protected:
guoweis@webrtc.org7169afd2014-12-04 17:59:29 +0000136 virtual ~MetricsObserverInterface() {}
buildbot@webrtc.org1567b8c2014-05-08 19:54:16 +0000137};
138
guoweis@webrtc.org7169afd2014-12-04 17:59:29 +0000139typedef MetricsObserverInterface UMAObserver;
140
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000141class PeerConnectionInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000142 public:
143 // See http://dev.w3.org/2011/webrtc/editor/webrtc.html#state-definitions .
144 enum SignalingState {
145 kStable,
146 kHaveLocalOffer,
147 kHaveLocalPrAnswer,
148 kHaveRemoteOffer,
149 kHaveRemotePrAnswer,
150 kClosed,
151 };
152
153 // TODO(bemasc): Remove IceState when callers are changed to
154 // IceConnection/GatheringState.
155 enum IceState {
156 kIceNew,
157 kIceGathering,
158 kIceWaiting,
159 kIceChecking,
160 kIceConnected,
161 kIceCompleted,
162 kIceFailed,
163 kIceClosed,
164 };
165
166 enum IceGatheringState {
167 kIceGatheringNew,
168 kIceGatheringGathering,
169 kIceGatheringComplete
170 };
171
172 enum IceConnectionState {
173 kIceConnectionNew,
174 kIceConnectionChecking,
175 kIceConnectionConnected,
176 kIceConnectionCompleted,
177 kIceConnectionFailed,
178 kIceConnectionDisconnected,
179 kIceConnectionClosed,
Guo-wei Shieh3d564c12015-08-19 16:51:15 -0700180 kIceConnectionMax,
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000181 };
182
183 struct IceServer {
Joachim Bauch7c4e7452015-05-28 23:06:30 +0200184 // TODO(jbauch): Remove uri when all code using it has switched to urls.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000185 std::string uri;
Joachim Bauch7c4e7452015-05-28 23:06:30 +0200186 std::vector<std::string> urls;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000187 std::string username;
188 std::string password;
189 };
190 typedef std::vector<IceServer> IceServers;
191
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000192 enum IceTransportsType {
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000193 // TODO(pthatcher): Rename these kTransporTypeXXX, but update
194 // Chromium at the same time.
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000195 kNone,
196 kRelay,
197 kNoHost,
198 kAll
199 };
200
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000201 // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-08#section-4.1.1
202 enum BundlePolicy {
203 kBundlePolicyBalanced,
204 kBundlePolicyMaxBundle,
205 kBundlePolicyMaxCompat
206 };
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000207
Peter Thatcheraf55ccc2015-05-21 07:48:41 -0700208 // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-09#section-4.1.1
209 enum RtcpMuxPolicy {
210 kRtcpMuxPolicyNegotiate,
211 kRtcpMuxPolicyRequire,
212 };
213
Jiayang Liucac1b382015-04-30 12:35:24 -0700214 enum TcpCandidatePolicy {
215 kTcpCandidatePolicyEnabled,
216 kTcpCandidatePolicyDisabled
217 };
218
honghaiz1f429e32015-09-28 07:57:34 -0700219 enum ContinualGatheringPolicy {
220 GATHER_ONCE,
221 GATHER_CONTINUALLY
222 };
223
Henrik Boström87713d02015-08-25 09:53:21 +0200224 // TODO(hbos): Change into class with private data and public getters.
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000225 struct RTCConfiguration {
Niels Möller71bdda02016-03-31 12:59:59 +0200226 // This struct is subject to reorganization, both for naming
227 // consistency, and to group settings to match where they are used
228 // in the implementation. To do that, we need getter and setter
229 // methods for all settings which are of interest to applications,
230 // Chrome in particular.
231
232 bool dscp() { return enable_dscp.value_or(false); }
233 void set_dscp(bool enable) { enable_dscp = rtc::Optional<bool>(enable); }
234
235 // TODO(nisse): The corresponding flag in MediaConfig and
236 // elsewhere should be renamed enable_cpu_adaptation.
237 bool cpu_adaptation() { return cpu_overuse_detection.value_or(true); }
238 void set_cpu_adaptation(bool enable) {
239 cpu_overuse_detection = rtc::Optional<bool>(enable);
240 }
241
242 // TODO(nisse): Currently no getter method, since it collides with
243 // the flag itself. Add when the flag is moved to MediaConfig.
244 void set_suspend_below_min_bitrate(bool enable) {
245 suspend_below_min_bitrate = rtc::Optional<bool>(enable);
246 }
247
248 // TODO(nisse): The negation in the corresponding MediaConfig
249 // attribute is inconsistent, and it should be renamed at some
250 // point.
251 bool prerenderer_smoothing() { return !disable_prerenderer_smoothing; }
252 void set_prerenderer_smoothing(bool enable) {
253 disable_prerenderer_smoothing = !enable;
254 }
255
honghaiz4edc39c2015-09-01 09:53:56 -0700256 static const int kUndefined = -1;
257 // Default maximum number of packets in the audio jitter buffer.
258 static const int kAudioJitterBufferMaxPackets = 50;
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000259 // TODO(pthatcher): Rename this ice_transport_type, but update
260 // Chromium at the same time.
261 IceTransportsType type;
262 // TODO(pthatcher): Rename this ice_servers, but update Chromium
263 // at the same time.
264 IceServers servers;
265 BundlePolicy bundle_policy;
Peter Thatcheraf55ccc2015-05-21 07:48:41 -0700266 RtcpMuxPolicy rtcp_mux_policy;
Jiayang Liucac1b382015-04-30 12:35:24 -0700267 TcpCandidatePolicy tcp_candidate_policy;
Henrik Lundin64dad832015-05-11 12:44:23 +0200268 int audio_jitter_buffer_max_packets;
Henrik Lundin5263b3c2015-06-01 10:29:41 +0200269 bool audio_jitter_buffer_fast_accelerate;
Honghai Zhang381b4212015-12-04 12:24:03 -0800270 int ice_connection_receiving_timeout; // ms
271 int ice_backup_candidate_pair_ping_interval; // ms
honghaiz1f429e32015-09-28 07:57:34 -0700272 ContinualGatheringPolicy continual_gathering_policy;
Henrik Boström87713d02015-08-25 09:53:21 +0200273 std::vector<rtc::scoped_refptr<rtc::RTCCertificate>> certificates;
qiangchen444682a2015-11-24 18:07:56 -0800274 bool disable_prerenderer_smoothing;
guoweis36f01372016-03-02 18:02:40 -0800275 bool prioritize_most_likely_ice_candidate_pairs;
htaa2a49d92016-03-04 02:51:39 -0800276 // Flags corresponding to values set by constraint flags.
277 // rtc::Optional flags can be "missing", in which case the webrtc
278 // default applies.
279 bool disable_ipv6;
280 rtc::Optional<bool> enable_dscp;
281 bool enable_rtp_data_channel;
282 rtc::Optional<bool> cpu_overuse_detection;
283 rtc::Optional<bool> suspend_below_min_bitrate;
284 rtc::Optional<int> screencast_min_bitrate;
285 rtc::Optional<bool> combined_audio_video_bwe;
286 rtc::Optional<bool> enable_dtls_srtp;
Jiayang Liucac1b382015-04-30 12:35:24 -0700287 RTCConfiguration()
288 : type(kAll),
289 bundle_policy(kBundlePolicyBalanced),
Peter Thatcheraf55ccc2015-05-21 07:48:41 -0700290 rtcp_mux_policy(kRtcpMuxPolicyNegotiate),
Henrik Lundin64dad832015-05-11 12:44:23 +0200291 tcp_candidate_policy(kTcpCandidatePolicyEnabled),
honghaiz4edc39c2015-09-01 09:53:56 -0700292 audio_jitter_buffer_max_packets(kAudioJitterBufferMaxPackets),
293 audio_jitter_buffer_fast_accelerate(false),
honghaiz1f429e32015-09-28 07:57:34 -0700294 ice_connection_receiving_timeout(kUndefined),
Honghai Zhang381b4212015-12-04 12:24:03 -0800295 ice_backup_candidate_pair_ping_interval(kUndefined),
qiangchen444682a2015-11-24 18:07:56 -0800296 continual_gathering_policy(GATHER_ONCE),
guoweis36f01372016-03-02 18:02:40 -0800297 disable_prerenderer_smoothing(false),
htaa2a49d92016-03-04 02:51:39 -0800298 prioritize_most_likely_ice_candidate_pairs(false),
299 disable_ipv6(false),
300 enable_rtp_data_channel(false) {}
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000301 };
302
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000303 struct RTCOfferAnswerOptions {
304 static const int kUndefined = -1;
305 static const int kMaxOfferToReceiveMedia = 1;
306
307 // The default value for constraint offerToReceiveX:true.
308 static const int kOfferToReceiveMediaTrue = 1;
309
310 int offer_to_receive_video;
311 int offer_to_receive_audio;
312 bool voice_activity_detection;
313 bool ice_restart;
314 bool use_rtp_mux;
315
316 RTCOfferAnswerOptions()
317 : offer_to_receive_video(kUndefined),
318 offer_to_receive_audio(kUndefined),
319 voice_activity_detection(true),
320 ice_restart(false),
321 use_rtp_mux(true) {}
322
323 RTCOfferAnswerOptions(int offer_to_receive_video,
324 int offer_to_receive_audio,
325 bool voice_activity_detection,
326 bool ice_restart,
327 bool use_rtp_mux)
328 : offer_to_receive_video(offer_to_receive_video),
329 offer_to_receive_audio(offer_to_receive_audio),
330 voice_activity_detection(voice_activity_detection),
331 ice_restart(ice_restart),
332 use_rtp_mux(use_rtp_mux) {}
333 };
334
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000335 // Used by GetStats to decide which stats to include in the stats reports.
336 // |kStatsOutputLevelStandard| includes the standard stats for Javascript API;
337 // |kStatsOutputLevelDebug| includes both the standard stats and additional
338 // stats for debugging purposes.
339 enum StatsOutputLevel {
340 kStatsOutputLevelStandard,
341 kStatsOutputLevelDebug,
342 };
343
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000344 // Accessor methods to active local streams.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000345 virtual rtc::scoped_refptr<StreamCollectionInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000346 local_streams() = 0;
347
348 // Accessor methods to remote streams.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000349 virtual rtc::scoped_refptr<StreamCollectionInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000350 remote_streams() = 0;
351
352 // Add a new MediaStream to be sent on this PeerConnection.
353 // Note that a SessionDescription negotiation is needed before the
354 // remote peer can receive the stream.
perkj@webrtc.orgfd0efb62014-11-06 12:16:36 +0000355 virtual bool AddStream(MediaStreamInterface* stream) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000356
357 // Remove a MediaStream from this PeerConnection.
358 // Note that a SessionDescription negotiation is need before the
359 // remote peer is notified.
360 virtual void RemoveStream(MediaStreamInterface* stream) = 0;
361
deadbeefe1f9d832016-01-14 15:35:42 -0800362 // TODO(deadbeef): Make the following two methods pure virtual once
363 // implemented by all subclasses of PeerConnectionInterface.
364 // Add a new MediaStreamTrack to be sent on this PeerConnection.
365 // |streams| indicates which stream labels the track should be associated
366 // with.
367 virtual rtc::scoped_refptr<RtpSenderInterface> AddTrack(
368 MediaStreamTrackInterface* track,
369 std::vector<MediaStreamInterface*> streams) {
370 return nullptr;
371 }
372
373 // Remove an RtpSender from this PeerConnection.
374 // Returns true on success.
375 virtual bool RemoveTrack(RtpSenderInterface* sender) {
376 return false;
377 }
378
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000379 // Returns pointer to the created DtmfSender on success.
380 // Otherwise returns NULL.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000381 virtual rtc::scoped_refptr<DtmfSenderInterface> CreateDtmfSender(
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000382 AudioTrackInterface* track) = 0;
383
deadbeef70ab1a12015-09-28 16:53:55 -0700384 // TODO(deadbeef): Make these pure virtual once all subclasses implement them.
deadbeeffac06552015-11-25 11:26:01 -0800385 // |kind| must be "audio" or "video".
deadbeefbd7d8f72015-12-18 16:58:44 -0800386 // |stream_id| is used to populate the msid attribute; if empty, one will
387 // be generated automatically.
deadbeeffac06552015-11-25 11:26:01 -0800388 virtual rtc::scoped_refptr<RtpSenderInterface> CreateSender(
deadbeefbd7d8f72015-12-18 16:58:44 -0800389 const std::string& kind,
390 const std::string& stream_id) {
deadbeeffac06552015-11-25 11:26:01 -0800391 return rtc::scoped_refptr<RtpSenderInterface>();
392 }
393
deadbeef70ab1a12015-09-28 16:53:55 -0700394 virtual std::vector<rtc::scoped_refptr<RtpSenderInterface>> GetSenders()
395 const {
396 return std::vector<rtc::scoped_refptr<RtpSenderInterface>>();
397 }
398
399 virtual std::vector<rtc::scoped_refptr<RtpReceiverInterface>> GetReceivers()
400 const {
401 return std::vector<rtc::scoped_refptr<RtpReceiverInterface>>();
402 }
403
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000404 virtual bool GetStats(StatsObserver* observer,
405 MediaStreamTrackInterface* track,
406 StatsOutputLevel level) = 0;
407
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000408 virtual rtc::scoped_refptr<DataChannelInterface> CreateDataChannel(
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000409 const std::string& label,
410 const DataChannelInit* config) = 0;
411
412 virtual const SessionDescriptionInterface* local_description() const = 0;
413 virtual const SessionDescriptionInterface* remote_description() const = 0;
414
415 // Create a new offer.
416 // The CreateSessionDescriptionObserver callback will be called when done.
417 virtual void CreateOffer(CreateSessionDescriptionObserver* observer,
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000418 const MediaConstraintsInterface* constraints) {}
419
420 // TODO(jiayl): remove the default impl and the old interface when chromium
421 // code is updated.
422 virtual void CreateOffer(CreateSessionDescriptionObserver* observer,
423 const RTCOfferAnswerOptions& options) {}
424
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000425 // Create an answer to an offer.
426 // The CreateSessionDescriptionObserver callback will be called when done.
427 virtual void CreateAnswer(CreateSessionDescriptionObserver* observer,
htaa2a49d92016-03-04 02:51:39 -0800428 const RTCOfferAnswerOptions& options) {}
429 // Deprecated - use version above.
430 // TODO(hta): Remove and remove default implementations when all callers
431 // are updated.
432 virtual void CreateAnswer(CreateSessionDescriptionObserver* observer,
433 const MediaConstraintsInterface* constraints) {}
434
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000435 // Sets the local session description.
436 // JsepInterface takes the ownership of |desc| even if it fails.
437 // The |observer| callback will be called when done.
438 virtual void SetLocalDescription(SetSessionDescriptionObserver* observer,
439 SessionDescriptionInterface* desc) = 0;
440 // Sets the remote session description.
441 // JsepInterface takes the ownership of |desc| even if it fails.
442 // The |observer| callback will be called when done.
443 virtual void SetRemoteDescription(SetSessionDescriptionObserver* observer,
444 SessionDescriptionInterface* desc) = 0;
445 // Restarts or updates the ICE Agent process of gathering local candidates
446 // and pinging remote candidates.
deadbeefa67696b2015-09-29 11:56:26 -0700447 // TODO(deadbeef): Remove once Chrome is moved over to SetConfiguration.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000448 virtual bool UpdateIce(const IceServers& configuration,
deadbeefa67696b2015-09-29 11:56:26 -0700449 const MediaConstraintsInterface* constraints) {
450 return false;
451 }
htaa2a49d92016-03-04 02:51:39 -0800452 virtual bool UpdateIce(const IceServers& configuration) { return false; }
deadbeefa67696b2015-09-29 11:56:26 -0700453 // Sets the PeerConnection's global configuration to |config|.
454 // Any changes to STUN/TURN servers or ICE candidate policy will affect the
455 // next gathering phase, and cause the next call to createOffer to generate
456 // new ICE credentials. Note that the BUNDLE and RTCP-multiplexing policies
457 // cannot be changed with this method.
458 // TODO(deadbeef): Make this pure virtual once all Chrome subclasses of
459 // PeerConnectionInterface implement it.
460 virtual bool SetConfiguration(
461 const PeerConnectionInterface::RTCConfiguration& config) {
462 return false;
463 }
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000464 // Provides a remote candidate to the ICE Agent.
465 // A copy of the |candidate| will be created and added to the remote
466 // description. So the caller of this method still has the ownership of the
467 // |candidate|.
468 // TODO(ronghuawu): Consider to change this so that the AddIceCandidate will
469 // take the ownership of the |candidate|.
470 virtual bool AddIceCandidate(const IceCandidateInterface* candidate) = 0;
471
Honghai Zhang7fb69db2016-03-14 11:59:18 -0700472 // Removes a group of remote candidates from the ICE agent.
473 virtual bool RemoveIceCandidates(
474 const std::vector<cricket::Candidate>& candidates) {
475 return false;
476 }
477
buildbot@webrtc.org1567b8c2014-05-08 19:54:16 +0000478 virtual void RegisterUMAObserver(UMAObserver* observer) = 0;
479
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000480 // Returns the current SignalingState.
481 virtual SignalingState signaling_state() = 0;
482
483 // TODO(bemasc): Remove ice_state when callers are changed to
484 // IceConnection/GatheringState.
485 // Returns the current IceState.
486 virtual IceState ice_state() = 0;
487 virtual IceConnectionState ice_connection_state() = 0;
488 virtual IceGatheringState ice_gathering_state() = 0;
489
490 // Terminates all media and closes the transport.
491 virtual void Close() = 0;
492
493 protected:
494 // Dtor protected as objects shouldn't be deleted via this interface.
495 ~PeerConnectionInterface() {}
496};
497
498// PeerConnection callback interface. Application should implement these
499// methods.
500class PeerConnectionObserver {
501 public:
502 enum StateType {
503 kSignalingState,
504 kIceState,
505 };
506
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000507 // Triggered when the SignalingState changed.
508 virtual void OnSignalingChange(
perkjdfb769d2016-02-09 03:09:43 -0800509 PeerConnectionInterface::SignalingState new_state) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000510
511 // Triggered when media is received on a new stream from remote peer.
512 virtual void OnAddStream(MediaStreamInterface* stream) = 0;
513
514 // Triggered when a remote peer close a stream.
515 virtual void OnRemoveStream(MediaStreamInterface* stream) = 0;
516
517 // Triggered when a remote peer open a data channel.
perkj@webrtc.orgc2dd5ee2014-11-04 11:31:29 +0000518 virtual void OnDataChannel(DataChannelInterface* data_channel) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000519
mallinath@webrtc.org0d92ef62014-01-22 02:21:22 +0000520 // Triggered when renegotiation is needed, for example the ICE has restarted.
fischman@webrtc.orgd7568a02014-01-13 22:04:12 +0000521 virtual void OnRenegotiationNeeded() = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000522
523 // Called any time the IceConnectionState changes
524 virtual void OnIceConnectionChange(
perkjdfb769d2016-02-09 03:09:43 -0800525 PeerConnectionInterface::IceConnectionState new_state) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000526
527 // Called any time the IceGatheringState changes
528 virtual void OnIceGatheringChange(
perkjdfb769d2016-02-09 03:09:43 -0800529 PeerConnectionInterface::IceGatheringState new_state) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000530
531 // New Ice candidate have been found.
532 virtual void OnIceCandidate(const IceCandidateInterface* candidate) = 0;
533
Honghai Zhang7fb69db2016-03-14 11:59:18 -0700534 // Ice candidates have been removed.
535 // TODO(honghaiz): Make this a pure virtual method when all its subclasses
536 // implement it.
537 virtual void OnIceCandidatesRemoved(
538 const std::vector<cricket::Candidate>& candidates) {}
539
Peter Thatcher54360512015-07-08 11:08:35 -0700540 // Called when the ICE connection receiving status changes.
541 virtual void OnIceConnectionReceivingChange(bool receiving) {}
542
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000543 protected:
544 // Dtor protected as objects shouldn't be deleted via this interface.
545 ~PeerConnectionObserver() {}
546};
547
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000548// PeerConnectionFactoryInterface is the factory interface use for creating
549// PeerConnection, MediaStream and media tracks.
550// PeerConnectionFactoryInterface will create required libjingle threads,
551// socket and network manager factory classes for networking.
552// If an application decides to provide its own threads and network
553// implementation of these classes it should use the alternate
554// CreatePeerConnectionFactory method which accepts threads as input and use the
Taylor Brandstetter0c7e9f52015-12-29 14:14:52 -0800555// CreatePeerConnection version that takes a PortAllocator as an
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000556// argument.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000557class PeerConnectionFactoryInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000558 public:
wu@webrtc.org97077a32013-10-25 21:18:33 +0000559 class Options {
560 public:
Guo-wei Shieha7446d22016-01-11 15:27:03 -0800561 Options()
562 : disable_encryption(false),
563 disable_sctp_data_channels(false),
564 disable_network_monitor(false),
565 network_ignore_mask(rtc::kDefaultNetworkIgnoreMask),
566 ssl_max_version(rtc::SSL_PROTOCOL_DTLS_12) {}
wu@webrtc.org97077a32013-10-25 21:18:33 +0000567 bool disable_encryption;
568 bool disable_sctp_data_channels;
honghaiz023f3ef2015-10-19 09:39:32 -0700569 bool disable_network_monitor;
phoglund@webrtc.org006521d2015-02-12 09:23:59 +0000570
571 // Sets the network types to ignore. For instance, calling this with
572 // ADAPTER_TYPE_ETHERNET | ADAPTER_TYPE_LOOPBACK will ignore Ethernet and
573 // loopback interfaces.
574 int network_ignore_mask;
Joachim Bauch04e5b492015-05-29 09:40:39 +0200575
576 // Sets the maximum supported protocol version. The highest version
577 // supported by both ends will be used for the connection, i.e. if one
578 // party supports DTLS 1.0 and the other DTLS 1.2, DTLS 1.0 will be used.
579 rtc::SSLProtocolVersion ssl_max_version;
wu@webrtc.org97077a32013-10-25 21:18:33 +0000580 };
581
582 virtual void SetOptions(const Options& options) = 0;
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000583
deadbeef41b07982015-12-01 15:01:24 -0800584 virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection(
585 const PeerConnectionInterface::RTCConfiguration& configuration,
586 const MediaConstraintsInterface* constraints,
587 rtc::scoped_ptr<cricket::PortAllocator> allocator,
588 rtc::scoped_ptr<DtlsIdentityStoreInterface> dtls_identity_store,
Taylor Brandstetter0c7e9f52015-12-29 14:14:52 -0800589 PeerConnectionObserver* observer) = 0;
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000590
htaa2a49d92016-03-04 02:51:39 -0800591 virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection(
592 const PeerConnectionInterface::RTCConfiguration& configuration,
593 rtc::scoped_ptr<cricket::PortAllocator> allocator,
594 rtc::scoped_ptr<DtlsIdentityStoreInterface> dtls_identity_store,
595 PeerConnectionObserver* observer) = 0;
596
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000597 virtual rtc::scoped_refptr<MediaStreamInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000598 CreateLocalMediaStream(const std::string& label) = 0;
599
600 // Creates a AudioSourceInterface.
601 // |constraints| decides audio processing settings but can be NULL.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000602 virtual rtc::scoped_refptr<AudioSourceInterface> CreateAudioSource(
htaa2a49d92016-03-04 02:51:39 -0800603 const cricket::AudioOptions& options) = 0;
604 // Deprecated - use version above.
605 virtual rtc::scoped_refptr<AudioSourceInterface> CreateAudioSource(
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000606 const MediaConstraintsInterface* constraints) = 0;
607
perkja3ede6c2016-03-08 01:27:48 +0100608 // Creates a VideoTrackSourceInterface. The new source take ownership of
htaa2a49d92016-03-04 02:51:39 -0800609 // |capturer|.
perkja3ede6c2016-03-08 01:27:48 +0100610 virtual rtc::scoped_refptr<VideoTrackSourceInterface> CreateVideoSource(
htaa2a49d92016-03-04 02:51:39 -0800611 cricket::VideoCapturer* capturer) = 0;
612 // A video source creator that allows selection of resolution and frame rate.
613 // |constraints| decides video resolution and frame rate but can
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000614 // be NULL.
htaa2a49d92016-03-04 02:51:39 -0800615 // In the NULL case, use the version above.
perkja3ede6c2016-03-08 01:27:48 +0100616 virtual rtc::scoped_refptr<VideoTrackSourceInterface> CreateVideoSource(
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000617 cricket::VideoCapturer* capturer,
618 const MediaConstraintsInterface* constraints) = 0;
619
620 // Creates a new local VideoTrack. The same |source| can be used in several
621 // tracks.
perkja3ede6c2016-03-08 01:27:48 +0100622 virtual rtc::scoped_refptr<VideoTrackInterface> CreateVideoTrack(
623 const std::string& label,
624 VideoTrackSourceInterface* source) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000625
626 // Creates an new AudioTrack. At the moment |source| can be NULL.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000627 virtual rtc::scoped_refptr<AudioTrackInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000628 CreateAudioTrack(const std::string& label,
629 AudioSourceInterface* source) = 0;
630
wu@webrtc.orga9890802013-12-13 00:21:03 +0000631 // Starts AEC dump using existing file. Takes ownership of |file| and passes
632 // it on to VoiceEngine (via other objects) immediately, which will take
wu@webrtc.orga8910d22014-01-23 22:12:45 +0000633 // the ownerhip. If the operation fails, the file will be closed.
ivocd66b44d2016-01-15 03:06:36 -0800634 // A maximum file size in bytes can be specified. When the file size limit is
635 // reached, logging is stopped automatically. If max_size_bytes is set to a
636 // value <= 0, no limit will be used, and logging will continue until the
637 // StopAecDump function is called.
638 virtual bool StartAecDump(rtc::PlatformFile file, int64_t max_size_bytes) = 0;
wu@webrtc.orga9890802013-12-13 00:21:03 +0000639
ivoc797ef122015-10-22 03:25:41 -0700640 // Stops logging the AEC dump.
641 virtual void StopAecDump() = 0;
642
ivoc112a3d82015-10-16 02:22:18 -0700643 // Starts RtcEventLog using existing file. Takes ownership of |file| and
644 // passes it on to VoiceEngine, which will take the ownership. If the
645 // operation fails the file will be closed. The logging will stop
646 // automatically after 10 minutes have passed, or when the StopRtcEventLog
647 // function is called.
648 // This function as well as the StopRtcEventLog don't really belong on this
649 // interface, this is a temporary solution until we move the logging object
650 // from inside voice engine to webrtc::Call, which will happen when the VoE
651 // restructuring effort is further along.
652 // TODO(ivoc): Move this into being:
653 // PeerConnection => MediaController => webrtc::Call.
654 virtual bool StartRtcEventLog(rtc::PlatformFile file) = 0;
655
656 // Stops logging the RtcEventLog.
657 virtual void StopRtcEventLog() = 0;
658
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000659 protected:
660 // Dtor and ctor protected as objects shouldn't be created or deleted via
661 // this interface.
662 PeerConnectionFactoryInterface() {}
663 ~PeerConnectionFactoryInterface() {} // NOLINT
664};
665
666// Create a new instance of PeerConnectionFactoryInterface.
Taylor Brandstettera8415fe2016-03-23 10:38:07 -0700667//
668// This method relies on the thread it's called on as the "signaling thread"
669// for the PeerConnectionFactory it creates.
670//
671// As such, if the current thread is not already running an rtc::Thread message
672// loop, an application using this method must eventually either call
673// rtc::Thread::Current()->Run(), or call
674// rtc::Thread::Current()->ProcessMessages() within the application's own
675// message loop.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000676rtc::scoped_refptr<PeerConnectionFactoryInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000677CreatePeerConnectionFactory();
678
679// Create a new instance of PeerConnectionFactoryInterface.
Taylor Brandstettera8415fe2016-03-23 10:38:07 -0700680//
681// |worker_thread| and |signaling_thread| are the only mandatory
682// parameters.
683//
684// If non-null, ownership of |default_adm|, |encoder_factory| and
685// |decoder_factory| are transferred to the returned factory.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000686rtc::scoped_refptr<PeerConnectionFactoryInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000687CreatePeerConnectionFactory(
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000688 rtc::Thread* worker_thread,
689 rtc::Thread* signaling_thread,
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000690 AudioDeviceModule* default_adm,
691 cricket::WebRtcVideoEncoderFactory* encoder_factory,
692 cricket::WebRtcVideoDecoderFactory* decoder_factory);
693
694} // namespace webrtc
695
Henrik Kjellander15583c12016-02-10 10:53:12 +0100696#endif // WEBRTC_API_PEERCONNECTIONINTERFACE_H_