diff options
Diffstat (limited to 'spec')
-rw-r--r-- | spec/Call_Content_Interface_DTMF.xml | 230 | ||||
-rw-r--r-- | spec/Channel_Interface_DTMF.xml | 15 | ||||
-rw-r--r-- | spec/all.xml | 1 |
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"/> |