For Call1, move the DTMF to the Content where it belongs

The only bit left in the channel interface is the InitialTones requestable
property.

3 files changed, 241 insertions, 5 deletions

diff --git a/spec/Call_Content_Interface_DTMF.xml b/spec/Call_Content_Interface_DTMF.xml
new file mode 100644
index 00000000..77c407e7
--- /dev/null
+++ b/spec/Call_Content_Interface_DTMF.xml
@@ -0,0 +1,230 @@
+<?xml version="1.0" ?>
+<node name="/Call_Content_Interface_DTMF" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+  <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright>
+  <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>
+  <tp:copyright>Copyright © 2006 INdT</tp:copyright>
+  <tp:license xmlns="http://www.w3.org/1999/xhtml">
+    <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+  </tp:license>
+  <interface name="org.freedesktop.Telepathy.Call1.Content.Interface.DTMF"
+	     tp:causes-havoc="experimental">
+    <tp:added version="0.UNRELEASED">(draft 1)</tp:added>
+    <tp:requires interface="org.freedesktop.Telepathy.Call1.Content"/>
+
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      An interface that gives audio Contents the ability to send DTMF events
+      which have been established using the Call1 channel
+      type. The event codes used are in common with those defined in <a
+      href="http://www.rfc-editor.org/rfc/rfc4733.txt">RFC4733</a>, and are
+      listed in the <tp:type>DTMF_Event</tp:type> enumeration.
+    </tp:docstring>
+
+    <method name="StartTone" tp:name-for-bindings="Start_Tone">
+      <arg direction="in" name="Event" type="y" tp:type="DTMF_Event">
+        <tp:docstring>A numeric event code from the DTMF_Event enum.</tp:docstring>
+      </arg>
+
+      <tp:docstring>
+        <p>Start sending a DTMF tone to all eligible streams in the channel.
+          Where possible, the tone will continue until
+          <tp:member-ref>StopTone</tp:member-ref> is called. On certain protocols,
+          it may only be possible to send events with a predetermined length. In
+          this case, the implementation MAY emit a fixed-length tone, and the
+          StopTone method call SHOULD return NotAvailable.</p>
+          <tp:rationale>
+            The client may wish to control the exact duration and timing of the
+            tones sent as a result of user's interaction with the dialpad, thus
+            starting and stopping the tone sending explicitly.
+          </tp:rationale>
+
+        <p>Tone overlaping or queueing is not supported, so this method can only
+          be called if no DTMF tones are already being played.</p>
+      </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+          <tp:docstring>
+	    The event id was invalid.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy">
+          <tp:docstring>
+            DTMF tones are already being played.
+          </tp:docstring>
+        </tp:error>
+      </tp:possible-errors>
+    </method>
+
+    <method name="StopTone" tp:name-for-bindings="Stop_Tone">
+      <tp:docstring>
+        Stop sending any DTMF tones which have been started using the
+        <tp:member-ref>StartTone</tp:member-ref> or
+        <tp:member-ref>MultipleTones</tp:member-ref> methods.
+        If there is no current tone, this method will do nothing.
+        If MultipleTones was used, the client should not assume the
+        sending has stopped immediately; instead, the client should wait
+        for the StoppedTones signal.
+        <tp:rationale>
+          On some protocols it might be impossible to cancel queued tones
+          immediately.
+        </tp:rationale>
+      </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
+        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+          <tp:docstring>
+            Continuous tones are not supported by this stream. Deprecated,
+            since stream IDs are ignored.
+          </tp:docstring>
+        </tp:error>
+      </tp:possible-errors>
+    </method>
+
+    <method name="MultipleTones" tp:name-for-bindings="Multiple_Tones">
+      <arg direction="in" name="Tones" type="s">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>A string representation of one or more DTMF
+            events. Implementations of this method MUST support all of the
+            following characters in this string:</p>
+
+          <ul>
+            <li>the digits 0-9, letters A-D and a-d, and symbols '*' and '#'
+              correspond to the members of <tp:type>DTMF_Event</tp:type></li>
+
+            <li>any of 'p', 'P', 'x', 'X' or ',' (comma) results in an
+              implementation-defined pause, typically for 3 seconds</li>
+
+            <li>'w' or 'W' waits for the user to continue, by stopping
+              interpretation of the string, and if there is more to be played,
+              emitting the <tp:member-ref>TonesDeferred</tp:member-ref> signal
+              with the rest of the string as its argument: see that signal
+              for details</li>
+          </ul>
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        <p>Send multiple DTMF events to all eligible streams in the channel.
+        Each tone will be played for an implementation-defined number of
+        milliseconds (typically 250ms), followed by a gap before the next tone
+        is played (typically 100ms). The
+        duration and gap are defined by the protocol or connection manager.</p>
+
+        <tp:rationale>
+          <p>In cases where the client knows in advance the tone sequence it
+            wants to send, it's easier to use this method than manually start
+            and stop each tone in the sequence.</p>
+
+          <p>The tone and gap lengths may need to vary for interoperability,
+            according to the protocol and other implementations' ability to
+            recognise tones. At the time of writing, GStreamer uses a
+            minimum of 250ms tones and 100ms gaps when playing in-band DTMF
+            in the normal audio stream, or 70ms tones and 50ms gaps when
+            encoding DTMF as <code>audio/telephone-event</code>.</p>
+        </tp:rationale>
+
+        <p>Tone overlaping or queueing is not supported, so this method can only
+          be called if no DTMF tones are already being played.</p>
+      </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+          <tp:docstring>
+            The supplied Tones string was invalid.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy">
+          <tp:docstring>
+            DTMF tones are already being played.
+          </tp:docstring>
+        </tp:error>
+      </tp:possible-errors>
+    </method>
+
+    <property name="CurrentlySendingTones"
+        tp:name-for-bindings="Currently_Sending_Tones" type="b" access="read">
+      <tp:docstring>
+        Indicates whether there are DTMF tones currently being sent in the
+        channel. If so, the client should wait for
+        <tp:member-ref>StoppedTones</tp:member-ref> signal before trying to
+        send more tones.
+      </tp:docstring>
+    </property>
+
+    <property name="DeferredTones" tp:name-for-bindings="Deferred_Tones"
+        type="s" access="read">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The tones waiting for the user to continue, if any.</p>
+
+        <p>When this property is set to a non-empty value,
+          <tp:member-ref>TonesDeferred</tp:member-ref> is emitted.
+          When any tones are played (i.e. whenever
+          <tp:member-ref>SendingTones</tp:member-ref> is emitted),
+          this property is reset to the empty string.</p>
+      </tp:docstring>
+    </property>
+
+    <signal name="TonesDeferred" tp:name-for-bindings="Tones_Deferred">
+      <tp:added version="0.21.3" />
+      <arg name="Tones" type="s">
+        <tp:docstring>The new non-empty value of
+          <tp:member-ref>DeferredTones</tp:member-ref>.</tp:docstring>
+      </arg>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Emitted when 'w' or 'W', indicating "wait for the user to continue",
+          is encountered while playing a DTMF string queued by
+          <tp:member-ref>MultipleTones</tp:member-ref>. Any queued DTMF events
+          after the 'w', which have not yet been played, are placed in the
+          <tp:member-ref>DeferredTones</tp:member-ref> property and copied
+          into this signal's argument.</p>
+
+        <p>When the channel handler is ready to continue, it MAY pass the
+          value of <tp:member-ref>DeferredTones</tp:member-ref> to
+          <tp:member-ref>MultipleTones</tp:member-ref>, to resume sending.
+          Alternatively, it MAY ignore the deferred tones, or even play
+          different tones instead. Any deferred tones are discarded the next
+          time a tone is played.</p>
+
+        <p>This signal SHOULD NOT be emitted if there is nothing left to play,
+          i.e. if the 'w' was the last character in the DTMF string.</p>
+      </tp:docstring>
+    </signal>
+
+    <signal name="SendingTones" tp:name-for-bindings="Sending_Tones">
+      <arg name="Tones" type="s">
+        <tp:docstring>DTMF string (one or more events) that is to be played.
+        </tp:docstring>
+      </arg>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>DTMF tone(s)are being sent to all eligible streams in the channel.
+        The signal is provided to indicating the fact that the streams are
+        currently being used to send one or more DTMF tones, so any other
+        media input is not getting through to the audio stream. It also
+        serves as a cue for the
+        <tp:member-ref>StopTone</tp:member-ref> method.</p>
+      </tp:docstring>
+    </signal>
+
+    <signal name="StoppedTones" tp:name-for-bindings="Stopped_Tones">
+      <arg name="Cancelled" type="b">
+        <tp:docstring>True if the DTMF tones were actively cancelled via
+          <tp:member-ref>StopTone</tp:member-ref>.</tp:docstring>
+      </arg>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>DTMF tones have finished playing on streams in this channel.</p>
+      </tp:docstring>
+    </signal>
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_DTMF.xml b/spec/Channel_Interface_DTMF.xml
index bb579a11..e328d67c 100644
--- a/spec/Channel_Interface_DTMF.xml
+++ b/spec/Channel_Interface_DTMF.xml
@@ -23,11 +23,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
       <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Call1"/>
     </tp:xor-requires>
+
+    <tp:changed version="0.UNRELEASED">The only part of this spec that should
+    be used with a Call1 channel is the "InitialTones" property.
+    </tp:changed>
+
     <tp:changed version="0.19.6">The <tp:type>Stream_ID</tp:type>s in this
-      interface should now be ignored by CMs. This is primarily to allow this
-      interface to be used with <tp:dbus-ref
-      namespace='ofdT.Channel.Type'>Call1</tp:dbus-ref>
-      channels.</tp:changed>
+      interface can now be ignored by CMs.
+    </tp:changed>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
       An interface that gives a Channel the ability to send DTMF events over
@@ -207,7 +210,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     </property>
 
     <property name="InitialTones" tp:name-for-bindings="Initial_Tones"
-        type="s" access="read">
+        type="s" access="read" tp:immutable="yes" tp:requestable="yes">
       <tp:added version="0.19.6" />
       <tp:docstring>
         <p>If non-empty in a channel request that will create a new channel,
@@ -215,6 +218,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           at least one eligible audio stream has been created in the
           channel.</p>
 
+        <p>This should only be used with InitialAudio=true.</p>
+
         <p>This property is immutable (cannot change).</p>
       </tp:docstring>
     </property>
diff --git a/spec/all.xml b/spec/all.xml
index 87bcf75b..72e4c491 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -241,6 +241,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
    <xi:include href="Call_Content.xml"/>
    <xi:include href="Call_Content_Interface_Media.xml"/>
    <xi:include href="Call_Interface_Mute.xml"/>
+   <xi:include href="Call_Content_Interface_DTMF.xml"/>
    <xi:include href="Call_Content_Interface_Video_Control.xml"/>
    <xi:include href="Call_Content_Interface_Audio_Control.xml"/>
    <xi:include href="Call_Content_Media_Description.xml"/>