diff options
| -rw-r--r-- | spec/Call1_Content_Interface_DTMF1.xml | 56 | ||||
| -rw-r--r-- | spec/Call1_Content_Interface_Media.xml | 2 | ||||
| -rw-r--r-- | spec/Channel_Interface_DTMF1.xml | 346 | ||||
| -rw-r--r-- | spec/Channel_Type_Call1.xml | 27 | ||||
| -rw-r--r-- | spec/all.xml | 1 |
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> |