dom/webidl/RTCPeerConnection.webidl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   4  * You can obtain one at http://mozilla.org/MPL/2.0/.
   5  *
   6  * The origin of this IDL file is
   7  * http://dev.w3.org/2011/webrtc/editor/webrtc.html#idl-def-RTCPeerConnection
   8  */
   9
  10 callback RTCSessionDescriptionCallback = void (mozRTCSessionDescription sdp);
  11 callback RTCPeerConnectionErrorCallback = void (DOMError error);
  12 callback VoidFunction = void ();
  13 callback RTCStatsCallback = void (RTCStatsReport report);
  14
  15 enum RTCSignalingState {
  16     "stable",
  17     "have-local-offer",
  18     "have-remote-offer",
  19     "have-local-pranswer",
  20     "have-remote-pranswer",
  21     "closed"
  22 };
  23
  24 enum RTCIceGatheringState {
  25     "new",
  26     "gathering",
  27     "complete"
  28 };
  29
  30 enum RTCIceConnectionState {
  31     "new",
  32     "checking",
  33     "connected",
  34     "completed",
  35     "failed",
  36     "disconnected",
  37     "closed"
  38 };
  39
  40 dictionary RTCDataChannelInit {
  41   boolean         ordered = true;
  42   unsigned short? maxRetransmitTime = null;
  43   unsigned short? maxRetransmits = null;
  44   DOMString       protocol = "";
  45   boolean         negotiated = false; // spec currently says 'true'; we disagree
  46   unsigned short? id = null;
  47
  48   // these are deprecated due to renaming in the spec, but still supported for Fx22
  49   boolean outOfOrderAllowed; // now ordered, and the default changes to keep behavior the same
  50   unsigned short maxRetransmitNum; // now maxRetransmits
  51   boolean preset; // now negotiated
  52   unsigned short stream; // now id
  53 };
  54
  55 dictionary RTCOfferOptions {
  56   long    offerToReceiveVideo;
  57   long    offerToReceiveAudio;
  58   boolean mozDontOfferDataChannel;
  59   boolean mozBundleOnly;
  60
  61   // TODO: Remove old constraint-like RTCOptions support soon (Bug 1064223).
  62   DeprecatedRTCOfferOptionsSet mandatory;
  63   sequence<DeprecatedRTCOfferOptionsSet> _optional;
  64 };
  65
  66 dictionary DeprecatedRTCOfferOptionsSet {
  67   boolean OfferToReceiveAudio;     // Note the uppercase 'O'
  68   boolean OfferToReceiveVideo;     // Note the uppercase 'O'
  69   boolean MozDontOfferDataChannel; // Note the uppercase 'M'
  70   boolean MozBundleOnly;           // Note the uppercase 'M'
  71 };
  72
  73 interface RTCDataChannel;
  74
  75 [Pref="media.peerconnection.enabled",
  76  JSImplementation="@mozilla.org/dom/peerconnection;1",
  77  Constructor (optional RTCConfiguration configuration,
  78               optional object? constraints)]
  79 // moz-prefixed until sufficiently standardized.
  80 interface mozRTCPeerConnection : EventTarget  {
  81   [Pref="media.peerconnection.identity.enabled"]
  82   void setIdentityProvider (DOMString provider,
  83                             optional DOMString protocol,
  84                             optional DOMString username);
  85   [Pref="media.peerconnection.identity.enabled"]
  86   void getIdentityAssertion();
  87   Promise<mozRTCSessionDescription> createOffer (optional RTCOfferOptions options);
  88   Promise<mozRTCSessionDescription> createAnswer ();
  89   Promise<void> setLocalDescription (mozRTCSessionDescription description);
  90   Promise<void> setRemoteDescription (mozRTCSessionDescription description);
  91   readonly attribute mozRTCSessionDescription? localDescription;
  92   readonly attribute mozRTCSessionDescription? remoteDescription;
  93   readonly attribute RTCSignalingState signalingState;
  94   void updateIce (optional RTCConfiguration configuration);
  95   Promise<void> addIceCandidate (mozRTCIceCandidate candidate);
  96   readonly attribute RTCIceGatheringState iceGatheringState;
  97   readonly attribute RTCIceConnectionState iceConnectionState;
  98   [Pref="media.peerconnection.identity.enabled"]
  99   readonly attribute RTCIdentityAssertion? peerIdentity;
 100
 101   [ChromeOnly]
 102   attribute DOMString id;
 103
 104   RTCConfiguration      getConfiguration ();
 105   [UnsafeInPrerendering]
 106   sequence<MediaStream> getLocalStreams ();
 107   [UnsafeInPrerendering]
 108   sequence<MediaStream> getRemoteStreams ();
 109   [UnsafeInPrerendering]
 110   MediaStream? getStreamById (DOMString streamId);
 111   void addStream (MediaStream stream);
 112   void removeStream (MediaStream stream);
 113
 114   // replaces addStream; fails if already added
 115   // because a track can be part of multiple streams, stream parameters
 116   // indicate which particular streams should be referenced in signaling
 117
 118   RTCRtpSender addTrack(MediaStreamTrack track,
 119                         MediaStream stream,
 120                         MediaStream... moreStreams);
 121   void removeTrack(RTCRtpSender sender);
 122
 123   sequence<RTCRtpSender> getSenders();
 124   sequence<RTCRtpReceiver> getReceivers();
 125
 126   void close ();
 127   attribute EventHandler onnegotiationneeded;
 128   attribute EventHandler onicecandidate;
 129   attribute EventHandler onsignalingstatechange;
 130   attribute EventHandler onaddstream;
 131   attribute EventHandler onaddtrack;  // replaces onaddstream; see AddTrackEvent
 132   attribute EventHandler onremovestream;
 133   attribute EventHandler oniceconnectionstatechange;
 134
 135   Promise<RTCStatsReport> getStats (MediaStreamTrack? selector);
 136
 137   // Data channel.
 138   RTCDataChannel createDataChannel (DOMString label,
 139                                     optional RTCDataChannelInit dataChannelDict);
 140   attribute EventHandler ondatachannel;
 141   [Pref="media.peerconnection.identity.enabled"]
 142   attribute EventHandler onidentityresult;
 143   [Pref="media.peerconnection.identity.enabled"]
 144   attribute EventHandler onpeeridentity;
 145   [Pref="media.peerconnection.identity.enabled"]
 146   attribute EventHandler onidpassertionerror;
 147   [Pref="media.peerconnection.identity.enabled"]
 148   attribute EventHandler onidpvalidationerror;
 149 };
 150
 151 // Legacy callback API
 152
 153 partial interface mozRTCPeerConnection {
 154
 155   // Dummy Promise<void> return values avoid "WebIDL.WebIDLError: error:
 156   // We have overloads with both Promise and non-Promise return types"
 157
 158   Promise<void> createOffer (RTCSessionDescriptionCallback successCallback,
 159                              RTCPeerConnectionErrorCallback failureCallback,
 160                              optional RTCOfferOptions options);
 161   Promise<void> createAnswer (RTCSessionDescriptionCallback successCallback,
 162                               RTCPeerConnectionErrorCallback failureCallback);
 163   Promise<void> setLocalDescription (mozRTCSessionDescription description,
 164                                      VoidFunction successCallback,
 165                                      RTCPeerConnectionErrorCallback failureCallback);
 166   Promise<void> setRemoteDescription (mozRTCSessionDescription description,
 167                                       VoidFunction successCallback,
 168                                       RTCPeerConnectionErrorCallback failureCallback);
 169   Promise<void> addIceCandidate (mozRTCIceCandidate candidate,
 170                                  VoidFunction successCallback,
 171                                  RTCPeerConnectionErrorCallback failureCallback);
 172   Promise<void> getStats (MediaStreamTrack? selector,
 173                           RTCStatsCallback successCallback,
 174                           RTCPeerConnectionErrorCallback failureCallback);
 175 };