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 // Accessor methods to active local streams.
170 virtual talk_base::scoped_refptr<StreamCollectionInterface>
173 // Accessor methods to remote streams.
174 virtual talk_base::scoped_refptr<StreamCollectionInterface>
175 remote_streams() = 0;
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;
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;
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;
193 virtual bool GetStats(StatsObserver* observer,
194 MediaStreamTrackInterface* track) = 0;
196 virtual talk_base::scoped_refptr<DataChannelInterface> CreateDataChannel(
197 const std::string& label,
198 const DataChannelInit* config) = 0;
200 virtual const SessionDescriptionInterface* local_description() const = 0;
201 virtual const SessionDescriptionInterface* remote_description() const = 0;
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
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;
233 // Returns the current SignalingState.
234 virtual SignalingState signaling_state() = 0;
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;
243 // Terminates all media and closes the transport.
244 virtual void Close() = 0;
247 // Dtor protected as objects shouldn't be deleted via this interface.
248 ~PeerConnectionInterface() {}
251 // PeerConnection callback interface. Application should implement these
253 class PeerConnectionObserver {
260 virtual void OnError() = 0;
262 // Triggered when the SignalingState changed.
263 virtual void OnSignalingChange(
264 PeerConnectionInterface::SignalingState new_state) {}
266 // Triggered when SignalingState or IceState have changed.
267 // TODO(bemasc): Remove once callers transition to OnSignalingChange.
268 virtual void OnStateChange(StateType state_changed) {}
270 // Triggered when media is received on a new stream from remote peer.
271 virtual void OnAddStream(MediaStreamInterface* stream) = 0;
273 // Triggered when a remote peer close a stream.
274 virtual void OnRemoveStream(MediaStreamInterface* stream) = 0;
276 // Triggered when a remote peer open a data channel.
277 // TODO(perkj): Make pure virtual.
278 virtual void OnDataChannel(DataChannelInterface* data_channel) {}
280 // Triggered when renegotiation is needed, for example the ICE has restarted.
281 virtual void OnRenegotiationNeeded() = 0;
283 // Called any time the IceConnectionState changes
284 virtual void OnIceConnectionChange(
285 PeerConnectionInterface::IceConnectionState new_state) {}
287 // Called any time the IceGatheringState changes
288 virtual void OnIceGatheringChange(
289 PeerConnectionInterface::IceGatheringState new_state) {}
291 // New Ice candidate have been found.
292 virtual void OnIceCandidate(const IceCandidateInterface* candidate) = 0;
294 // TODO(bemasc): Remove this once callers transition to OnIceGatheringChange.
295 // All Ice candidates have been found.
296 virtual void OnIceComplete() {}
299 // Dtor protected as objects shouldn't be deleted via this interface.
300 ~PeerConnectionObserver() {}
303 // Factory class used for creating cricket::PortAllocator that is used
304 // for ICE negotiation.
305 class PortAllocatorFactoryInterface : public talk_base::RefCountInterface {
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;
314 struct TurnConfiguration {
315 TurnConfiguration(const std::string& address,
317 const std::string& username,
318 const std::string& password,
319 const std::string& transport_type,
321 : server(address, port),
324 transport_type(transport_type),
326 talk_base::SocketAddress server;
327 std::string username;
328 std::string password;
329 std::string transport_type;
333 virtual cricket::PortAllocator* CreatePortAllocator(
334 const std::vector<StunConfiguration>& stun_servers,
335 const std::vector<TurnConfiguration>& turn_configurations) = 0;
338 PortAllocatorFactoryInterface() {}
339 ~PortAllocatorFactoryInterface() {}
342 // Used to receive callbacks of DTLS identity requests.
343 class DTLSIdentityRequestObserver : public talk_base::RefCountInterface {
345 virtual void OnFailure(int error) = 0;
346 virtual void OnSuccess(const std::string& der_cert,
347 const std::string& der_private_key) = 0;
349 virtual ~DTLSIdentityRequestObserver() {}
352 class DTLSIdentityServiceInterface {
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.
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
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.
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.
372 // |observer| is the object to receive success or failure callbacks.
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;
380 virtual ~DTLSIdentityServiceInterface() {}
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
392 class PeerConnectionFactoryInterface : public talk_base::RefCountInterface {
397 disable_encryption(false),
398 disable_sctp_data_channels(false) {
400 bool disable_encryption;
401 bool disable_sctp_data_channels;
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;
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;
426 // Creates a VideoSourceInterface. The new source take ownership of
427 // |capturer|. |constraints| decides video resolution and frame rate but can
429 virtual talk_base::scoped_refptr<VideoSourceInterface> CreateVideoSource(
430 cricket::VideoCapturer* capturer,
431 const MediaConstraintsInterface* constraints) = 0;
433 // Creates a new local VideoTrack. The same |source| can be used in several
435 virtual talk_base::scoped_refptr<VideoTrackInterface>
436 CreateVideoTrack(const std::string& label,
437 VideoSourceInterface* source) = 0;
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;
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;
452 // Dtor and ctor protected as objects shouldn't be created or deleted via
454 PeerConnectionFactoryInterface() {}
455 ~PeerConnectionFactoryInterface() {} // NOLINT
458 // Create a new instance of PeerConnectionFactoryInterface.
459 talk_base::scoped_refptr<PeerConnectionFactoryInterface>
460 CreatePeerConnectionFactory();
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);
473 } // namespace webrtc
475 #endif // TALK_APP_WEBRTC_PEERCONNECTIONINTERFACE_H_