3 * Copyright 2012, Google Inc.
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
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.
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.
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.
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.
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.
68 #ifndef TALK_APP_WEBRTC_PEERCONNECTIONINTERFACE_H_
69 #define TALK_APP_WEBRTC_PEERCONNECTIONINTERFACE_H_
74 #include "talk/app/webrtc/datachannelinterface.h"
75 #include "talk/app/webrtc/dtmfsenderinterface.h"
76 #include "talk/app/webrtc/jsep.h"
77 #include "talk/app/webrtc/mediastreaminterface.h"
78 #include "talk/app/webrtc/statstypes.h"
79 #include "talk/base/fileutils.h"
80 #include "talk/base/socketaddress.h"
88 class WebRtcVideoDecoderFactory;
89 class WebRtcVideoEncoderFactory;
93 class AudioDeviceModule;
94 class MediaConstraintsInterface;
96 // MediaStream container interface.
97 class StreamCollectionInterface : public talk_base::RefCountInterface {
99 // TODO(ronghuawu): Update the function names to c++ style, e.g. find -> Find.
100 virtual size_t count() = 0;
101 virtual MediaStreamInterface* at(size_t index) = 0;
102 virtual MediaStreamInterface* find(const std::string& label) = 0;
103 virtual MediaStreamTrackInterface* FindAudioTrack(
104 const std::string& id) = 0;
105 virtual MediaStreamTrackInterface* FindVideoTrack(
106 const std::string& id) = 0;
109 // Dtor protected as objects shouldn't be deleted via this interface.
110 ~StreamCollectionInterface() {}
113 class StatsObserver : public talk_base::RefCountInterface {
115 virtual void OnComplete(const std::vector<StatsReport>& reports) = 0;
118 virtual ~StatsObserver() {}
121 class PeerConnectionInterface : public talk_base::RefCountInterface {
123 // See http://dev.w3.org/2011/webrtc/editor/webrtc.html#state-definitions .
124 enum SignalingState {
133 // TODO(bemasc): Remove IceState when callers are changed to
134 // IceConnection/GatheringState.
146 enum IceGatheringState {
148 kIceGatheringGathering,
149 kIceGatheringComplete
152 enum IceConnectionState {
154 kIceConnectionChecking,
155 kIceConnectionConnected,
156 kIceConnectionCompleted,
157 kIceConnectionFailed,
158 kIceConnectionDisconnected,
159 kIceConnectionClosed,
164 std::string username;
165 std::string password;
167 typedef std::vector<IceServer> IceServers;
169 // Used by GetStats to decide which stats to include in the stats reports.
170 // |kStatsOutputLevelStandard| includes the standard stats for Javascript API;
171 // |kStatsOutputLevelDebug| includes both the standard stats and additional
172 // stats for debugging purposes.
173 enum StatsOutputLevel {
174 kStatsOutputLevelStandard,
175 kStatsOutputLevelDebug,
178 // Accessor methods to active local streams.
179 virtual talk_base::scoped_refptr<StreamCollectionInterface>
182 // Accessor methods to remote streams.
183 virtual talk_base::scoped_refptr<StreamCollectionInterface>
184 remote_streams() = 0;
186 // Add a new MediaStream to be sent on this PeerConnection.
187 // Note that a SessionDescription negotiation is needed before the
188 // remote peer can receive the stream.
189 virtual bool AddStream(MediaStreamInterface* stream,
190 const MediaConstraintsInterface* constraints) = 0;
192 // Remove a MediaStream from this PeerConnection.
193 // Note that a SessionDescription negotiation is need before the
194 // remote peer is notified.
195 virtual void RemoveStream(MediaStreamInterface* stream) = 0;
197 // Returns pointer to the created DtmfSender on success.
198 // Otherwise returns NULL.
199 virtual talk_base::scoped_refptr<DtmfSenderInterface> CreateDtmfSender(
200 AudioTrackInterface* track) = 0;
202 virtual bool GetStats(StatsObserver* observer,
203 MediaStreamTrackInterface* track,
204 StatsOutputLevel level) = 0;
206 virtual talk_base::scoped_refptr<DataChannelInterface> CreateDataChannel(
207 const std::string& label,
208 const DataChannelInit* config) = 0;
210 virtual const SessionDescriptionInterface* local_description() const = 0;
211 virtual const SessionDescriptionInterface* remote_description() const = 0;
213 // Create a new offer.
214 // The CreateSessionDescriptionObserver callback will be called when done.
215 virtual void CreateOffer(CreateSessionDescriptionObserver* observer,
216 const MediaConstraintsInterface* constraints) = 0;
217 // Create an answer to an offer.
218 // The CreateSessionDescriptionObserver callback will be called when done.
219 virtual void CreateAnswer(CreateSessionDescriptionObserver* observer,
220 const MediaConstraintsInterface* constraints) = 0;
221 // Sets the local session description.
222 // JsepInterface takes the ownership of |desc| even if it fails.
223 // The |observer| callback will be called when done.
224 virtual void SetLocalDescription(SetSessionDescriptionObserver* observer,
225 SessionDescriptionInterface* desc) = 0;
226 // Sets the remote session description.
227 // JsepInterface takes the ownership of |desc| even if it fails.
228 // The |observer| callback will be called when done.
229 virtual void SetRemoteDescription(SetSessionDescriptionObserver* observer,
230 SessionDescriptionInterface* desc) = 0;
231 // Restarts or updates the ICE Agent process of gathering local candidates
232 // and pinging remote candidates.
233 virtual bool UpdateIce(const IceServers& configuration,
234 const MediaConstraintsInterface* constraints) = 0;
235 // Provides a remote candidate to the ICE Agent.
236 // A copy of the |candidate| will be created and added to the remote
237 // description. So the caller of this method still has the ownership of the
239 // TODO(ronghuawu): Consider to change this so that the AddIceCandidate will
240 // take the ownership of the |candidate|.
241 virtual bool AddIceCandidate(const IceCandidateInterface* candidate) = 0;
243 // Returns the current SignalingState.
244 virtual SignalingState signaling_state() = 0;
246 // TODO(bemasc): Remove ice_state when callers are changed to
247 // IceConnection/GatheringState.
248 // Returns the current IceState.
249 virtual IceState ice_state() = 0;
250 virtual IceConnectionState ice_connection_state() = 0;
251 virtual IceGatheringState ice_gathering_state() = 0;
253 // Terminates all media and closes the transport.
254 virtual void Close() = 0;
257 // Dtor protected as objects shouldn't be deleted via this interface.
258 ~PeerConnectionInterface() {}
261 // PeerConnection callback interface. Application should implement these
263 class PeerConnectionObserver {
270 virtual void OnError() = 0;
272 // Triggered when the SignalingState changed.
273 virtual void OnSignalingChange(
274 PeerConnectionInterface::SignalingState new_state) {}
276 // Triggered when SignalingState or IceState have changed.
277 // TODO(bemasc): Remove once callers transition to OnSignalingChange.
278 virtual void OnStateChange(StateType state_changed) {}
280 // Triggered when media is received on a new stream from remote peer.
281 virtual void OnAddStream(MediaStreamInterface* stream) = 0;
283 // Triggered when a remote peer close a stream.
284 virtual void OnRemoveStream(MediaStreamInterface* stream) = 0;
286 // Triggered when a remote peer open a data channel.
287 // TODO(perkj): Make pure virtual.
288 virtual void OnDataChannel(DataChannelInterface* data_channel) {}
290 // Triggered when renegotiation is needed, for example the ICE has restarted.
291 virtual void OnRenegotiationNeeded() = 0;
293 // Called any time the IceConnectionState changes
294 virtual void OnIceConnectionChange(
295 PeerConnectionInterface::IceConnectionState new_state) {}
297 // Called any time the IceGatheringState changes
298 virtual void OnIceGatheringChange(
299 PeerConnectionInterface::IceGatheringState new_state) {}
301 // New Ice candidate have been found.
302 virtual void OnIceCandidate(const IceCandidateInterface* candidate) = 0;
304 // TODO(bemasc): Remove this once callers transition to OnIceGatheringChange.
305 // All Ice candidates have been found.
306 virtual void OnIceComplete() {}
309 // Dtor protected as objects shouldn't be deleted via this interface.
310 ~PeerConnectionObserver() {}
313 // Factory class used for creating cricket::PortAllocator that is used
314 // for ICE negotiation.
315 class PortAllocatorFactoryInterface : public talk_base::RefCountInterface {
317 struct StunConfiguration {
318 StunConfiguration(const std::string& address, int port)
319 : server(address, port) {}
320 // STUN server address and port.
321 talk_base::SocketAddress server;
324 struct TurnConfiguration {
325 TurnConfiguration(const std::string& address,
327 const std::string& username,
328 const std::string& password,
329 const std::string& transport_type,
331 : server(address, port),
334 transport_type(transport_type),
336 talk_base::SocketAddress server;
337 std::string username;
338 std::string password;
339 std::string transport_type;
343 virtual cricket::PortAllocator* CreatePortAllocator(
344 const std::vector<StunConfiguration>& stun_servers,
345 const std::vector<TurnConfiguration>& turn_configurations) = 0;
348 PortAllocatorFactoryInterface() {}
349 ~PortAllocatorFactoryInterface() {}
352 // Used to receive callbacks of DTLS identity requests.
353 class DTLSIdentityRequestObserver : public talk_base::RefCountInterface {
355 virtual void OnFailure(int error) = 0;
356 virtual void OnSuccess(const std::string& der_cert,
357 const std::string& der_private_key) = 0;
359 virtual ~DTLSIdentityRequestObserver() {}
362 class DTLSIdentityServiceInterface {
364 // Asynchronously request a DTLS identity, including a self-signed certificate
365 // and the private key used to sign the certificate, from the identity store
366 // for the given identity name.
367 // DTLSIdentityRequestObserver::OnSuccess will be called with the identity if
368 // the request succeeded; DTLSIdentityRequestObserver::OnFailure will be
369 // called with an error code if the request failed.
371 // Only one request can be made at a time. If a second request is called
372 // before the first one completes, RequestIdentity will abort and return
375 // |identity_name| is an internal name selected by the client to identify an
376 // identity within an origin. E.g. an web site may cache the certificates used
377 // to communicate with differnent peers under different identity names.
379 // |common_name| is the common name used to generate the certificate. If the
380 // certificate already exists in the store, |common_name| is ignored.
382 // |observer| is the object to receive success or failure callbacks.
384 // Returns true if either OnFailure or OnSuccess will be called.
385 virtual bool RequestIdentity(
386 const std::string& identity_name,
387 const std::string& common_name,
388 DTLSIdentityRequestObserver* observer) = 0;
390 virtual ~DTLSIdentityServiceInterface() {}
393 // PeerConnectionFactoryInterface is the factory interface use for creating
394 // PeerConnection, MediaStream and media tracks.
395 // PeerConnectionFactoryInterface will create required libjingle threads,
396 // socket and network manager factory classes for networking.
397 // If an application decides to provide its own threads and network
398 // implementation of these classes it should use the alternate
399 // CreatePeerConnectionFactory method which accepts threads as input and use the
400 // CreatePeerConnection version that takes a PortAllocatorFactoryInterface as
402 class PeerConnectionFactoryInterface : public talk_base::RefCountInterface {
407 disable_encryption(false),
408 disable_sctp_data_channels(false) {
410 bool disable_encryption;
411 bool disable_sctp_data_channels;
414 virtual void SetOptions(const Options& options) = 0;
415 virtual talk_base::scoped_refptr<PeerConnectionInterface>
416 CreatePeerConnection(
417 const PeerConnectionInterface::IceServers& configuration,
418 const MediaConstraintsInterface* constraints,
419 DTLSIdentityServiceInterface* dtls_identity_service,
420 PeerConnectionObserver* observer) = 0;
421 virtual talk_base::scoped_refptr<PeerConnectionInterface>
422 CreatePeerConnection(
423 const PeerConnectionInterface::IceServers& configuration,
424 const MediaConstraintsInterface* constraints,
425 PortAllocatorFactoryInterface* allocator_factory,
426 DTLSIdentityServiceInterface* dtls_identity_service,
427 PeerConnectionObserver* observer) = 0;
428 virtual talk_base::scoped_refptr<MediaStreamInterface>
429 CreateLocalMediaStream(const std::string& label) = 0;
431 // Creates a AudioSourceInterface.
432 // |constraints| decides audio processing settings but can be NULL.
433 virtual talk_base::scoped_refptr<AudioSourceInterface> CreateAudioSource(
434 const MediaConstraintsInterface* constraints) = 0;
436 // Creates a VideoSourceInterface. The new source take ownership of
437 // |capturer|. |constraints| decides video resolution and frame rate but can
439 virtual talk_base::scoped_refptr<VideoSourceInterface> CreateVideoSource(
440 cricket::VideoCapturer* capturer,
441 const MediaConstraintsInterface* constraints) = 0;
443 // Creates a new local VideoTrack. The same |source| can be used in several
445 virtual talk_base::scoped_refptr<VideoTrackInterface>
446 CreateVideoTrack(const std::string& label,
447 VideoSourceInterface* source) = 0;
449 // Creates an new AudioTrack. At the moment |source| can be NULL.
450 virtual talk_base::scoped_refptr<AudioTrackInterface>
451 CreateAudioTrack(const std::string& label,
452 AudioSourceInterface* source) = 0;
454 // Starts AEC dump using existing file. Takes ownership of |file| and passes
455 // it on to VoiceEngine (via other objects) immediately, which will take
456 // the ownerhip. If the operation fails, the file will be closed.
457 // TODO(grunell): Remove when Chromium has started to use AEC in each source.
458 // http://crbug.com/264611.
459 virtual bool StartAecDump(talk_base::PlatformFile file) = 0;
462 // Dtor and ctor protected as objects shouldn't be created or deleted via
464 PeerConnectionFactoryInterface() {}
465 ~PeerConnectionFactoryInterface() {} // NOLINT
468 // Create a new instance of PeerConnectionFactoryInterface.
469 talk_base::scoped_refptr<PeerConnectionFactoryInterface>
470 CreatePeerConnectionFactory();
472 // Create a new instance of PeerConnectionFactoryInterface.
473 // Ownership of |factory|, |default_adm|, and optionally |encoder_factory| and
474 // |decoder_factory| transferred to the returned factory.
475 talk_base::scoped_refptr<PeerConnectionFactoryInterface>
476 CreatePeerConnectionFactory(
477 talk_base::Thread* worker_thread,
478 talk_base::Thread* signaling_thread,
479 AudioDeviceModule* default_adm,
480 cricket::WebRtcVideoEncoderFactory* encoder_factory,
481 cricket::WebRtcVideoDecoderFactory* decoder_factory);
483 } // namespace webrtc
485 #endif // TALK_APP_WEBRTC_PEERCONNECTIONINTERFACE_H_