Abolish Channel.I.DTMF

Distribute its remaining non-obsolete functionality between
Content.I.DTMF and Channel.T.Call.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=46443

5 files changed, 83 insertions, 349 deletions

diff --git a/spec/Call1_Content_Interface_DTMF1.xml b/spec/Call1_Content_Interface_DTMF1.xml
index 8d8f848d..1410efab 100644
--- a/spec/Call1_Content_Interface_DTMF1.xml
+++ b/spec/Call1_Content_Interface_DTMF1.xml
@@ -183,7 +183,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <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
+          <tp:member-ref>MultipleTones</tp:member-ref> or <tp:dbus-ref
+            namespace="imt1.Channel.Type.Call1">InitialTones</tp:dbus-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>
@@ -224,6 +226,58 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <p>DTMF tones have finished playing on streams in this channel.</p>
       </tp:docstring>
     </signal>
+
+    <tp:enum name="DTMF_Event" type="y">
+      <tp:enumvalue suffix="Digit_0" value="0">
+        <tp:docstring>0</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Digit_1" value="1">
+        <tp:docstring>1</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Digit_2" value="2">
+        <tp:docstring>2</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Digit_3" value="3">
+        <tp:docstring>3</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Digit_4" value="4">
+        <tp:docstring>4</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Digit_5" value="5">
+        <tp:docstring>5</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Digit_6" value="6">
+        <tp:docstring>6</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Digit_7" value="7">
+        <tp:docstring>7</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Digit_8" value="8">
+        <tp:docstring>8</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Digit_9" value="9">
+        <tp:docstring>9</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Asterisk" value="10">
+        <tp:docstring>*</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Hash" value="11">
+        <tp:docstring>#</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Letter_A" value="12">
+        <tp:docstring>A</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Letter_B" value="13">
+        <tp:docstring>B</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Letter_C" value="14">
+        <tp:docstring>C</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Letter_D" value="15">
+        <tp:docstring>D</tp:docstring>
+      </tp:enumvalue>
+    </tp:enum>
+
   </interface>
 </node>
 <!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Call1_Content_Interface_Media.xml b/spec/Call1_Content_Interface_Media.xml
index 8b1fdaaf..da2fd540 100644
--- a/spec/Call1_Content_Interface_Media.xml
+++ b/spec/Call1_Content_Interface_Media.xml
@@ -478,7 +478,7 @@
       tp:name-for-bindings="DTMF_Change_Requested">
       <tp:docstring>
         Used by the CM to relay instructions from <tp:dbus-ref
-        namespace="imt1">Channel.Interface.DTMF1</tp:dbus-ref> to the streaming
+        namespace="imt1.Call1">Content.Interface.DTMF1</tp:dbus-ref> to the streaming
         implementation. If any contact in this call supports the
         telephone-event codec in their MediaDescription, this event should be
         sent as outlined in RFC 4733. Otherwise, it should be sent as an
diff --git a/spec/Channel_Interface_DTMF1.xml b/spec/Channel_Interface_DTMF1.xml
deleted file mode 100644
index 616cb377..00000000
--- a/spec/Channel_Interface_DTMF1.xml
+++ /dev/null
@@ -1,346 +0,0 @@
-<?xml version="1.0" ?>
-<node name="/Channel_Interface_DTMF1" 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="im.telepathy.v1.Channel.Interface.DTMF1">
-    <tp:requires interface="im.telepathy.v1.Channel.Type.Call1"/>
-
-    <tp:changed version="0.25.2">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 Stream_IDs in this
-      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 audio streams which have been established using the
-      <tp:dbus-ref namespace="imt1.Channel.Type">Call1</tp:dbus-ref>
-      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">
-      <tp:changed version="0.19.6">The <var>Stream_ID</var> parameter became
-        vestigial.</tp:changed>
-      <arg direction="in" name="Stream_ID" type="u">
-        <tp:docstring>This argument is included for backwards
-        compatibility and MUST be ignored by the implementations - the
-        tone SHOULD be sent to all eligible streams in the
-        channel.</tp:docstring>
-      </arg>
-      <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="im.telepathy.v1.Error.NetworkError" />
-        <tp:error name="im.telepathy.v1.Error.InvalidArgument">
-          <tp:docstring>
-            The given stream ID was invalid. Deprecated, since stream IDs
-            are ignored.
-          </tp:docstring>
-        </tp:error>
-        <tp:error name="im.telepathy.v1.Error.NotAvailable">
-          <tp:docstring>
-            There are no eligible audio streams.
-          </tp:docstring>
-        </tp:error>
-        <tp:error name="im.telepathy.v1.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:changed version="0.19.6">The <var>Stream_ID</var> parameter became
-        vestigial.</tp:changed>
-      <arg direction="in" name="Stream_ID" type="u">
-        <tp:docstring>This argument is included for backwards
-        compatibility and MUST be ignored by the implementations - the
-        sending SHOULD be stoped in all eligible streams in the
-        channel.</tp:docstring>
-      </arg>
-
-      <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="im.telepathy.v1.Error.NetworkError" />
-        <tp:error name="im.telepathy.v1.Error.InvalidArgument">
-          <tp:docstring>
-            The given stream ID was invalid. Deprecated, since stream IDs
-            are ignored.
-          </tp:docstring>
-        </tp:error>
-        <tp:error name="im.telepathy.v1.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">
-      <tp:added version="0.19.6" />
-      <tp:changed version="0.21.3">The characters [pPxXwW,] must
-        also be supported.</tp:changed>
-      <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="im.telepathy.v1.Error.NetworkError" />
-        <tp:error name="im.telepathy.v1.Error.InvalidArgument">
-          <tp:docstring>
-            The supplied Tones string was invalid.
-          </tp:docstring>
-        </tp:error>
-        <tp:error name="im.telepathy.v1.Error.NotAvailable">
-          <tp:docstring>
-            There are no eligible audio streams.
-          </tp:docstring>
-        </tp:error>
-        <tp:error name="im.telepathy.v1.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:added version="0.19.6" />
-      <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="InitialTones" tp:name-for-bindings="Initial_Tones"
-        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,
-          the connection manager should send the tones immediately after
-          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>
-
-    <property name="DeferredTones" tp:name-for-bindings="Deferred_Tones"
-        type="s" access="read">
-      <tp:added version="0.21.3" />
-      <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> or
-          <tp:member-ref>InitialTones</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">
-      <tp:added version="0.19.6" />
-      <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">
-      <tp:added version="0.19.6" />
-      <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>
-
-    <tp:enum name="DTMF_Event" type="y">
-      <tp:enumvalue suffix="Digit_0" value="0">
-        <tp:docstring>0</tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Digit_1" value="1">
-        <tp:docstring>1</tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Digit_2" value="2">
-        <tp:docstring>2</tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Digit_3" value="3">
-        <tp:docstring>3</tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Digit_4" value="4">
-        <tp:docstring>4</tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Digit_5" value="5">
-        <tp:docstring>5</tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Digit_6" value="6">
-        <tp:docstring>6</tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Digit_7" value="7">
-        <tp:docstring>7</tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Digit_8" value="8">
-        <tp:docstring>8</tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Digit_9" value="9">
-        <tp:docstring>9</tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Asterisk" value="10">
-        <tp:docstring>*</tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Hash" value="11">
-        <tp:docstring>#</tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Letter_A" value="12">
-        <tp:docstring>A</tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Letter_B" value="13">
-        <tp:docstring>B</tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Letter_C" value="14">
-        <tp:docstring>C</tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Letter_D" value="15">
-        <tp:docstring>D</tp:docstring>
-      </tp:enumvalue>
-    </tp:enum>
-  </interface>
-</node>
-<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Type_Call1.xml b/spec/Channel_Type_Call1.xml
index 4c30466a..11cc2458 100644
--- a/spec/Channel_Type_Call1.xml
+++ b/spec/Channel_Type_Call1.xml
@@ -1573,6 +1573,33 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       </tp:docstring>
     </tp:hct>
 
+    <property name="InitialTones" tp:name-for-bindings="Initial_Tones"
+        type="s" access="read" tp:immutable="yes" tp:requestable="sometimes">
+      <tp:added version="0.99.UNRELEASED" />
+      <tp:docstring>
+        <p>If non-empty in a channel request that will create a new channel,
+          the connection manager should send the tones immediately after
+          at least one eligible audio stream has been created in the
+          channel. Its semantics are equivalent to calling the <tp:dbus-ref
+            namespace="imt1.Call1">Content.Interface.DTMF1.MultipleTones</tp:dbus-ref>
+          method as soon as there is a suitable stream.</p>
+
+        <tp:rationale>
+          <p>We could have added a whole separate interface for this, but it
+            seemed like a waste of time; in protocols not supporting DTMF,
+            this property is easy to implement as non-requestable, immutable
+            and readable with value "".</p>
+        </tp:rationale>
+
+        <p>This should only be used with InitialAudio=true,
+          and should only be requestable on protocols whose Call1
+          channels will implement <tp:dbus-ref
+            namespace="imt1.Call1">Content.Interface.DTMF1</tp:dbus-ref>.</p>
+
+        <p>This property is immutable (cannot change).</p>
+      </tp:docstring>
+    </property>
+
   </interface>
 </node>
 <!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/all.xml b/spec/all.xml
index 48515d1a..650e3d4a 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -185,7 +185,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
        namespace='imt1.Channel.Type'>Call1</tp:dbus-ref>.</p>
     </tp:docstring>
 
-    <xi:include href="Channel_Interface_DTMF1.xml"/>
     <xi:include href="Channel_Interface_Hold1.xml"/>
    </tp:section>