blob: 9c0cefaca63df61fdefa48fcf06b7d2821f87cf5 [file] [log] [blame]
henrike@webrtc.org28e20752013-07-10 00:45:36 +00001/*
2 * libjingle
jlmiller@webrtc.org5f93d0a2015-01-20 21:36:13 +00003 * Copyright 2012 Google Inc.
henrike@webrtc.org28e20752013-07-10 00:45:36 +00004 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
7 *
8 * 1. Redistributions of source code must retain the above copyright notice,
9 * this list of conditions and the following disclaimer.
10 * 2. Redistributions in binary form must reproduce the above copyright notice,
11 * this list of conditions and the following disclaimer in the documentation
12 * and/or other materials provided with the distribution.
13 * 3. The name of the author may not be used to endorse or promote products
14 * derived from this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
17 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
18 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
19 * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
20 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
22 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
23 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
24 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
25 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 */
27
28// This file contains the PeerConnection interface as defined in
29// http://dev.w3.org/2011/webrtc/editor/webrtc.html#peer-to-peer-connections.
30// Applications must use this interface to implement peerconnection.
31// PeerConnectionFactory class provides factory methods to create
32// peerconnection, mediastream and media tracks objects.
33//
34// The Following steps are needed to setup a typical call using Jsep.
35// 1. Create a PeerConnectionFactoryInterface. Check constructors for more
36// information about input parameters.
37// 2. Create a PeerConnection object. Provide a configuration string which
38// points either to stun or turn server to generate ICE candidates and provide
39// an object that implements the PeerConnectionObserver interface.
40// 3. Create local MediaStream and MediaTracks using the PeerConnectionFactory
41// and add it to PeerConnection by calling AddStream.
42// 4. Create an offer and serialize it and send it to the remote peer.
43// 5. Once an ice candidate have been found PeerConnection will call the
44// observer function OnIceCandidate. The candidates must also be serialized and
45// sent to the remote peer.
46// 6. Once an answer is received from the remote peer, call
47// SetLocalSessionDescription with the offer and SetRemoteSessionDescription
48// with the remote answer.
49// 7. Once a remote candidate is received from the remote peer, provide it to
50// the peerconnection by calling AddIceCandidate.
51
52
53// The Receiver of a call can decide to accept or reject the call.
54// This decision will be taken by the application not peerconnection.
55// If application decides to accept the call
56// 1. Create PeerConnectionFactoryInterface if it doesn't exist.
57// 2. Create a new PeerConnection.
58// 3. Provide the remote offer to the new PeerConnection object by calling
59// SetRemoteSessionDescription.
60// 4. Generate an answer to the remote offer by calling CreateAnswer and send it
61// back to the remote peer.
62// 5. Provide the local answer to the new PeerConnection by calling
63// SetLocalSessionDescription with the answer.
64// 6. Provide the remote ice candidates by calling AddIceCandidate.
65// 7. Once a candidate have been found PeerConnection will call the observer
66// function OnIceCandidate. Send these candidates to the remote peer.
67
68#ifndef TALK_APP_WEBRTC_PEERCONNECTIONINTERFACE_H_
69#define TALK_APP_WEBRTC_PEERCONNECTIONINTERFACE_H_
70
71#include <string>
kwiberg0eb15ed2015-12-17 03:04:15 -080072#include <utility>
henrike@webrtc.org28e20752013-07-10 00:45:36 +000073#include <vector>
74
75#include "talk/app/webrtc/datachannelinterface.h"
Henrik Boström5b4ce332015-08-05 16:55:22 +020076#include "talk/app/webrtc/dtlsidentitystore.h"
Henrik Boström5e56c592015-08-11 10:33:13 +020077#include "talk/app/webrtc/dtlsidentitystore.h"
kjellandera96e2d72016-02-04 23:52:28 -080078#include "talk/app/webrtc/dtmfsenderinterface.h"
henrike@webrtc.org28e20752013-07-10 00:45:36 +000079#include "talk/app/webrtc/jsep.h"
80#include "talk/app/webrtc/mediastreaminterface.h"
deadbeef70ab1a12015-09-28 16:53:55 -070081#include "talk/app/webrtc/rtpreceiverinterface.h"
82#include "talk/app/webrtc/rtpsenderinterface.h"
henrike@webrtc.org28e20752013-07-10 00:45:36 +000083#include "talk/app/webrtc/statstypes.h"
buildbot@webrtc.org1567b8c2014-05-08 19:54:16 +000084#include "talk/app/webrtc/umametrics.h"
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +000085#include "webrtc/base/fileutils.h"
phoglund@webrtc.org006521d2015-02-12 09:23:59 +000086#include "webrtc/base/network.h"
Henrik Boström87713d02015-08-25 09:53:21 +020087#include "webrtc/base/rtccertificate.h"
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +000088#include "webrtc/base/socketaddress.h"
kjellandera96e2d72016-02-04 23:52:28 -080089#include "webrtc/base/sslstreamadapter.h"
deadbeef41b07982015-12-01 15:01:24 -080090#include "webrtc/p2p/base/portallocator.h"
henrike@webrtc.org28e20752013-07-10 00:45:36 +000091
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +000092namespace rtc {
jiayl@webrtc.org61e00b02015-03-04 22:17:38 +000093class SSLIdentity;
henrike@webrtc.org28e20752013-07-10 00:45:36 +000094class Thread;
95}
96
97namespace cricket {
henrike@webrtc.org28e20752013-07-10 00:45:36 +000098class WebRtcVideoDecoderFactory;
99class WebRtcVideoEncoderFactory;
100}
101
102namespace webrtc {
103class AudioDeviceModule;
104class MediaConstraintsInterface;
105
106// MediaStream container interface.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000107class StreamCollectionInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000108 public:
109 // TODO(ronghuawu): Update the function names to c++ style, e.g. find -> Find.
110 virtual size_t count() = 0;
111 virtual MediaStreamInterface* at(size_t index) = 0;
112 virtual MediaStreamInterface* find(const std::string& label) = 0;
113 virtual MediaStreamTrackInterface* FindAudioTrack(
114 const std::string& id) = 0;
115 virtual MediaStreamTrackInterface* FindVideoTrack(
116 const std::string& id) = 0;
117
118 protected:
119 // Dtor protected as objects shouldn't be deleted via this interface.
120 ~StreamCollectionInterface() {}
121};
122
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000123class StatsObserver : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000124 public:
tommi@webrtc.orge2e199b2014-12-15 13:22:54 +0000125 virtual void OnComplete(const StatsReports& reports) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000126
127 protected:
128 virtual ~StatsObserver() {}
129};
130
guoweis@webrtc.org7169afd2014-12-04 17:59:29 +0000131class MetricsObserverInterface : public rtc::RefCountInterface {
buildbot@webrtc.org1567b8c2014-05-08 19:54:16 +0000132 public:
Guo-wei Shieh3d564c12015-08-19 16:51:15 -0700133
134 // |type| is the type of the enum counter to be incremented. |counter|
135 // is the particular counter in that type. |counter_max| is the next sequence
136 // number after the highest counter.
137 virtual void IncrementEnumCounter(PeerConnectionEnumCounterType type,
138 int counter,
139 int counter_max) {}
140
Guo-wei Shieh456696a2015-09-30 21:48:54 -0700141 // This is used to handle sparse counters like SSL cipher suites.
142 // TODO(guoweis): Remove the implementation once the dependency's interface
143 // definition is updated.
144 virtual void IncrementSparseEnumCounter(PeerConnectionEnumCounterType type,
145 int counter) {
146 IncrementEnumCounter(type, counter, 0 /* Ignored */);
147 }
148
guoweis@webrtc.org7169afd2014-12-04 17:59:29 +0000149 virtual void AddHistogramSample(PeerConnectionMetricsName type,
mallinath@webrtc.orgd37bcfa2014-05-12 23:10:18 +0000150 int value) = 0;
buildbot@webrtc.org1567b8c2014-05-08 19:54:16 +0000151
152 protected:
guoweis@webrtc.org7169afd2014-12-04 17:59:29 +0000153 virtual ~MetricsObserverInterface() {}
buildbot@webrtc.org1567b8c2014-05-08 19:54:16 +0000154};
155
guoweis@webrtc.org7169afd2014-12-04 17:59:29 +0000156typedef MetricsObserverInterface UMAObserver;
157
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000158class PeerConnectionInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000159 public:
160 // See http://dev.w3.org/2011/webrtc/editor/webrtc.html#state-definitions .
161 enum SignalingState {
162 kStable,
163 kHaveLocalOffer,
164 kHaveLocalPrAnswer,
165 kHaveRemoteOffer,
166 kHaveRemotePrAnswer,
167 kClosed,
168 };
169
170 // TODO(bemasc): Remove IceState when callers are changed to
171 // IceConnection/GatheringState.
172 enum IceState {
173 kIceNew,
174 kIceGathering,
175 kIceWaiting,
176 kIceChecking,
177 kIceConnected,
178 kIceCompleted,
179 kIceFailed,
180 kIceClosed,
181 };
182
183 enum IceGatheringState {
184 kIceGatheringNew,
185 kIceGatheringGathering,
186 kIceGatheringComplete
187 };
188
189 enum IceConnectionState {
190 kIceConnectionNew,
191 kIceConnectionChecking,
192 kIceConnectionConnected,
193 kIceConnectionCompleted,
194 kIceConnectionFailed,
195 kIceConnectionDisconnected,
196 kIceConnectionClosed,
Guo-wei Shieh3d564c12015-08-19 16:51:15 -0700197 kIceConnectionMax,
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000198 };
199
200 struct IceServer {
Joachim Bauch7c4e7452015-05-28 23:06:30 +0200201 // TODO(jbauch): Remove uri when all code using it has switched to urls.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000202 std::string uri;
Joachim Bauch7c4e7452015-05-28 23:06:30 +0200203 std::vector<std::string> urls;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000204 std::string username;
205 std::string password;
206 };
207 typedef std::vector<IceServer> IceServers;
208
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000209 enum IceTransportsType {
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000210 // TODO(pthatcher): Rename these kTransporTypeXXX, but update
211 // Chromium at the same time.
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000212 kNone,
213 kRelay,
214 kNoHost,
215 kAll
216 };
217
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000218 // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-08#section-4.1.1
219 enum BundlePolicy {
220 kBundlePolicyBalanced,
221 kBundlePolicyMaxBundle,
222 kBundlePolicyMaxCompat
223 };
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000224
Peter Thatcheraf55ccc2015-05-21 07:48:41 -0700225 // https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-09#section-4.1.1
226 enum RtcpMuxPolicy {
227 kRtcpMuxPolicyNegotiate,
228 kRtcpMuxPolicyRequire,
229 };
230
Jiayang Liucac1b382015-04-30 12:35:24 -0700231 enum TcpCandidatePolicy {
232 kTcpCandidatePolicyEnabled,
233 kTcpCandidatePolicyDisabled
234 };
235
honghaiz1f429e32015-09-28 07:57:34 -0700236 enum ContinualGatheringPolicy {
237 GATHER_ONCE,
238 GATHER_CONTINUALLY
239 };
240
Henrik Boström87713d02015-08-25 09:53:21 +0200241 // TODO(hbos): Change into class with private data and public getters.
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000242 struct RTCConfiguration {
honghaiz4edc39c2015-09-01 09:53:56 -0700243 static const int kUndefined = -1;
244 // Default maximum number of packets in the audio jitter buffer.
245 static const int kAudioJitterBufferMaxPackets = 50;
pthatcher@webrtc.orgfd630a52015-01-14 23:19:06 +0000246 // TODO(pthatcher): Rename this ice_transport_type, but update
247 // Chromium at the same time.
248 IceTransportsType type;
249 // TODO(pthatcher): Rename this ice_servers, but update Chromium
250 // at the same time.
251 IceServers servers;
252 BundlePolicy bundle_policy;
Peter Thatcheraf55ccc2015-05-21 07:48:41 -0700253 RtcpMuxPolicy rtcp_mux_policy;
Jiayang Liucac1b382015-04-30 12:35:24 -0700254 TcpCandidatePolicy tcp_candidate_policy;
Henrik Lundin64dad832015-05-11 12:44:23 +0200255 int audio_jitter_buffer_max_packets;
Henrik Lundin5263b3c2015-06-01 10:29:41 +0200256 bool audio_jitter_buffer_fast_accelerate;
Honghai Zhang381b4212015-12-04 12:24:03 -0800257 int ice_connection_receiving_timeout; // ms
258 int ice_backup_candidate_pair_ping_interval; // ms
honghaiz1f429e32015-09-28 07:57:34 -0700259 ContinualGatheringPolicy continual_gathering_policy;
Henrik Boström87713d02015-08-25 09:53:21 +0200260 std::vector<rtc::scoped_refptr<rtc::RTCCertificate>> certificates;
qiangchen444682a2015-11-24 18:07:56 -0800261 bool disable_prerenderer_smoothing;
Jiayang Liucac1b382015-04-30 12:35:24 -0700262 RTCConfiguration()
263 : type(kAll),
264 bundle_policy(kBundlePolicyBalanced),
Peter Thatcheraf55ccc2015-05-21 07:48:41 -0700265 rtcp_mux_policy(kRtcpMuxPolicyNegotiate),
Henrik Lundin64dad832015-05-11 12:44:23 +0200266 tcp_candidate_policy(kTcpCandidatePolicyEnabled),
honghaiz4edc39c2015-09-01 09:53:56 -0700267 audio_jitter_buffer_max_packets(kAudioJitterBufferMaxPackets),
268 audio_jitter_buffer_fast_accelerate(false),
honghaiz1f429e32015-09-28 07:57:34 -0700269 ice_connection_receiving_timeout(kUndefined),
Honghai Zhang381b4212015-12-04 12:24:03 -0800270 ice_backup_candidate_pair_ping_interval(kUndefined),
qiangchen444682a2015-11-24 18:07:56 -0800271 continual_gathering_policy(GATHER_ONCE),
272 disable_prerenderer_smoothing(false) {}
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000273 };
274
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000275 struct RTCOfferAnswerOptions {
276 static const int kUndefined = -1;
277 static const int kMaxOfferToReceiveMedia = 1;
278
279 // The default value for constraint offerToReceiveX:true.
280 static const int kOfferToReceiveMediaTrue = 1;
281
282 int offer_to_receive_video;
283 int offer_to_receive_audio;
284 bool voice_activity_detection;
285 bool ice_restart;
286 bool use_rtp_mux;
287
288 RTCOfferAnswerOptions()
289 : offer_to_receive_video(kUndefined),
290 offer_to_receive_audio(kUndefined),
291 voice_activity_detection(true),
292 ice_restart(false),
293 use_rtp_mux(true) {}
294
295 RTCOfferAnswerOptions(int offer_to_receive_video,
296 int offer_to_receive_audio,
297 bool voice_activity_detection,
298 bool ice_restart,
299 bool use_rtp_mux)
300 : offer_to_receive_video(offer_to_receive_video),
301 offer_to_receive_audio(offer_to_receive_audio),
302 voice_activity_detection(voice_activity_detection),
303 ice_restart(ice_restart),
304 use_rtp_mux(use_rtp_mux) {}
305 };
306
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000307 // Used by GetStats to decide which stats to include in the stats reports.
308 // |kStatsOutputLevelStandard| includes the standard stats for Javascript API;
309 // |kStatsOutputLevelDebug| includes both the standard stats and additional
310 // stats for debugging purposes.
311 enum StatsOutputLevel {
312 kStatsOutputLevelStandard,
313 kStatsOutputLevelDebug,
314 };
315
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000316 // Accessor methods to active local streams.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000317 virtual rtc::scoped_refptr<StreamCollectionInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000318 local_streams() = 0;
319
320 // Accessor methods to remote streams.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000321 virtual rtc::scoped_refptr<StreamCollectionInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000322 remote_streams() = 0;
323
324 // Add a new MediaStream to be sent on this PeerConnection.
325 // Note that a SessionDescription negotiation is needed before the
326 // remote peer can receive the stream.
perkj@webrtc.orgfd0efb62014-11-06 12:16:36 +0000327 virtual bool AddStream(MediaStreamInterface* stream) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000328
329 // Remove a MediaStream from this PeerConnection.
330 // Note that a SessionDescription negotiation is need before the
331 // remote peer is notified.
332 virtual void RemoveStream(MediaStreamInterface* stream) = 0;
333
deadbeefe1f9d832016-01-14 15:35:42 -0800334 // TODO(deadbeef): Make the following two methods pure virtual once
335 // implemented by all subclasses of PeerConnectionInterface.
336 // Add a new MediaStreamTrack to be sent on this PeerConnection.
337 // |streams| indicates which stream labels the track should be associated
338 // with.
339 virtual rtc::scoped_refptr<RtpSenderInterface> AddTrack(
340 MediaStreamTrackInterface* track,
341 std::vector<MediaStreamInterface*> streams) {
342 return nullptr;
343 }
344
345 // Remove an RtpSender from this PeerConnection.
346 // Returns true on success.
347 virtual bool RemoveTrack(RtpSenderInterface* sender) {
348 return false;
349 }
350
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000351 // Returns pointer to the created DtmfSender on success.
352 // Otherwise returns NULL.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000353 virtual rtc::scoped_refptr<DtmfSenderInterface> CreateDtmfSender(
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000354 AudioTrackInterface* track) = 0;
355
deadbeef70ab1a12015-09-28 16:53:55 -0700356 // TODO(deadbeef): Make these pure virtual once all subclasses implement them.
deadbeeffac06552015-11-25 11:26:01 -0800357 // |kind| must be "audio" or "video".
deadbeefbd7d8f72015-12-18 16:58:44 -0800358 // |stream_id| is used to populate the msid attribute; if empty, one will
359 // be generated automatically.
deadbeeffac06552015-11-25 11:26:01 -0800360 virtual rtc::scoped_refptr<RtpSenderInterface> CreateSender(
deadbeefbd7d8f72015-12-18 16:58:44 -0800361 const std::string& kind,
362 const std::string& stream_id) {
deadbeeffac06552015-11-25 11:26:01 -0800363 return rtc::scoped_refptr<RtpSenderInterface>();
364 }
365
deadbeef70ab1a12015-09-28 16:53:55 -0700366 virtual std::vector<rtc::scoped_refptr<RtpSenderInterface>> GetSenders()
367 const {
368 return std::vector<rtc::scoped_refptr<RtpSenderInterface>>();
369 }
370
371 virtual std::vector<rtc::scoped_refptr<RtpReceiverInterface>> GetReceivers()
372 const {
373 return std::vector<rtc::scoped_refptr<RtpReceiverInterface>>();
374 }
375
wu@webrtc.orgb9a088b2014-02-13 23:18:49 +0000376 virtual bool GetStats(StatsObserver* observer,
377 MediaStreamTrackInterface* track,
378 StatsOutputLevel level) = 0;
379
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000380 virtual rtc::scoped_refptr<DataChannelInterface> CreateDataChannel(
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000381 const std::string& label,
382 const DataChannelInit* config) = 0;
383
384 virtual const SessionDescriptionInterface* local_description() const = 0;
385 virtual const SessionDescriptionInterface* remote_description() const = 0;
386
387 // Create a new offer.
388 // The CreateSessionDescriptionObserver callback will be called when done.
389 virtual void CreateOffer(CreateSessionDescriptionObserver* observer,
jiayl@webrtc.orgb18bf5e2014-08-04 18:34:16 +0000390 const MediaConstraintsInterface* constraints) {}
391
392 // TODO(jiayl): remove the default impl and the old interface when chromium
393 // code is updated.
394 virtual void CreateOffer(CreateSessionDescriptionObserver* observer,
395 const RTCOfferAnswerOptions& options) {}
396
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000397 // Create an answer to an offer.
398 // The CreateSessionDescriptionObserver callback will be called when done.
399 virtual void CreateAnswer(CreateSessionDescriptionObserver* observer,
400 const MediaConstraintsInterface* constraints) = 0;
401 // Sets the local session description.
402 // JsepInterface takes the ownership of |desc| even if it fails.
403 // The |observer| callback will be called when done.
404 virtual void SetLocalDescription(SetSessionDescriptionObserver* observer,
405 SessionDescriptionInterface* desc) = 0;
406 // Sets the remote session description.
407 // JsepInterface takes the ownership of |desc| even if it fails.
408 // The |observer| callback will be called when done.
409 virtual void SetRemoteDescription(SetSessionDescriptionObserver* observer,
410 SessionDescriptionInterface* desc) = 0;
411 // Restarts or updates the ICE Agent process of gathering local candidates
412 // and pinging remote candidates.
deadbeefa67696b2015-09-29 11:56:26 -0700413 // TODO(deadbeef): Remove once Chrome is moved over to SetConfiguration.
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000414 virtual bool UpdateIce(const IceServers& configuration,
deadbeefa67696b2015-09-29 11:56:26 -0700415 const MediaConstraintsInterface* constraints) {
416 return false;
417 }
418 // Sets the PeerConnection's global configuration to |config|.
419 // Any changes to STUN/TURN servers or ICE candidate policy will affect the
420 // next gathering phase, and cause the next call to createOffer to generate
421 // new ICE credentials. Note that the BUNDLE and RTCP-multiplexing policies
422 // cannot be changed with this method.
423 // TODO(deadbeef): Make this pure virtual once all Chrome subclasses of
424 // PeerConnectionInterface implement it.
425 virtual bool SetConfiguration(
426 const PeerConnectionInterface::RTCConfiguration& config) {
427 return false;
428 }
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000429 // Provides a remote candidate to the ICE Agent.
430 // A copy of the |candidate| will be created and added to the remote
431 // description. So the caller of this method still has the ownership of the
432 // |candidate|.
433 // TODO(ronghuawu): Consider to change this so that the AddIceCandidate will
434 // take the ownership of the |candidate|.
435 virtual bool AddIceCandidate(const IceCandidateInterface* candidate) = 0;
436
buildbot@webrtc.org1567b8c2014-05-08 19:54:16 +0000437 virtual void RegisterUMAObserver(UMAObserver* observer) = 0;
438
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000439 // Returns the current SignalingState.
440 virtual SignalingState signaling_state() = 0;
441
442 // TODO(bemasc): Remove ice_state when callers are changed to
443 // IceConnection/GatheringState.
444 // Returns the current IceState.
445 virtual IceState ice_state() = 0;
446 virtual IceConnectionState ice_connection_state() = 0;
447 virtual IceGatheringState ice_gathering_state() = 0;
448
449 // Terminates all media and closes the transport.
450 virtual void Close() = 0;
451
452 protected:
453 // Dtor protected as objects shouldn't be deleted via this interface.
454 ~PeerConnectionInterface() {}
455};
456
457// PeerConnection callback interface. Application should implement these
458// methods.
459class PeerConnectionObserver {
460 public:
461 enum StateType {
462 kSignalingState,
463 kIceState,
464 };
465
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000466 // Triggered when the SignalingState changed.
467 virtual void OnSignalingChange(
468 PeerConnectionInterface::SignalingState new_state) {}
469
470 // Triggered when SignalingState or IceState have changed.
471 // TODO(bemasc): Remove once callers transition to OnSignalingChange.
472 virtual void OnStateChange(StateType state_changed) {}
473
474 // Triggered when media is received on a new stream from remote peer.
475 virtual void OnAddStream(MediaStreamInterface* stream) = 0;
476
477 // Triggered when a remote peer close a stream.
478 virtual void OnRemoveStream(MediaStreamInterface* stream) = 0;
479
480 // Triggered when a remote peer open a data channel.
perkj@webrtc.orgc2dd5ee2014-11-04 11:31:29 +0000481 virtual void OnDataChannel(DataChannelInterface* data_channel) = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000482
mallinath@webrtc.org0d92ef62014-01-22 02:21:22 +0000483 // Triggered when renegotiation is needed, for example the ICE has restarted.
fischman@webrtc.orgd7568a02014-01-13 22:04:12 +0000484 virtual void OnRenegotiationNeeded() = 0;
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000485
486 // Called any time the IceConnectionState changes
487 virtual void OnIceConnectionChange(
488 PeerConnectionInterface::IceConnectionState new_state) {}
489
490 // Called any time the IceGatheringState changes
491 virtual void OnIceGatheringChange(
492 PeerConnectionInterface::IceGatheringState new_state) {}
493
494 // New Ice candidate have been found.
495 virtual void OnIceCandidate(const IceCandidateInterface* candidate) = 0;
496
497 // TODO(bemasc): Remove this once callers transition to OnIceGatheringChange.
498 // All Ice candidates have been found.
499 virtual void OnIceComplete() {}
500
Peter Thatcher54360512015-07-08 11:08:35 -0700501 // Called when the ICE connection receiving status changes.
502 virtual void OnIceConnectionReceivingChange(bool receiving) {}
503
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000504 protected:
505 // Dtor protected as objects shouldn't be deleted via this interface.
506 ~PeerConnectionObserver() {}
507};
508
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000509// PeerConnectionFactoryInterface is the factory interface use for creating
510// PeerConnection, MediaStream and media tracks.
511// PeerConnectionFactoryInterface will create required libjingle threads,
512// socket and network manager factory classes for networking.
513// If an application decides to provide its own threads and network
514// implementation of these classes it should use the alternate
515// CreatePeerConnectionFactory method which accepts threads as input and use the
Taylor Brandstetter0c7e9f52015-12-29 14:14:52 -0800516// CreatePeerConnection version that takes a PortAllocator as an
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000517// argument.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000518class PeerConnectionFactoryInterface : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000519 public:
wu@webrtc.org97077a32013-10-25 21:18:33 +0000520 class Options {
521 public:
Guo-wei Shieha7446d22016-01-11 15:27:03 -0800522 Options()
523 : disable_encryption(false),
524 disable_sctp_data_channels(false),
525 disable_network_monitor(false),
526 network_ignore_mask(rtc::kDefaultNetworkIgnoreMask),
527 ssl_max_version(rtc::SSL_PROTOCOL_DTLS_12) {}
wu@webrtc.org97077a32013-10-25 21:18:33 +0000528 bool disable_encryption;
529 bool disable_sctp_data_channels;
honghaiz023f3ef2015-10-19 09:39:32 -0700530 bool disable_network_monitor;
phoglund@webrtc.org006521d2015-02-12 09:23:59 +0000531
532 // Sets the network types to ignore. For instance, calling this with
533 // ADAPTER_TYPE_ETHERNET | ADAPTER_TYPE_LOOPBACK will ignore Ethernet and
534 // loopback interfaces.
535 int network_ignore_mask;
Joachim Bauch04e5b492015-05-29 09:40:39 +0200536
537 // Sets the maximum supported protocol version. The highest version
538 // supported by both ends will be used for the connection, i.e. if one
539 // party supports DTLS 1.0 and the other DTLS 1.2, DTLS 1.0 will be used.
540 rtc::SSLProtocolVersion ssl_max_version;
wu@webrtc.org97077a32013-10-25 21:18:33 +0000541 };
542
543 virtual void SetOptions(const Options& options) = 0;
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000544
deadbeef41b07982015-12-01 15:01:24 -0800545 virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection(
546 const PeerConnectionInterface::RTCConfiguration& configuration,
547 const MediaConstraintsInterface* constraints,
548 rtc::scoped_ptr<cricket::PortAllocator> allocator,
549 rtc::scoped_ptr<DtlsIdentityStoreInterface> dtls_identity_store,
Taylor Brandstetter0c7e9f52015-12-29 14:14:52 -0800550 PeerConnectionObserver* observer) = 0;
buildbot@webrtc.org41451d42014-05-03 05:39:45 +0000551
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000552 virtual rtc::scoped_refptr<MediaStreamInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000553 CreateLocalMediaStream(const std::string& label) = 0;
554
555 // Creates a AudioSourceInterface.
556 // |constraints| decides audio processing settings but can be NULL.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000557 virtual rtc::scoped_refptr<AudioSourceInterface> CreateAudioSource(
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000558 const MediaConstraintsInterface* constraints) = 0;
559
560 // Creates a VideoSourceInterface. The new source take ownership of
561 // |capturer|. |constraints| decides video resolution and frame rate but can
562 // be NULL.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000563 virtual rtc::scoped_refptr<VideoSourceInterface> CreateVideoSource(
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000564 cricket::VideoCapturer* capturer,
565 const MediaConstraintsInterface* constraints) = 0;
566
567 // Creates a new local VideoTrack. The same |source| can be used in several
568 // tracks.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000569 virtual rtc::scoped_refptr<VideoTrackInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000570 CreateVideoTrack(const std::string& label,
571 VideoSourceInterface* source) = 0;
572
573 // Creates an new AudioTrack. At the moment |source| can be NULL.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000574 virtual rtc::scoped_refptr<AudioTrackInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000575 CreateAudioTrack(const std::string& label,
576 AudioSourceInterface* source) = 0;
577
wu@webrtc.orga9890802013-12-13 00:21:03 +0000578 // Starts AEC dump using existing file. Takes ownership of |file| and passes
579 // it on to VoiceEngine (via other objects) immediately, which will take
wu@webrtc.orga8910d22014-01-23 22:12:45 +0000580 // the ownerhip. If the operation fails, the file will be closed.
ivocd66b44d2016-01-15 03:06:36 -0800581 // A maximum file size in bytes can be specified. When the file size limit is
582 // reached, logging is stopped automatically. If max_size_bytes is set to a
583 // value <= 0, no limit will be used, and logging will continue until the
584 // StopAecDump function is called.
585 virtual bool StartAecDump(rtc::PlatformFile file, int64_t max_size_bytes) = 0;
wu@webrtc.orga9890802013-12-13 00:21:03 +0000586
ivoc797ef122015-10-22 03:25:41 -0700587 // Stops logging the AEC dump.
588 virtual void StopAecDump() = 0;
589
ivoc112a3d82015-10-16 02:22:18 -0700590 // Starts RtcEventLog using existing file. Takes ownership of |file| and
591 // passes it on to VoiceEngine, which will take the ownership. If the
592 // operation fails the file will be closed. The logging will stop
593 // automatically after 10 minutes have passed, or when the StopRtcEventLog
594 // function is called.
595 // This function as well as the StopRtcEventLog don't really belong on this
596 // interface, this is a temporary solution until we move the logging object
597 // from inside voice engine to webrtc::Call, which will happen when the VoE
598 // restructuring effort is further along.
599 // TODO(ivoc): Move this into being:
600 // PeerConnection => MediaController => webrtc::Call.
601 virtual bool StartRtcEventLog(rtc::PlatformFile file) = 0;
602
603 // Stops logging the RtcEventLog.
604 virtual void StopRtcEventLog() = 0;
605
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000606 protected:
607 // Dtor and ctor protected as objects shouldn't be created or deleted via
608 // this interface.
609 PeerConnectionFactoryInterface() {}
610 ~PeerConnectionFactoryInterface() {} // NOLINT
611};
612
613// Create a new instance of PeerConnectionFactoryInterface.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000614rtc::scoped_refptr<PeerConnectionFactoryInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000615CreatePeerConnectionFactory();
616
617// Create a new instance of PeerConnectionFactoryInterface.
618// Ownership of |factory|, |default_adm|, and optionally |encoder_factory| and
619// |decoder_factory| transferred to the returned factory.
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000620rtc::scoped_refptr<PeerConnectionFactoryInterface>
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000621CreatePeerConnectionFactory(
buildbot@webrtc.orgd4e598d2014-07-29 17:36:52 +0000622 rtc::Thread* worker_thread,
623 rtc::Thread* signaling_thread,
henrike@webrtc.org28e20752013-07-10 00:45:36 +0000624 AudioDeviceModule* default_adm,
625 cricket::WebRtcVideoEncoderFactory* encoder_factory,
626 cricket::WebRtcVideoDecoderFactory* decoder_factory);
627
628} // namespace webrtc
629
630#endif // TALK_APP_WEBRTC_PEERCONNECTIONINTERFACE_H_