From 768fd24a2e8baf8283879887e26c6d189fb7384c Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Mon, 4 Nov 2013 16:31:25 +0000 Subject: [PATCH 09/12] 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 --- spec/Call1_Content_Interface_DTMF1.xml | 56 +++++- spec/Call1_Content_Interface_Media.xml | 2 +- spec/Channel_Interface_DTMF1.xml | 346 --------------------------------- spec/Channel_Type_Call1.xml | 27 +++ spec/all.xml | 1 - 5 files changed, 83 insertions(+), 349 deletions(-) delete mode 100644 spec/Channel_Interface_DTMF1.xml diff --git a/spec/Call1_Content_Interface_DTMF1.xml b/spec/Call1_Content_Interface_DTMF1.xml index 8d8f848..1410efa 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.

Emitted when 'w' or 'W', indicating "wait for the user to continue", is encountered while playing a DTMF string queued by - MultipleTones. Any queued DTMF events + MultipleTones or InitialTones. + Any queued DTMF events after the 'w', which have not yet been played, are placed in the DeferredTones property and copied into this signal's argument.

@@ -224,6 +226,58 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.DTMF tones have finished playing on streams in this channel.

+ + + + 0 + + + 1 + + + 2 + + + 3 + + + 4 + + + 5 + + + 6 + + + 7 + + + 8 + + + 9 + + + * + + + # + + + A + + + B + + + C + + + D + + + diff --git a/spec/Call1_Content_Interface_Media.xml b/spec/Call1_Content_Interface_Media.xml index 8b1fdaa..da2fd54 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"> Used by the CM to relay instructions from Channel.Interface.DTMF1 to the streaming + namespace="imt1.Call1">Content.Interface.DTMF1 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 616cb37..0000000 --- a/spec/Channel_Interface_DTMF1.xml +++ /dev/null @@ -1,346 +0,0 @@ - - - Copyright © 2005-2010 Collabora Limited - Copyright © 2005-2010 Nokia Corporation - Copyright © 2006 INdT - -

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.

- -

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.

- -

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.

- - - - - The only part of this spec that should - be used with a Call1 channel is the "InitialTones" property. - - - The Stream_IDs in this - interface can now be ignored by CMs. - - - - An interface that gives a Channel the ability to send DTMF - events over audio streams which have been established using the - Call1 - channel type. The event codes used are in common with those - defined in RFC4733, - and are listed in the DTMF_Event enumeration. - - - - The Stream_ID parameter became - vestigial. - - 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. - - - A numeric event code from the DTMF_Event enum. - - - -

Start sending a DTMF tone to all eligible streams in the channel. - Where possible, the tone will continue until - StopTone 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.

- - 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. - - -

Tone overlaping or queueing is not supported, so this method can only - be called if no DTMF tones are already being played.

- - - - - - The given stream ID was invalid. Deprecated, since stream IDs - are ignored. - - - - - There are no eligible audio streams. - - - - - DTMF tones are already being played. - - - - - - - The Stream_ID parameter became - vestigial. - - 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. - - - - Stop sending any DTMF tones which have been started using the - StartTone or - MultipleTones 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. - - On some protocols it might be impossible to cancel queued tones - immediately. - - - - - - - The given stream ID was invalid. Deprecated, since stream IDs - are ignored. - - - - - Continuous tones are not supported by this stream. Deprecated, - since stream IDs are ignored. - - - - - - - - The characters [pPxXwW,] must - also be supported. - - -

A string representation of one or more DTMF - events. Implementations of this method MUST support all of the - following characters in this string:

- -
    -
  • the digits 0-9, letters A-D and a-d, and symbols '*' and '#' - correspond to the members of DTMF_Event
    • - -
  • any of 'p', 'P', 'x', 'X' or ',' (comma) results in an - implementation-defined pause, typically for 3 seconds
    • - -
  • '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 TonesDeferred signal - with the rest of the string as its argument: see that signal - for details
    • -
- - - -

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.

- - -

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.

- -

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 audio/telephone-event.

- - -

Tone overlaping or queueing is not supported, so this method can only - be called if no DTMF tones are already being played.

- - - - - - The supplied Tones string was invalid. - - - - - There are no eligible audio streams. - - - - - DTMF tones are already being played. - - - - - - - - - Indicates whether there are DTMF tones currently being sent in the - channel. If so, the client should wait for - StoppedTones signal before trying to - send more tones. - - - - - - -

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.

- -

This should only be used with InitialAudio=true.

- -

This property is immutable (cannot change).

- - - - - - -

The tones waiting for the user to continue, if any.

- -

When this property is set to a non-empty value, - TonesDeferred is emitted. - When any tones are played (i.e. whenever - SendingTones is emitted), - this property is reset to the empty string.

- - - - - - - The new non-empty value of - DeferredTones. - - -

Emitted when 'w' or 'W', indicating "wait for the user to continue", - is encountered while playing a DTMF string queued by - MultipleTones or - InitialTones. Any queued DTMF events - after the 'w', which have not yet been played, are placed in the - DeferredTones property and copied - into this signal's argument.

- -

When the channel handler is ready to continue, it MAY pass the - value of DeferredTones to - MultipleTones, 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.

- -

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.

- - - - - - - DTMF string (one or more events) that is to be played. - - - -

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 - StopTone method.

- - - - - - - True if the DTMF tones were actively cancelled via - StopTone. - - -

DTMF tones have finished playing on streams in this channel.

- - - - - - 0 - - - 1 - - - 2 - - - 3 - - - 4 - - - 5 - - - 6 - - - 7 - - - 8 - - - 9 - - - * - - - # - - - A - - - B - - - C - - - D - - - - - diff --git a/spec/Channel_Type_Call1.xml b/spec/Channel_Type_Call1.xml index dcf4c6f..341b753 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. + + + +

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 Content.Interface.DTMF1.MultipleTones + method as soon as there is a suitable stream.

+ + +

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 "".

+ + +

This should only be used with InitialAudio=true, + and should only be requestable on protocols whose Call1 + channels will implement Content.Interface.DTMF1.

+ +

This property is immutable (cannot change).

+ + + diff --git a/spec/all.xml b/spec/all.xml index 20d15c8..1273e5d 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.Call1.

- -- 1.8.4.2