667774e270eb00774c665a3363a550e9ce82b235
[platform/framework/web/crosswalk.git] / src / third_party / libjingle / source / talk / app / webrtc / peerconnectioninterface.h
1 /*
2  * libjingle
3  * Copyright 2012, Google Inc.
4  *
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>
72 #include <vector>
73
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"
81
82 namespace talk_base {
83 class Thread;
84 }
85
86 namespace cricket {
87 class PortAllocator;
88 class WebRtcVideoDecoderFactory;
89 class WebRtcVideoEncoderFactory;
90 }
91
92 namespace webrtc {
93 class AudioDeviceModule;
94 class MediaConstraintsInterface;
95
96 // MediaStream container interface.
97 class StreamCollectionInterface : public talk_base::RefCountInterface {
98  public:
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;
107
108  protected:
109   // Dtor protected as objects shouldn't be deleted via this interface.
110   ~StreamCollectionInterface() {}
111 };
112
113 class StatsObserver : public talk_base::RefCountInterface {
114  public:
115   virtual void OnComplete(const std::vector<StatsReport>& reports) = 0;
116
117  protected:
118   virtual ~StatsObserver() {}
119 };
120
121 class PeerConnectionInterface : public talk_base::RefCountInterface {
122  public:
123   // See http://dev.w3.org/2011/webrtc/editor/webrtc.html#state-definitions .
124   enum SignalingState {
125     kStable,
126     kHaveLocalOffer,
127     kHaveLocalPrAnswer,
128     kHaveRemoteOffer,
129     kHaveRemotePrAnswer,
130     kClosed,
131   };
132
133   // TODO(bemasc): Remove IceState when callers are changed to
134   // IceConnection/GatheringState.
135   enum IceState {
136     kIceNew,
137     kIceGathering,
138     kIceWaiting,
139     kIceChecking,
140     kIceConnected,
141     kIceCompleted,
142     kIceFailed,
143     kIceClosed,
144   };
145
146   enum IceGatheringState {
147     kIceGatheringNew,
148     kIceGatheringGathering,
149     kIceGatheringComplete
150   };
151
152   enum IceConnectionState {
153     kIceConnectionNew,
154     kIceConnectionChecking,
155     kIceConnectionConnected,
156     kIceConnectionCompleted,
157     kIceConnectionFailed,
158     kIceConnectionDisconnected,
159     kIceConnectionClosed,
160   };
161
162   struct IceServer {
163     std::string uri;
164     std::string username;
165     std::string password;
166   };
167   typedef std::vector<IceServer> IceServers;
168
169   // Accessor methods to active local streams.
170   virtual talk_base::scoped_refptr<StreamCollectionInterface>
171       local_streams() = 0;
172
173   // Accessor methods to remote streams.
174   virtual talk_base::scoped_refptr<StreamCollectionInterface>
175       remote_streams() = 0;
176
177   // Add a new MediaStream to be sent on this PeerConnection.
178   // Note that a SessionDescription negotiation is needed before the
179   // remote peer can receive the stream.
180   virtual bool AddStream(MediaStreamInterface* stream,
181                          const MediaConstraintsInterface* constraints) = 0;
182
183   // Remove a MediaStream from this PeerConnection.
184   // Note that a SessionDescription negotiation is need before the
185   // remote peer is notified.
186   virtual void RemoveStream(MediaStreamInterface* stream) = 0;
187
188   // Returns pointer to the created DtmfSender on success.
189   // Otherwise returns NULL.
190   virtual talk_base::scoped_refptr<DtmfSenderInterface> CreateDtmfSender(
191       AudioTrackInterface* track) = 0;
192
193   virtual bool GetStats(StatsObserver* observer,
194                         MediaStreamTrackInterface* track) = 0;
195
196   virtual talk_base::scoped_refptr<DataChannelInterface> CreateDataChannel(
197       const std::string& label,
198       const DataChannelInit* config) = 0;
199
200   virtual const SessionDescriptionInterface* local_description() const = 0;
201   virtual const SessionDescriptionInterface* remote_description() const = 0;
202
203   // Create a new offer.
204   // The CreateSessionDescriptionObserver callback will be called when done.
205   virtual void CreateOffer(CreateSessionDescriptionObserver* observer,
206                            const MediaConstraintsInterface* constraints) = 0;
207   // Create an answer to an offer.
208   // The CreateSessionDescriptionObserver callback will be called when done.
209   virtual void CreateAnswer(CreateSessionDescriptionObserver* observer,
210                             const MediaConstraintsInterface* constraints) = 0;
211   // Sets the local session description.
212   // JsepInterface takes the ownership of |desc| even if it fails.
213   // The |observer| callback will be called when done.
214   virtual void SetLocalDescription(SetSessionDescriptionObserver* observer,
215                                    SessionDescriptionInterface* desc) = 0;
216   // Sets the remote session description.
217   // JsepInterface takes the ownership of |desc| even if it fails.
218   // The |observer| callback will be called when done.
219   virtual void SetRemoteDescription(SetSessionDescriptionObserver* observer,
220                                     SessionDescriptionInterface* desc) = 0;
221   // Restarts or updates the ICE Agent process of gathering local candidates
222   // and pinging remote candidates.
223   virtual bool UpdateIce(const IceServers& configuration,
224                          const MediaConstraintsInterface* constraints) = 0;
225   // Provides a remote candidate to the ICE Agent.
226   // A copy of the |candidate| will be created and added to the remote
227   // description. So the caller of this method still has the ownership of the
228   // |candidate|.
229   // TODO(ronghuawu): Consider to change this so that the AddIceCandidate will
230   // take the ownership of the |candidate|.
231   virtual bool AddIceCandidate(const IceCandidateInterface* candidate) = 0;
232
233   // Returns the current SignalingState.
234   virtual SignalingState signaling_state() = 0;
235
236   // TODO(bemasc): Remove ice_state when callers are changed to
237   // IceConnection/GatheringState.
238   // Returns the current IceState.
239   virtual IceState ice_state() = 0;
240   virtual IceConnectionState ice_connection_state() = 0;
241   virtual IceGatheringState ice_gathering_state() = 0;
242
243   // Terminates all media and closes the transport.
244   virtual void Close() = 0;
245
246  protected:
247   // Dtor protected as objects shouldn't be deleted via this interface.
248   ~PeerConnectionInterface() {}
249 };
250
251 // PeerConnection callback interface. Application should implement these
252 // methods.
253 class PeerConnectionObserver {
254  public:
255   enum StateType {
256     kSignalingState,
257     kIceState,
258   };
259
260   virtual void OnError() = 0;
261
262   // Triggered when the SignalingState changed.
263   virtual void OnSignalingChange(
264      PeerConnectionInterface::SignalingState new_state) {}
265
266   // Triggered when SignalingState or IceState have changed.
267   // TODO(bemasc): Remove once callers transition to OnSignalingChange.
268   virtual void OnStateChange(StateType state_changed) {}
269
270   // Triggered when media is received on a new stream from remote peer.
271   virtual void OnAddStream(MediaStreamInterface* stream) = 0;
272
273   // Triggered when a remote peer close a stream.
274   virtual void OnRemoveStream(MediaStreamInterface* stream) = 0;
275
276   // Triggered when a remote peer open a data channel.
277   // TODO(perkj): Make pure virtual.
278   virtual void OnDataChannel(DataChannelInterface* data_channel) {}
279
280   // Triggered when renegotiation is needed, for example the ICE has restarted.
281   virtual void OnRenegotiationNeeded() = 0;
282
283   // Called any time the IceConnectionState changes
284   virtual void OnIceConnectionChange(
285       PeerConnectionInterface::IceConnectionState new_state) {}
286
287   // Called any time the IceGatheringState changes
288   virtual void OnIceGatheringChange(
289       PeerConnectionInterface::IceGatheringState new_state) {}
290
291   // New Ice candidate have been found.
292   virtual void OnIceCandidate(const IceCandidateInterface* candidate) = 0;
293
294   // TODO(bemasc): Remove this once callers transition to OnIceGatheringChange.
295   // All Ice candidates have been found.
296   virtual void OnIceComplete() {}
297
298  protected:
299   // Dtor protected as objects shouldn't be deleted via this interface.
300   ~PeerConnectionObserver() {}
301 };
302
303 // Factory class used for creating cricket::PortAllocator that is used
304 // for ICE negotiation.
305 class PortAllocatorFactoryInterface : public talk_base::RefCountInterface {
306  public:
307   struct StunConfiguration {
308     StunConfiguration(const std::string& address, int port)
309         : server(address, port) {}
310     // STUN server address and port.
311     talk_base::SocketAddress server;
312   };
313
314   struct TurnConfiguration {
315     TurnConfiguration(const std::string& address,
316                       int port,
317                       const std::string& username,
318                       const std::string& password,
319                       const std::string& transport_type,
320                       bool secure)
321         : server(address, port),
322           username(username),
323           password(password),
324           transport_type(transport_type),
325           secure(secure) {}
326     talk_base::SocketAddress server;
327     std::string username;
328     std::string password;
329     std::string transport_type;
330     bool secure;
331   };
332
333   virtual cricket::PortAllocator* CreatePortAllocator(
334       const std::vector<StunConfiguration>& stun_servers,
335       const std::vector<TurnConfiguration>& turn_configurations) = 0;
336
337  protected:
338   PortAllocatorFactoryInterface() {}
339   ~PortAllocatorFactoryInterface() {}
340 };
341
342 // Used to receive callbacks of DTLS identity requests.
343 class DTLSIdentityRequestObserver : public talk_base::RefCountInterface {
344  public:
345   virtual void OnFailure(int error) = 0;
346   virtual void OnSuccess(const std::string& der_cert,
347                          const std::string& der_private_key) = 0;
348  protected:
349   virtual ~DTLSIdentityRequestObserver() {}
350 };
351
352 class DTLSIdentityServiceInterface {
353  public:
354   // Asynchronously request a DTLS identity, including a self-signed certificate
355   // and the private key used to sign the certificate, from the identity store
356   // for the given identity name.
357   // DTLSIdentityRequestObserver::OnSuccess will be called with the identity if
358   // the request succeeded; DTLSIdentityRequestObserver::OnFailure will be
359   // called with an error code if the request failed.
360   //
361   // Only one request can be made at a time. If a second request is called
362   // before the first one completes, RequestIdentity will abort and return
363   // false.
364   //
365   // |identity_name| is an internal name selected by the client to identify an
366   // identity within an origin. E.g. an web site may cache the certificates used
367   // to communicate with differnent peers under different identity names.
368   //
369   // |common_name| is the common name used to generate the certificate. If the
370   // certificate already exists in the store, |common_name| is ignored.
371   //
372   // |observer| is the object to receive success or failure callbacks.
373   //
374   // Returns true if either OnFailure or OnSuccess will be called.
375   virtual bool RequestIdentity(
376       const std::string& identity_name,
377       const std::string& common_name,
378       DTLSIdentityRequestObserver* observer) = 0;
379
380   virtual ~DTLSIdentityServiceInterface() {}
381 };
382
383 // PeerConnectionFactoryInterface is the factory interface use for creating
384 // PeerConnection, MediaStream and media tracks.
385 // PeerConnectionFactoryInterface will create required libjingle threads,
386 // socket and network manager factory classes for networking.
387 // If an application decides to provide its own threads and network
388 // implementation of these classes it should use the alternate
389 // CreatePeerConnectionFactory method which accepts threads as input and use the
390 // CreatePeerConnection version that takes a PortAllocatorFactoryInterface as
391 // argument.
392 class PeerConnectionFactoryInterface : public talk_base::RefCountInterface {
393  public:
394   class Options {
395    public:
396     Options() :
397       disable_encryption(false),
398       disable_sctp_data_channels(false) {
399     }
400     bool disable_encryption;
401     bool disable_sctp_data_channels;
402   };
403
404   virtual void SetOptions(const Options& options) = 0;
405   virtual talk_base::scoped_refptr<PeerConnectionInterface>
406      CreatePeerConnection(
407          const PeerConnectionInterface::IceServers& configuration,
408          const MediaConstraintsInterface* constraints,
409          DTLSIdentityServiceInterface* dtls_identity_service,
410          PeerConnectionObserver* observer) = 0;
411   virtual talk_base::scoped_refptr<PeerConnectionInterface>
412       CreatePeerConnection(
413           const PeerConnectionInterface::IceServers& configuration,
414           const MediaConstraintsInterface* constraints,
415           PortAllocatorFactoryInterface* allocator_factory,
416           DTLSIdentityServiceInterface* dtls_identity_service,
417           PeerConnectionObserver* observer) = 0;
418   virtual talk_base::scoped_refptr<MediaStreamInterface>
419       CreateLocalMediaStream(const std::string& label) = 0;
420
421   // Creates a AudioSourceInterface.
422   // |constraints| decides audio processing settings but can be NULL.
423   virtual talk_base::scoped_refptr<AudioSourceInterface> CreateAudioSource(
424       const MediaConstraintsInterface* constraints) = 0;
425
426   // Creates a VideoSourceInterface. The new source take ownership of
427   // |capturer|. |constraints| decides video resolution and frame rate but can
428   // be NULL.
429   virtual talk_base::scoped_refptr<VideoSourceInterface> CreateVideoSource(
430       cricket::VideoCapturer* capturer,
431       const MediaConstraintsInterface* constraints) = 0;
432
433   // Creates a new local VideoTrack. The same |source| can be used in several
434   // tracks.
435   virtual talk_base::scoped_refptr<VideoTrackInterface>
436       CreateVideoTrack(const std::string& label,
437                        VideoSourceInterface* source) = 0;
438
439   // Creates an new AudioTrack. At the moment |source| can be NULL.
440   virtual talk_base::scoped_refptr<AudioTrackInterface>
441       CreateAudioTrack(const std::string& label,
442                        AudioSourceInterface* source) = 0;
443
444   // Starts AEC dump using existing file. Takes ownership of |file| and passes
445   // it on to VoiceEngine (via other objects) immediately, which will take
446   // the ownerhip. If the operation fails, the file will be closed.
447   // TODO(grunell): Remove when Chromium has started to use AEC in each source.
448   // http://crbug.com/264611.
449   virtual bool StartAecDump(talk_base::PlatformFile file) = 0;
450
451  protected:
452   // Dtor and ctor protected as objects shouldn't be created or deleted via
453   // this interface.
454   PeerConnectionFactoryInterface() {}
455   ~PeerConnectionFactoryInterface() {} // NOLINT
456 };
457
458 // Create a new instance of PeerConnectionFactoryInterface.
459 talk_base::scoped_refptr<PeerConnectionFactoryInterface>
460 CreatePeerConnectionFactory();
461
462 // Create a new instance of PeerConnectionFactoryInterface.
463 // Ownership of |factory|, |default_adm|, and optionally |encoder_factory| and
464 // |decoder_factory| transferred to the returned factory.
465 talk_base::scoped_refptr<PeerConnectionFactoryInterface>
466 CreatePeerConnectionFactory(
467     talk_base::Thread* worker_thread,
468     talk_base::Thread* signaling_thread,
469     AudioDeviceModule* default_adm,
470     cricket::WebRtcVideoEncoderFactory* encoder_factory,
471     cricket::WebRtcVideoDecoderFactory* decoder_factory);
472
473 }  // namespace webrtc
474
475 #endif  // TALK_APP_WEBRTC_PEERCONNECTIONINTERFACE_H_