From ec870eb60c7d4c19c9a021a1eb0c4f9c9b56693b Mon Sep 17 00:00:00 2001 From: Peter Thatcher Date: Mon, 29 Dec 2014 12:06:31 -0800 Subject: [PATCH] Remove RTCPeerConnection.createDTMFSender and add RTCRtpSender.dtmf. --- webrtc.html | 146 +++++++++++++++++++++------------------------------- 1 file changed, 59 insertions(+), 87 deletions(-) diff --git a/webrtc.html b/webrtc.html index 438c97b31..2cd8dd3ca 100644 --- a/webrtc.html +++ b/webrtc.html @@ -1363,8 +1363,7 @@

Garbage collection

signalingState is closed, no such event handler can be triggered and it is therefore safe to garbage collect the object.

-

All RTCDTMFSender, - RTCDataChannel and +

All RTCDataChannel and MediaStreamTrack objects that are connected to a RTCPeerConnection are considered to have a strong reference to the RTCPeerConnection object.

@@ -2948,30 +2947,23 @@

Garbage Collection

Peer-to-peer DTMF

-

In order to send DTMF (phone keypad) values across an - RTCPeerConnection, the user agent needs to know which - MediaStreamTrack on which - RTCPeerConnection will carry the DTMF. This section - describes an interface on RTCPeerConnection to - associate DTMF capability with a MediaStreamTrack for - that RTCPeerConnection. Details of how DTMF is sent to - the other peer are described in [[!RTCWEB-AUDIO]].

+

This section describes an interface on RTCRtpSender + to send DTMF (phone keypad) values across an RTCPeerConnection. + Details of how DTMF is sent to the other peer are described in [[!RTCWEB-AUDIO]].

-

RTCPeerConnection Interface Extensions

+

RTCRtpSender Interface Extensions

The Peer-to-peer DTMF API extends the - RTCPeerConnection interface as described below.

+ RTCRtpSender interface as described below.

-
RTCDTMFSender createDTMFSender (MediaStreamTrack track)
+
readonly attribute RTCDTMFSender? dtmf;
-

The createDTMFSender() method creates an RTCDTMFSender - that references the given MediaStreamTrack. An RTCRtpSender for track - MUST already exist in theRTCPeerConnection object's set of senders; if not, throw an - InvalidParameter exception and abort these steps.

+

The dtmf attribute returns a RTCDTMFSender + which can be used to send DTMF. A null value indicates that + this RTCRtpSender cannot send DTMF.

@@ -2979,22 +2971,7 @@

RTCPeerConnection Interface Extensions

RTCDTMFSender

-

An RTCDTMFSender is created by calling the - createDTMFSender() method on an - RTCPeerConnection. This constructs an object that - exposes the functions required to send DTMF on the given - MediaStreamTrack.

-
-
readonly attribute boolean canInsertDTMF
- -
-

The canInsertDTMF - attribute MUST indicate if the RTCDTMFSender is - capable of sending DTMF.

-
-
void insertDTMF(in DOMString tones, optional long duration = 100, optional long interToneGap = 70)
@@ -3029,14 +3006,6 @@

RTCDTMFSender

user agent MUST run the following steps:

    -
  1. If the associated MediaStreamTrack is not - connected to the associated RTCPeerConnection, - return.
    2. - -
  2. If the canInsertDTMF - attribute is false, return.
    3. -
  3. Set the object's toneBuffer attribute to the value of the first argument, the RTCDTMFSender the currently playing tone.

    -
    readonly attribute MediaStreamTrack track
    - -
    -

    The track attribute MUST return the - MediaStreamTrack given as argument to the - createDTMFSender() method.

    -
    -
    attribute EventHandler ontonechange
    @@ -4662,15 +4623,13 @@

    Call Flow Browser to Browser

    DTMF Example

    -

    Examples assume that pc is a connected RTCPeerConnection, - and track is an audio track on that connection.

    +

    Examples assume that sender is an RTCRtpSender.

    Sending the DTMF signal "1234" with 500 ms duration per tone:

    -var sender = pc.createDTMFSender(track);
-if (sender.canInsertDTMF) {
+if (sender.dtmf) {
     var duration = 500;
-    sender.insertDTMF("1234", duration);
+    sender.dtmf.insertDTMF("1234", duration);
 } else
     log("DTMF function not available");
 
@@ -4680,55 +4639,64 @@ 
    DTMF Example
    
       lightKey(key) while the tone is playing (assuming that
       lightKey("") will darken all the keys):
    
       
    -var sender = pc.createDTMFSender(track);
-sender.ontonechange = function (e) {
-    if (!e.tone)
-        return;
-    // light up the key when playout starts
-    lightKey(e.tone);
-    // turn off the light after tone duration
-    setTimeout(lightKey, sender.duration, "");
-};
-sender.insertDTMF("1234");
+if (sender.dtmf) {
+  sender.dtmf.ontonechange = function (e) {
+      if (!e.tone)
+          return;
+      // light up the key when playout starts
+      lightKey(e.tone);
+      // turn off the light after tone duration
+      setTimeout(lightKey, sender.duration, "");
+  };
+  sender.dtmf.insertDTMF("1234");
+} else
+    log("DTMF function not available");
 
 
    
 
       
    Send a 1-second "1" tone followed by a 2-second "2" tone:
    
       
    -var sender = pc.createDTMFSender(track);
-sender.ontonechange = function (e) {
-    if (e.tone == "1")
-        sender.insertDTMF("2", 2000);
-};
-sender.insertDTMF("1", 1000);
+if (sender.dtmf) {
+  sender.dtmf.ontonechange = function (e) {
+      if (e.tone == "1")
+          sender.dtmf.insertDTMF("2", 2000);
+  };
+  sender.dtmf.isertDTMF("1", 1000);
+} else
+    log("DTMF function not available");
 
 
    
 
       
    It is always safe to append to the tone buffer. This example appends
       before any tone playout has started as well as during playout.
    
       
    -var sender = pc.createDTMFSender(track);
-sender.insertDTMF("123");
-// append more tones to the tone buffer before playout has begun
-sender.insertDTMF(sender.toneBuffer + "456");
-
-sender.ontonechange = function (e) {
-    if (e.tone == "1")
-        // append more tones when playout has begun
-        sender.insertDTMF(sender.toneBuffer + "789");
-};
+
+if (sender.dtmf) {
+  sender.dtmf.insertDTMF("123");
+  // append more tones to the tone buffer before playout has begun
+  sender.dtmf.insertDTMF(sender.toneBuffer + "456");
+
+  sender.dtmf.ontonechange = function (e) {
+      if (e.tone == "1")
+          // append more tones when playout has begun
+          sender.dtmf.insertDTMF(sender.toneBuffer + "789");
+  };
+} else
+    log("DTMF function not available");
 
 
    
 
       
    Send the DTMF signal "123" and abort after sending "2".
    
       
    -var sender = pc.createDTMFSender(track);
-sender.ontonechange = function (e) {
-    if (e.tone == "2")
-        // empty the buffer to not play any tone after "2"
-        sender.insertDTMF("");
-};
-sender.insertDTMF("123");
+if (sender.dtmf) {
+  sender.dtmf.ontonechange = function (e) {
+      if (e.tone == "2")
+          // empty the buffer to not play any tone after "2"
+          sender.dtmf.insertDTMF("");
+  };
+  sender.dtmf.insertDTMF("123");
+} else
+    log("DTMF function not available");

    Changes since June 4, 2014

    +
      +
    1. Removed RTCPeerConnection.createDTMFSender and added + RTCRtpSender.dtmf, along with corresponding examples. +
    1. Bug 25724: Allow garbage collection of closed PeerConnections