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