diff options
| author | Leon Handreke <leonh@ndreke.de> | 2014-03-13 10:15:29 +0100 |
|---|---|---|
| committer | David Edmundson <kde@davidedmundson.co.uk> | 2014-04-11 23:56:35 +0200 |
| commit | b38e443c312157e86a5c6f4d0c07df7ecfc3a1cc (patch) | |
| tree | e8d5e073c91f17cd69f7a457a8c99423fe61b422 | |
| parent | 28e8c97b154af59acc3b4710fd000cf484da1059 (diff) | |
Sync spec to 0.99.7
41 files changed, 450 insertions, 1005 deletions
diff --git a/spec/Account_Interface_External_Password_Storage1.xml b/spec/Account_Interface_External_Password_Storage1.xml index 29d39327..bfc7fd9f 100644 --- a/spec/Account_Interface_External_Password_Storage1.xml +++ b/spec/Account_Interface_External_Password_Storage1.xml @@ -22,6 +22,7 @@ <interface name="im.telepathy.v1.Account.Interface.ExternalPasswordStorage1" tp:causes-havoc="experimental"> + <!-- https://bugs.freedesktop.org/show_bug.cgi?id=33485 --> <tp:added version="0.21.10">(draft 1)</tp:added> <tp:requires interface="im.telepathy.v1.Account"/> diff --git a/spec/Account_Interface_Hidden1.xml b/spec/Account_Interface_Hidden1.xml deleted file mode 100644 index 431e361e..00000000 --- a/spec/Account_Interface_Hidden1.xml +++ /dev/null @@ -1,65 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Account_Interface_Hidden1" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - - <tp:copyright>Copyright © 2010 Collabora Ltd.</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.Account.Interface.Hidden1" - tp:causes-havoc="outrageous"> - <tp:added version="0.21.10">(draft 1)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An interface for flagging certain accounts as hidden, so that they do - not appear in the account manager's standard lists of accounts. - Accounts whose <tp:member-ref>Hidden</tp:member-ref> property is - <code>True</code> are intended for non-interactive use (by - non-user-visible services), and appear on the <tp:dbus-ref - namespace='imt1'>AccountManager.Interface.Hidden1</tp:dbus-ref> - interface; in all other respects, they behave like any other - account.</p> - - <tp:rationale> - <p>XMPP, in particular, is increasingly used for purposes other than - instant messaging and VoIP. For instance, extensions exist for - inter-device bookmark synchronization.</p> - - <p>While obviously these services could re-use connections intended for - instant messaging, in some cases you might want to use a different - account. (Perhaps your bookmark sync provider is not your IM - provider.) This API allows such auxiliary accounts to exist in - Telepathy, while not being displayed in standard user interfaces for - IM, VoIP, and friends.</p> - </tp:rationale> - </tp:docstring> - - <property name="Hidden" tp:name-for-bindings="Hidden" - type="b" access="read" tp:immutable='aye'> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If <code>True</code>, this account is intended for non-interactive - use, and thus should not be presented to the user. It will not appear - in properties and signals on the main <tp:dbus-ref - namespace='imt1'>AccountManager</tp:dbus-ref> interface; instead, it - will show up on <tp:dbus-ref - namespace='imt1'>AccountManager.Interface.Hidden1</tp:dbus-ref>.</p> - </tp:docstring> - </property> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Account_Manager_Interface_Hidden1.xml b/spec/Account_Manager_Interface_Hidden1.xml deleted file mode 100644 index c63df8da..00000000 --- a/spec/Account_Manager_Interface_Hidden1.xml +++ /dev/null @@ -1,100 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Account_Manager_Interface_Hidden1" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright © 2010 Nokia Corporation</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.AccountManager.Interface.Hidden1" - tp:causes-havoc='kind of sketchy'> - <tp:requires interface='im.telepathy.v1.AccountManager'/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This interface lists accounts whose <tp:dbus-ref - namespace='imt1.Account.Interface.Hidden1'>Hidden</tp:dbus-ref> - property is <code>True</code>.</p> - </tp:docstring> - <tp:added version="0.21.10">first draft</tp:added> - - <property name="UsableHiddenAccounts" type="ao" access="read" - tp:name-for-bindings="Usable_Hidden_Accounts"> - <tp:docstring> - A list of valid (complete, usable) <tp:dbus-ref - namespace="im.telepathy.v1">Account</tp:dbus-ref>s intended - exclusively for noninteractive applications. These accounts are not - included in <tp:dbus-ref - namespace='imt1'>AccountManager.UsableAccounts</tp:dbus-ref>. Change - notification is via - <tp:member-ref>HiddenAccountUsabilityChanged</tp:member-ref>. - </tp:docstring> - </property> - - <property name="UnusableHiddenAccounts" type="ao" access="read" - tp:name-for-bindings="Unusable_Hidden_Accounts"> - <tp:docstring> - A list of incomplete or otherwise unusable <tp:dbus-ref - namespace="im.telepathy.v1">Account</tp:dbus-ref>s intended - exclusively for noninteractive applications. Change notification is via - <tp:member-ref>HiddenAccountUsabilityChanged</tp:member-ref>. - </tp:docstring> - </property> - - <signal name="HiddenAccountRemoved" - tp:name-for-bindings="Hidden_Account_Removed"> - <tp:docstring> - The given account has been removed from - <tp:member-ref>UsableHiddenAccounts</tp:member-ref> or - <tp:member-ref>UnusableHiddenAccounts</tp:member-ref>. - </tp:docstring> - - <arg name="Account" type="o"> - <tp:docstring> - An Account, which must not be used any more. - </tp:docstring> - </arg> - </signal> - - <signal name="HiddenAccountUsabilityChanged" - tp:name-for-bindings="Hidden_Account_Usability_Changed"> - <tp:docstring> - The validity of the given account has changed. New magic - accounts are also indicated by this signal, as an account validity - change (usually to True) on an account that did not previously exist. - - <tp:rationale> - This is effectively change notification for the valid and invalid - accounts lists. - </tp:rationale> - </tp:docstring> - - <arg name="Account" type="o"> - <tp:docstring> - An <tp:dbus-ref - namespace="im.telepathy.v1">Account</tp:dbus-ref>. - </tp:docstring> - </arg> - - <arg name="Usable" type="b"> - <tp:docstring> - True if the account is now valid. - </tp:docstring> - </arg> - </signal> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> 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/Call1_Interface_Mute.xml b/spec/Call1_Interface_Mute.xml index 21eb64cd..5b9daec1 100644 --- a/spec/Call1_Interface_Mute.xml +++ b/spec/Call1_Interface_Mute.xml @@ -19,6 +19,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:license> <interface name="im.telepathy.v1.Call1.Interface.Mute" tp:causes-havoc="experimental"> + <!-- https://bugs.freedesktop.org/show_bug.cgi?id=46442 --> <tp:added version="0.25.2">(as stable API)</tp:added> <tp:xor-requires> <tp:requires interface="im.telepathy.v1.Channel.Type.Call1"/> diff --git a/spec/Channel.xml b/spec/Channel.xml index fa208d26..36426e6d 100644 --- a/spec/Channel.xml +++ b/spec/Channel.xml @@ -323,11 +323,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>Each channel has a number of immutable properties (which cannot vary after the channel has been announced with <tp:dbus-ref - namespace='imt1.Connection.Interface.Requests'>NewChannels</tp:dbus-ref>), + namespace='imt1.Connection.Interface.Requests'>NewChannel</tp:dbus-ref>), provided to clients in the - <tp:dbus-ref namespace='imt1.Client.Observer'>ObserveChannels</tp:dbus-ref>, + <tp:dbus-ref namespace='imt1.Client.Observer'>ObserveChannel</tp:dbus-ref>, <tp:dbus-ref namespace='imt1.Client.Approver'>AddDispatchOperation</tp:dbus-ref> and - <tp:dbus-ref namespace='imt1.Client.Handler'>HandleChannels</tp:dbus-ref> + <tp:dbus-ref namespace='imt1.Client.Handler'>HandleChannel</tp:dbus-ref> methods to permit immediate identification of the channel. This interface contains immutable properties common to all channels. In brief:</p> diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml index 4225dc30..85789fdb 100644 --- a/spec/Channel_Dispatch_Operation.xml +++ b/spec/Channel_Dispatch_Operation.xml @@ -26,7 +26,7 @@ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A channel dispatch operation is an object in the ChannelDispatcher - representing a batch of unrequested channels being announced to + representing an unrequested channel being announced to client <tp:dbus-ref namespace="im.telepathy.v1.Client">Approver</tp:dbus-ref> processes.</p> @@ -36,50 +36,29 @@ from outgoing requests for channels.</p> <p>More specifically, whenever the <tp:dbus-ref - namespace="im.telepathy.v1">Connection.Interface.Requests.NewChannels</tp:dbus-ref> - signal contains channels whose <tp:dbus-ref + namespace="im.telepathy.v1">Connection.Interface.Requests.NewChannel</tp:dbus-ref> + signal contains a channel whose <tp:dbus-ref namespace="im.telepathy.v1.Channel">Requested</tp:dbus-ref> - property is false, one or more ChannelDispatchOperation - objects are created for those channels.</p> - - <p>(If some channels in a NewChannels signal are in different bundles, - this is an error. The channel dispatcher SHOULD recover by treating - the NewChannels signal as if it had been several NewChannels signals - each containing one channel.)</p> - - <p>First, the channel dispatcher SHOULD construct a list of all the - <tp:dbus-ref - namespace="im.telepathy.v1.Client">Handler</tp:dbus-ref>s - that could handle all the channels (based on their <tp:dbus-ref - namespace="im.telepathy.v1.Client.Handler">HandlerChannelFilter</tp:dbus-ref> - property), ordered by - priority in some implementation-dependent way. If there are handlers - which could handle all the channels, one channel dispatch operation - SHOULD be created for all the channels. If there are not, one channel - dispatch operation SHOULD be created for each channel, each with - a list of channel handlers that could handle that channel.</p> + property is false, a ChannelDispatchOperation + object is created for that channel.</p> <p>If no handler at all can handle a channel, the channel dispatcher SHOULD terminate that channel instead of creating a channel dispatcher for it. It is RECOMMENDED that the channel dispatcher closes - the channels using <tp:dbus-ref + the channel using <tp:dbus-ref namespace="im.telepathy.v1">Channel.Interface.Destroyable1.Destroy</tp:dbus-ref> if supported, or <tp:dbus-ref namespace="im.telepathy.v1">Channel.Close</tp:dbus-ref> otherwise.</p> - <p>When listing channel handlers, priority SHOULD be given to - channel handlers that are already handling channels from the same - bundle.</p> - <p>If a handler with <tp:dbus-ref namespace="im.telepathy.v1.Client.Handler">BypassApproval</tp:dbus-ref> - <code>= True</code> could handle all of the channels in the dispatch + <code>= True</code> could handle the channel in the dispatch operation, then the channel dispatcher SHOULD call <tp:dbus-ref - namespace="im.telepathy.v1.Client.Handler">HandleChannels</tp:dbus-ref> + namespace="im.telepathy.v1.Client.Handler">HandleChannel</tp:dbus-ref> on that handler, and (assuming the call succeeds) emit - <tp:member-ref>Finished</tp:member-ref> and stop processing those - channels without involving any approvers.</p> + <tp:member-ref>Finished</tp:member-ref> and stop processing that + channel without involving any approvers.</p> <tp:rationale> <p>Some channel types can be picked up "quietly" by an existing @@ -95,14 +74,14 @@ <p>Otherwise, the channel dispatcher SHOULD send the channel dispatch operation to all relevant approvers (in parallel) and wait for an - approver to claim the channels or request that they are handled. + approver to claim the channel or request that it is handled. See <tp:dbus-ref namespace="im.telepathy.v1.Client.Approver">AddDispatchOperation</tp:dbus-ref> for more details on this.</p> <p>Finally, if the approver requested it, the channel dispatcher SHOULD - send the channels to a handler.</p> + send the channel to a handler.</p> </tp:docstring> <property name="Interfaces" tp:name-for-bindings="Interfaces" @@ -118,7 +97,7 @@ <tp:docstring> The <tp:dbus-ref namespace="im.telepathy.v1">Connection</tp:dbus-ref> - with which the <tp:member-ref>Channels</tp:member-ref> are + with which the <tp:member-ref>Channel</tp:member-ref> is associated. The well-known bus name to use can be derived from this object path by removing the leading '/' and replacing all subsequent '/' by '.'. This property cannot change. @@ -131,72 +110,29 @@ The <tp:dbus-ref namespace="im.telepathy.v1">Account</tp:dbus-ref> with which the <tp:member-ref>Connection</tp:member-ref> - and <tp:member-ref>Channels</tp:member-ref> are + and <tp:member-ref>Channel</tp:member-ref> is associated. This property cannot change. </tp:docstring> </property> - <property name="Channels" tp:name-for-bindings="Channels" - type="a(oa{sv})" access="read" tp:type="Channel_Details[]"> - <tp:docstring> - The <tp:dbus-ref - namespace="im.telepathy.v1">Channel</tp:dbus-ref>s - to be dispatched, and their properties. Change notification is via - the <tp:member-ref>ChannelLost</tp:member-ref> signal (channels - cannot be added to this property, only removed). + <property name="Channel" type="o" tp:name-for-bindings="Channel" + access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The Channel object. Its well-known bus name is the same + as that of the <tp:member-ref>Connection</tp:member-ref>. + This property cannot change.</p> </tp:docstring> </property> - <signal name="ChannelLost" tp:name-for-bindings="Channel_Lost"> + <property name="ChannelProperties" access="read" type="a{sv}" + tp:type="Qualified_Property_Value_Map" + tp:name-for-bindings="Channel_Properties"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A channel has closed before it could be claimed or handled. If - this is emitted for the last remaining channel in a channel - dispatch operation, it MUST immediately be followed by - <tp:member-ref>Finished</tp:member-ref>.</p> - - <p>This signal MUST NOT be emitted until all Approvers that were - invoked have returned (successfully or with an error) from - their <tp:dbus-ref - namespace="im.telepathy.v1.Client.Approver">AddDispatchOperation</tp:dbus-ref> - method.</p> - - <tp:rationale> - <p>This means that Approvers can connect to the ChannelLost signal - in a race-free way. Non-approver processes that discover - a channel dispatch operation in some way (such as observers) - will have to follow the usual "connect to signals then recover - state" model - first connect to ChannelLost and - <tp:member-ref>Finished</tp:member-ref>, - then download <tp:member-ref>Channels</tp:member-ref> (and - on error, perhaps assume that the operation has already - Finished).</p> - </tp:rationale> + <p>Properties of the <tp:member-ref>Channel</tp:member-ref>, + equivalent to the properties in <tp:type>Channel_Details</tp:type>. + This property cannot change.</p> </tp:docstring> - - <arg name="Channel" type="o"> - <tp:docstring> - The <tp:dbus-ref - namespace="im.telepathy.v1">Channel</tp:dbus-ref> - that closed. - </tp:docstring> - </arg> - - <arg name="Error" type="s" tp:type="DBus_Error_Name"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The name of a D-Bus error indicating why the channel closed. If - no better reason can be found, - <code>im.telepathy.v1.Error.NotAvailable</code> MAY - be used as a fallback; this means that this error SHOULD NOT be - given any more specific meaning.</p> - </tp:docstring> - </arg> - - <arg name="Message" type="s"> - <tp:docstring> - A string associated with the D-Bus error. - </tp:docstring> - </arg> - </signal> + </property> <property name="PossibleHandlers" tp:name-for-bindings="Possible_Handlers" type="as" access="read" tp:type="DBus_Well_Known_Name[]"> @@ -205,7 +141,7 @@ <code>im.telepathy.v1.Client.</code>) of the possible <tp:dbus-ref namespace="im.telepathy.v1.Client">Handler</tp:dbus-ref>s - for these channels. The channel dispatcher MUST place the most + for this channel. The channel dispatcher MUST place the most preferred handlers first, according to some reasonable heuristic. As a result, approvers SHOULD use the first handler by default.</p> @@ -233,18 +169,18 @@ completed and the object has already gone. If this occurs, it indicates that another approver has asked for the bundle to be handled by a particular handler. The approver MUST NOT attempt - to interact with the channels further in this case, unless it is + to interact with the channel further in this case, unless it is separately invoked as the handler.</p> <p>Approvers which are also channel handlers SHOULD use <tp:member-ref>Claim</tp:member-ref> instead - of HandleWith to request that they can handle a channel bundle + of HandleWith to request that they can handle a channel themselves.</p> <p>(FIXME: list some possible errors)</p> <p>If the channel handler raises an error from <tp:dbus-ref - namespace="im.telepathy.v1.Client.Handler">HandleChannels</tp:dbus-ref>, + namespace="im.telepathy.v1.Client.Handler">HandleChannel</tp:dbus-ref>, this method MAY respond by raising that same error, even if it is not specifically documented here.</p> @@ -259,6 +195,14 @@ </tp:docstring> </arg> + <arg direction="in" type="x" tp:type="User_Action_Timestamp" name="UserActionTime"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The time at which user action occurred, + or 0 if no user action was involved in selecting the + Handler or approving handling.</p> + </tp:docstring> + </arg> + <tp:possible-errors> <tp:error name="im.telepathy.v1.Error.InvalidArgument"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> @@ -269,15 +213,15 @@ </tp:error> <tp:error name="im.telepathy.v1.Error.NotAvailable"> <tp:docstring> - The selected handler is temporarily unable to handle these - channels. + The selected handler is temporarily unable to handle this + channel. </tp:docstring> </tp:error> <tp:error name="im.telepathy.v1.Error.NotImplemented"> <tp:docstring> The selected handler is syntactically correct, but will never - be able to handle these channels (for instance because the channels - do not match its HandlerChannelFilter, or because HandleChannels + be able to handle this channel (for instance because the channel + does not match its HandlerChannelFilter, or because HandleChannel raised NotImplemented). </tp:docstring> </tp:error> @@ -286,10 +230,10 @@ At the time that HandleWith was called, this dispatch operation was processing an earlier call to HandleWith. The earlier call has now succeeded, so some Handler nominated by another approver is - now responsible for the channels. In this situation, the second + now responsible for the channel. In this situation, the second call to HandleWith MUST NOT return until the first one has returned successfully or unsuccessfully, and if the first call - to HandleChannels fails, the channel dispatcher SHOULD try to obey + to HandleChannel fails, the channel dispatcher SHOULD try to obey the choice of Handler made by the second call to HandleWith. </tp:docstring> </tp:error> @@ -302,7 +246,7 @@ internally. If this method is called successfully, the process calling this method becomes the handler for the channel, but <em>does not</em> have the <tp:dbus-ref - namespace="im.telepathy.v1.Client.Handler">HandleChannels</tp:dbus-ref> + namespace="im.telepathy.v1.Client.Handler">HandleChannel</tp:dbus-ref> method called on it.</p> <p>Clients that call Claim on channels but do not immediately @@ -341,7 +285,7 @@ <p>This method may fail because the dispatch operation has already been completed. Again, see HandleWith for more details. The approver - MUST NOT attempt to interact with the channels further in this + MUST NOT attempt to interact with the channel further in this case.</p> <p>(FIXME: list some other possible errors)</p> @@ -359,72 +303,6 @@ </tp:possible-errors> </method> - <method name="HandleWithTime" tp:name-for-bindings="Handle_With_Time"> - <tp:added version="0.19.6"> - At the time of writing, no released implementation of the - Channel Dispatcher implements this method; clients should fall - back to calling <tp:member-ref>HandleWith</tp:member-ref>. - </tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A variant of <tp:member-ref>HandleWith</tp:member-ref> allowing the - approver to pass an user action time. This timestamp will be passed - to the Handler when <tp:dbus-ref - namespace="im.telepathy.v1.Client.Handler">HandleChannels</tp:dbus-ref> - is called.</p> - </tp:docstring> - - <arg direction="in" type="s" tp:type="DBus_Bus_Name" name="Handler"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The well-known bus name (starting with - <code>im.telepathy.v1.Client.</code>) of the channel - handler that should handle the channel, or the empty string - if the client has no preferred channel handler.</p> - </tp:docstring> - </arg> - - <arg direction="in" type="x" tp:type="User_Action_Timestamp" name="UserActionTime"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The time at which user action occurred.</p> - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="im.telepathy.v1.Error.InvalidArgument"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The selected handler is non-empty, but is not a syntactically - correct <tp:type>DBus_Bus_Name</tp:type> or does not start with - "<code>im.telepathy.v1.Client.</code>". - </tp:docstring> - </tp:error> - <tp:error name="im.telepathy.v1.Error.NotAvailable"> - <tp:docstring> - The selected handler is temporarily unable to handle these - channels. - </tp:docstring> - </tp:error> - <tp:error name="im.telepathy.v1.Error.NotImplemented"> - <tp:docstring> - The selected handler is syntactically correct, but will never - be able to handle these channels (for instance because the channels - do not match its HandlerChannelFilter, or because HandleChannels - raised NotImplemented). - </tp:docstring> - </tp:error> - <tp:error name="im.telepathy.v1.Error.NotYours"> - <tp:docstring> - At the time that HandleWith was called, this dispatch operation was - processing an earlier call to HandleWith. The earlier call has - now succeeded, so some Handler nominated by another approver is - now responsible for the channels. In this situation, the second - call to HandleWith MUST NOT return until the first one has - returned successfully or unsuccessfully, and if the first call - to HandleChannels fails, the channel dispatcher SHOULD try to obey - the choice of Handler made by the second call to HandleWith. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - <signal name="Finished" tp:name-for-bindings="Finished"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Emitted when this dispatch operation finishes. The dispatch @@ -432,9 +310,7 @@ called on it.</p> <p>Approvers that have a user interface SHOULD stop notifying the user - about the channels in response to this signal; they MAY assume that - on errors, they would have received - <tp:member-ref>ChannelLost</tp:member-ref> first.</p> + about the channel in response to this signal.</p> <p>Its object path SHOULD NOT be reused for a subsequent dispatch operation; the ChannelDispatcher MUST choose object paths @@ -454,17 +330,34 @@ method.</p> <tp:rationale> - <p>This means that Approvers can connect to the ChannelLost signal + <p>This means that Approvers can connect to the Finished signal in a race-free way. Non-approver processes that discover a channel dispatch operation in some way (such as observers) will have to follow the usual "connect to signals then recover - state" model - first connect to - <tp:member-ref>ChannelLost</tp:member-ref> and - Finished, then download <tp:member-ref>Channels</tp:member-ref> + state" model - first connect to Finished, then download properties (and on error, perhaps assume that the operation has already Finished).</p> </tp:rationale> </tp:docstring> + + <arg name="Error" type="s" tp:type="DBus_Error_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If the channel dispatch operation finished because the + channel was successfully dispatched, the empty string.</p> + + <p>Otherwise, the name of a D-Bus error indicating why the channel + closed. If no better reason can be found, + <code>im.telepathy.v1.Error.NotAvailable</code> MAY + be used as a fallback; this means that this error SHOULD NOT be + given any more specific meaning.</p> + </tp:docstring> + </arg> + + <arg name="Message" type="s"> + <tp:docstring> + A string associated with the D-Bus error. + </tp:docstring> + </arg> </signal> </interface> diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml index 434dd119..1bf50e09 100644 --- a/spec/Channel_Dispatcher.xml +++ b/spec/Channel_Dispatcher.xml @@ -174,7 +174,7 @@ namespace="im.telepathy.v1.ChannelRequest">UserActionTime</tp:dbus-ref> property will be set to this value, and it will eventually be passed as the <code>User_Action_Time</code> parameter of <tp:dbus-ref - namespace="im.telepathy.v1.Client.Handler">HandleChannels</tp:dbus-ref>.</p> + namespace="im.telepathy.v1.Client.Handler">HandleChannel</tp:dbus-ref>.</p> </tp:docstring> </arg> @@ -200,7 +200,7 @@ <p>This is partly so the channel dispatcher can call <tp:dbus-ref - namespace="im.telepathy.v1.Client.Handler">HandleChannels</tp:dbus-ref> + namespace="im.telepathy.v1.Client.Handler">HandleChannel</tp:dbus-ref> on it, and partly so the channel dispatcher can recover state if it crashes and is restarted.</p> @@ -429,7 +429,7 @@ </tp:added> <tp:changed version="0.23.2">This method now returns <var>Delegated</var> and <var>Not_Delegated</var> instead of nothing. - <tp:dbus-ref namespace="imt1.Client.Handler">HandleChannels</tp:dbus-ref> + <tp:dbus-ref namespace="imt1.Client.Handler">HandleChannel</tp:dbus-ref> is now called once per <var>Channel</var> in <var>Channels</var>. </tp:changed> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> @@ -440,7 +440,7 @@ <p>For each <var>Channel</var> in <var>Channels</var>, if another <tp:dbus-ref namespace="imt1.Client">Handler</tp:dbus-ref> can be found, - <tp:dbus-ref namespace="imt1.Client.Handler">HandleChannels</tp:dbus-ref> + <tp:dbus-ref namespace="imt1.Client.Handler">HandleChannel</tp:dbus-ref> will be called on it until a <tp:dbus-ref namespace="imt1.Client">Handler</tp:dbus-ref> accepts it.</p> diff --git a/spec/Channel_Interface_Addressing1.xml b/spec/Channel_Interface_Addressing1.xml index ac6c198f..70c7bd47 100644 --- a/spec/Channel_Interface_Addressing1.xml +++ b/spec/Channel_Interface_Addressing1.xml @@ -18,6 +18,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:license> <interface name="im.telepathy.v1.Channel.Interface.Addressing1" tp:causes-havoc="experimental"> + <!-- https://bugs.freedesktop.org/show_bug.cgi?id=42918 --> <tp:added version="0.19.12">(as draft)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>This interface provides properties that can be used for @@ -54,7 +55,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:rationale> <p>While this seems redundant, since the scheme is included in <tp:member-ref>TargetURI</tp:member-ref>, it exists for constructing - <tp:dbus-ref namespace="im.telepathy.v1.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref> + <tp:dbus-ref namespace="imt1.Connection">RequestableChannelClasses</tp:dbus-ref> that support a limited set of URI schemes.</p> </tp:rationale> diff --git a/spec/Channel_Interface_Conference1.xml b/spec/Channel_Interface_Conference1.xml index ae2ee3b3..91ea7b47 100644 --- a/spec/Channel_Interface_Conference1.xml +++ b/spec/Channel_Interface_Conference1.xml @@ -50,7 +50,7 @@ If <tp:member-ref>InitialInviteeHandles</tp:member-ref> and <tp:member-ref>InitialInviteeIDs</tp:member-ref> are <var>Allowed_Properties</var> in <tp:dbus-ref - namespace="im.telepathy.v1.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>, + namespace="imt1.Connection">RequestableChannelClasses</tp:dbus-ref>, ad-hoc conferences to a set of contacts may be created by requesting a channel, specifying <tp:member-ref>InitialInviteeHandles</tp:member-ref> and/or @@ -204,7 +204,7 @@ TargetHandle of C1 into Cn), then immediately inviting the TargetHandle of C2, the TargetHandle of C3, etc. into Cn as well.</p> - <h4>Sample <tp:dbus-ref namespace='imt1.Connection.Interface.Requests' + <h4>Sample <tp:dbus-ref namespace='imt1.Connection' >RequestableChannelClasses</tp:dbus-ref></h4> <p>A GSM connection might advertise the following channel class for @@ -366,7 +366,7 @@ <tp:member-ref>InitialInviteeHandles</tp:member-ref> and <tp:member-ref>InitialInviteeIDs</tp:member-ref> are <var>Allowed_Properties</var> in <tp:dbus-ref - namespace='imt1.Connection.Interface.Requests' + namespace='imt1.Connection' >RequestableChannelClasses</tp:dbus-ref>, then requests with zero or one channel paths SHOULD also succeed; otherwise, clients SHOULD NOT make requests with zero or one paths for this property.</p> @@ -428,7 +428,7 @@ (as opposed to merging several channels into one new conference channel), this property SHOULD be requestable, and appear in the allowed properties in <tp:dbus-ref - namespace="im.telepathy.v1.Connection.Interface.Requests" + namespace="imt1.Connection" >RequestableChannelClasses</tp:dbus-ref>. Otherwise, this property SHOULD NOT be requestable, and its value SHOULD always be the empty list.</p> @@ -478,12 +478,12 @@ to the InitialInviteeIDs, and the target handles of the InitialChannels, with any duplicate handles removed. Because this property is immutable, its value SHOULD be computed before the - channel is announced via the NewChannels signal.</p> + channel is announced via the NewChannel signal.</p> <tp:rationale> <p>This simplifies identification of new channels in clients - they only have to look at one of the properties, not both. For example, - after either of the requests mentioned above, the NewChannels + after either of the requests mentioned above, the NewChannel signal would announce the channel with InitialChannels=[C1], InitialInviteeHandles=[rob, sjoerd], and InitialInviteeIDs=["rob@example.net", "sjoerd.example.com"].</p> @@ -521,7 +521,7 @@ <p>This property SHOULD be requestable, and appear in the allowed properties in <tp:dbus-ref - namespace="im.telepathy.v1.Connection.Interface.Requests" + namespace="imt1.Connection" >RequestableChannelClasses</tp:dbus-ref>, in protocols where invitations can have an accompanying text message.</p> diff --git a/spec/Channel_Interface_Credentials_Storage1.xml b/spec/Channel_Interface_Credentials_Storage1.xml index 03c665ed..00ecd5bd 100644 --- a/spec/Channel_Interface_Credentials_Storage1.xml +++ b/spec/Channel_Interface_Credentials_Storage1.xml @@ -19,6 +19,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:license> <interface name="im.telepathy.v1.Channel.Interface.CredentialsStorage1" tp:causes-havoc="experimental"> + <!-- https://bugs.freedesktop.org/show_bug.cgi?id=33485 --> <tp:added version="0.21.10">(draft 1)</tp:added> <tp:requires interface="im.telepathy.v1.Channel.Interface.SASLAuthentication1"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> 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_Interface_HTML1.xml b/spec/Channel_Interface_HTML1.xml index 486ad942..f435d429 100644 --- a/spec/Channel_Interface_HTML1.xml +++ b/spec/Channel_Interface_HTML1.xml @@ -21,6 +21,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <interface name="im.telepathy.v1.Channel.Interface.HTML1" tp:causes-havoc="unfinished"> + <!-- https://bugs.freedesktop.org/show_bug.cgi?id=15449 --> <tp:requires interface="im.telepathy.v1.Channel.Type.Text"/> <tp:added version="0.17.5">(draft version, not API-stable)</tp:added> diff --git a/spec/Channel_Interface_Mergeable_Conference1.xml b/spec/Channel_Interface_Mergeable_Conference1.xml index 2aea73a3..9efff2ae 100644 --- a/spec/Channel_Interface_Mergeable_Conference1.xml +++ b/spec/Channel_Interface_Mergeable_Conference1.xml @@ -22,6 +22,7 @@ <interface name="im.telepathy.v1.Channel.Interface.MergeableConference1" tp:causes-havoc="experimental"> + <!-- https://bugs.freedesktop.org/show_bug.cgi?id=31660 --> <tp:added version="0.19.0">(draft 1)</tp:added> <tp:requires interface="im.telepathy.v1.Channel.Interface.Conference1"/> diff --git a/spec/Channel_Interface_Picture1.xml b/spec/Channel_Interface_Picture1.xml index 3b555faa..068208c9 100644 --- a/spec/Channel_Interface_Picture1.xml +++ b/spec/Channel_Interface_Picture1.xml @@ -22,6 +22,7 @@ <interface name="im.telepathy.v1.Channel.Interface.Picture1" tp:causes-havoc="draft"> + <!-- https://bugs.freedesktop.org/show_bug.cgi?id=42653 --> <tp:requires interface="im.telepathy.v1.Channel"/> <tp:added version="0.25.0"/> <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" diff --git a/spec/Channel_Interface_SMS1.xml b/spec/Channel_Interface_SMS1.xml index 226505da..5e601c76 100644 --- a/spec/Channel_Interface_SMS1.xml +++ b/spec/Channel_Interface_SMS1.xml @@ -103,7 +103,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <p>This property is immutable (cannot change), and therefore SHOULD appear wherever immutable properties are reported, e.g. <tp:dbus-ref namespace="imt1.Connection.Interface.Requests" - >NewChannels</tp:dbus-ref> signals.</p> + >NewChannel</tp:dbus-ref> signals.</p> <tp:rationale> <p>Class 0 SMSes should be displayed immediately to the user, and diff --git a/spec/Channel_Interface_Splittable1.xml b/spec/Channel_Interface_Splittable1.xml index f675c5d4..a27cfd60 100644 --- a/spec/Channel_Interface_Splittable1.xml +++ b/spec/Channel_Interface_Splittable1.xml @@ -22,6 +22,7 @@ <interface name="im.telepathy.v1.Channel.Interface.Splittable1" tp:causes-havoc="experimental"> + <!-- https://bugs.freedesktop.org/show_bug.cgi?id=31660 --> <tp:added version="0.19.0">(draft 1)</tp:added> <tp:requires interface="im.telepathy.v1.Channel"/> diff --git a/spec/Channel_Interface_Tube1.xml b/spec/Channel_Interface_Tube1.xml index d97b0ae4..703a0ea0 100644 --- a/spec/Channel_Interface_Tube1.xml +++ b/spec/Channel_Interface_Tube1.xml @@ -81,7 +81,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <p>When receiving an incoming tube, this property is immutable and so advertised in the <tp:dbus-ref - namespace="im.telepathy.v1.Connection.Interface.Requests">NewChannels</tp:dbus-ref> + namespace="im.telepathy.v1.Connection.Interface.Requests">NewChannel</tp:dbus-ref> signal.</p> </tp:docstring> </property> diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml index 75290988..ba298208 100644 --- a/spec/Channel_Request.xml +++ b/spec/Channel_Request.xml @@ -272,13 +272,13 @@ The Handler should check each <tp:dbus-ref namespace="imt1">ChannelRequest</tp:dbus-ref> of the Requests_Satisfied parameter of - <tp:dbus-ref namespace="imt1.Client.Handler">HandleChannels</tp:dbus-ref> + <tp:dbus-ref namespace="imt1.Client.Handler">HandleChannel</tp:dbus-ref> for the hint. The first request containing the hint SHOULD be used and all further hints SHOULD be ignored. <tp:rationale> This covers the very unlikely case where - <tp:dbus-ref namespace="imt1.Client.Handler">HandleChannels</tp:dbus-ref> + <tp:dbus-ref namespace="imt1.Client.Handler">HandleChannel</tp:dbus-ref> satisfies two separate requests which have different <tp:member-ref>PreferredHandler</tp:member-ref>s. </tp:rationale> @@ -323,7 +323,7 @@ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The same immutable properties of the Channel that would appear in a <tp:dbus-ref namespace="imt1.Connection.Interface.Requests" - >NewChannels</tp:dbus-ref> signal.</p> + >NewChannel</tp:dbus-ref> signal.</p> </tp:docstring> </arg> diff --git a/spec/Channel_Type_Call1.xml b/spec/Channel_Type_Call1.xml index 4c30466a..c1284ea5 100644 --- a/spec/Channel_Type_Call1.xml +++ b/spec/Channel_Type_Call1.xml @@ -155,12 +155,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <p>When an incoming call occurs, something like the following <tp:dbus-ref - namespace="imt1.Connection.Interface.Requests">NewChannels</tp:dbus-ref> + namespace="imt1.Connection.Interface.Requests">NewChannel</tp:dbus-ref> signal will occur:</p> <blockquote> <pre> -<tp:dbus-ref namespace="imt1.Connection.Interface.Requests">NewChannels</tp:dbus-ref>([ +<tp:dbus-ref namespace="imt1.Connection.Interface.Requests">NewChannel</tp:dbus-ref>( /im/telepathy/v1/Connection/foo/bar/foo_40bar_2ecom/CallChannel, { ...<tp:dbus-ref namespace="imt1.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref @@ -174,7 +174,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ...<tp:member-ref>InitialAudioName</tp:member-ref>: "audio", ...<tp:member-ref>InitialVideoName</tp:member-ref>: "video", ...<tp:member-ref>MutableContents</tp:member-ref>: True, - }])</pre></blockquote> + })</pre></blockquote> <p>The <tp:member-ref>InitialAudio</tp:member-ref> and <tp:member-ref>InitialVideo</tp:member-ref> properties show that @@ -267,7 +267,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <h4>Requestable channel classes</h4> <p>The <tp:dbus-ref - namespace="imt1.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref> + namespace="imt1.Connection">RequestableChannelClasses</tp:dbus-ref> for <tp:dbus-ref namespace="imt1.Channel.Type">Call1</tp:dbus-ref> channels can be:</p> @@ -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.7" /> + <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/Channel_Type_Contact_Search1.xml b/spec/Channel_Type_Contact_Search1.xml index cfc3a62f..3a214bd9 100644 --- a/spec/Channel_Type_Contact_Search1.xml +++ b/spec/Channel_Type_Contact_Search1.xml @@ -37,7 +37,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ found.</p> <p>Connections that support contact search channels SHOULD have an entry - in <tp:dbus-ref namespace='imt1.Connection.Interface.Requests' + in <tp:dbus-ref namespace='imt1.Connection' >RequestableChannelClasses</tp:dbus-ref> with the <tp:dbus-ref namespace='imt1.Channel'>ChannelType</tp:dbus-ref> fixed to this interface, @@ -56,7 +56,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>Requests for channels of this type need only optionally specify the <tp:member-ref>Server</tp:member-ref> property (if it is an allowed property in the connection's <tp:dbus-ref - namespace='imt1.Connection.Interface.Requests'>RequestableChannelClasses</tp:dbus-ref>).</p> + namespace='imt1.Connection'>RequestableChannelClasses</tp:dbus-ref>).</p> <p>Before searching, the <tp:member-ref>AvailableSearchKeys</tp:member-ref> property should be @@ -296,7 +296,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:rationale> It can be in the <tp:dbus-ref - namespace="im.telepathy.v1.Connection.Interface.Requests">NewChannels</tp:dbus-ref> + namespace="im.telepathy.v1.Connection.Interface.Requests">NewChannel</tp:dbus-ref> signal for round-trip reduction. </tp:rationale> </tp:docstring> diff --git a/spec/Channel_Type_File_Transfer1.xml b/spec/Channel_Type_File_Transfer1.xml index 67ccf11e..1fc54fbb 100644 --- a/spec/Channel_Type_File_Transfer1.xml +++ b/spec/Channel_Type_File_Transfer1.xml @@ -159,7 +159,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>For each supported hash type, implementations SHOULD include an entry in <tp:dbus-ref - namespace="im.telepathy.v1.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref> + namespace="imt1.Connection">RequestableChannelClasses</tp:dbus-ref> with this property fixed to that hash type. If the protocol supports offering a file without a content hash, implementations SHOULD list this property in Allowed in a requestable channel class, mapping hash diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml index cebc2ecf..ca7fe587 100644 --- a/spec/Channel_Type_Text.xml +++ b/spec/Channel_Type_Text.xml @@ -1494,7 +1494,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ the connection manager MUST allow this, but SHOULD open a new channel to deliver those messages, signalling it as a new channel with the <tp:dbus-ref - namespace="imt1.Connection.Interface.Requests">NewChannels</tp:dbus-ref> + namespace="imt1.Connection.Interface.Requests">NewChannel</tp:dbus-ref> signal. The new channel should resemble the old channel, but have <tp:dbus-ref namespace='imt1.Channel'>Requested</tp:dbus-ref> = FALSE regardless of its previous value; the <tp:dbus-ref @@ -1524,7 +1524,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <li>UI calls Close on text channel</li> <li>text channel emits Closed and closes</li> <li>message arrives</li> - <li>new text channel is created, connection emits NewChannels</li> + <li>new text channel is created, connection emits NewChannel</li> <li>(the same or a different) UI handles it</li> </ul> diff --git a/spec/Client_Approver.xml b/spec/Client_Approver.xml index 03504c7e..7c3f13db 100644 --- a/spec/Client_Approver.xml +++ b/spec/Client_Approver.xml @@ -89,8 +89,8 @@ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A specification of the channels in which this approver is interested. The <tp:member-ref>AddDispatchOperation</tp:member-ref> - method should be called by the channel dispatcher whenever at least - one of the channels in a channel dispatch operation matches this + method should be called by the channel dispatcher whenever + the channel in a channel dispatch operation matches this description.</p> <p>This property works in exactly the same way as the @@ -130,46 +130,6 @@ </tp:rationale> </tp:docstring> - <arg name="Channels" direction="in" - type="a(oa{sv})" tp:type="Channel_Details[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The initial value of the <tp:dbus-ref - namespace="im.telepathy.v1">ChannelDispatchOperation.Channels</tp:dbus-ref> - property, containing the <tp:dbus-ref - namespace="im.telepathy.v1">Channel</tp:dbus-ref>s - to be dispatched and their properties.</p> - - <tp:rationale> - <p>This can't be signalled to the approver through the Properties - parameter of this method, because Channels is not an immutable - property.</p> - </tp:rationale> - - <p>This argument always contains all of the channels in the channel - dispatch operation, even if not all of them actually match - the <tp:member-ref>ApproverChannelFilter</tp:member-ref>.</p> - - <tp:rationale> - <p>This seems the least bad way to handle such a situation; - see the discussion on - <a href="http://bugs.freedesktop.org/show_bug.cgi?id=21090">bug - #21090</a>.</p> - </tp:rationale> - - <p>The actual channels to be dispatched may reduce as channels are - closed: this is signalled by <tp:dbus-ref - namespace="im.telepathy.v1">ChannelDispatchOperation.ChannelLost</tp:dbus-ref>. - </p> - - <p>Approvers SHOULD connect to ChannelLost and <tp:dbus-ref - namespace="im.telepathy.v1">ChannelDispatchOperation.Finished</tp:dbus-ref>. - (if desired) before returning from AddDispatchOperation, since - those signals are guaranteed not to be emitted until after all - AddDispatchOperation calls have returned (with success or failure) - or timed out.</p> - </tp:docstring> - </arg> - <arg name="DispatchOperation" type="o" direction="in"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The @@ -188,7 +148,11 @@ <tp:dbus-ref namespace="im.telepathy.v1.ChannelDispatchOperation">Account</tp:dbus-ref>, <tp:dbus-ref - namespace="im.telepathy.v1.ChannelDispatchOperation">Connection</tp:dbus-ref> + namespace="im.telepathy.v1.ChannelDispatchOperation">Connection</tp:dbus-ref>, + <tp:dbus-ref + namespace="im.telepathy.v1.ChannelDispatchOperation">Channel</tp:dbus-ref>, + <tp:dbus-ref + namespace="im.telepathy.v1.ChannelDispatchOperation">ChannelProperties</tp:dbus-ref> and <tp:dbus-ref namespace="im.telepathy.v1.ChannelDispatchOperation">PossibleHandlers</tp:dbus-ref> properties.</p> diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml index 7ea0b52a..aad76b22 100644 --- a/spec/Client_Handler.xml +++ b/spec/Client_Handler.xml @@ -162,11 +162,11 @@ im.telepathy.v1.Channel.Interface.MediaSignalling/video/h264=true </tp:docstring> </property> - <method name="HandleChannels" tp:name-for-bindings="Handle_Channels"> + <method name="HandleChannel" tp:name-for-bindings="Handle_Channel"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Called by the channel dispatcher when this client should handle these - channels, or when this client should present channels that it is already - handling to the user (e.g. bring them into the foreground).</p> + <p>Called by the channel dispatcher when this client should handle this + channel, or when this client should present a channel that it is already + handling to the user (e.g. bring it into the foreground).</p> <tp:rationale> <p>Clients are expected to know what channels they're already handling, @@ -178,20 +178,19 @@ im.telepathy.v1.Channel.Interface.MediaSignalling/video/h264=true <p>This method can raise any D-Bus error. If it does, the handler is assumed to have failed or crashed, and the channel dispatcher MUST recover in an implementation-specific way; it MAY - attempt to dispatch the channels to another handler, or close the - channels.</p> + attempt to dispatch the channel to another handler, or close the + channel.</p> - <p>If closing the channels, it is RECOMMENDED that the channel - dispatcher attempts to close the channels using - <tp:dbus-ref + <p>If closing the channel, it is RECOMMENDED that the channel + dispatcher attempts to use <tp:dbus-ref namespace="im.telepathy.v1">Channel.Close</tp:dbus-ref>, but resorts to calling <tp:dbus-ref namespace="im.telepathy.v1">Channel.Interface.Destroyable1.Destroy</tp:dbus-ref> (if available) or ignoring the channel (if not) if the same handler - repeatedly fails to handle channels.</p> + repeatedly fails to handle a channel.</p> - <p>After HandleChannels returns successfully, the client process is + <p>After HandleChannel returns successfully, the client process is considered to be responsible for the channel until it its unique name disappears from the bus.</p> @@ -207,7 +206,7 @@ im.telepathy.v1.Channel.Interface.MediaSignalling/video/h264=true <tp:docstring> The <tp:dbus-ref namespace="im.telepathy.v1">Account</tp:dbus-ref> - with which the channels are associated. The + with which the channel is associated. The well-known bus name to use is that of the <tp:dbus-ref namespace="im.telepathy.v1">AccountManager</tp:dbus-ref>. </tp:docstring> @@ -215,28 +214,35 @@ im.telepathy.v1.Channel.Interface.MediaSignalling/video/h264=true <arg name="Connection" type="o" direction="in"> <tp:docstring> - The Connection with which the channels are associated. The + The Connection with which the channel is associated. The well-known bus name to use can be derived from this object path by removing the leading '/' and replacing all subsequent '/' by '.'. </tp:docstring> </arg> - <arg name="Channels" type="a(oa{sv})" direction="in" - tp:type="Channel_Details[]"> - <tp:docstring> - The channels and their immutable properties. Their well-known - bus name is the same as that of the Connection. + <arg name="Channel" direction="in" type="o"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The Channel object. Its well-known bus name is the same + as that of the Connection.</p> + </tp:docstring> + </arg> + + <arg name="Channel_Properties" direction="in" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Properties of the channel, equivalent to + the properties in <tp:type>Channel_Details</tp:type>.</p> </tp:docstring> </arg> <arg name="Requests_Satisfied" type="ao" direction="in"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The requests satisfied by these channels.</p> + <p>The requests satisfied by this channel.</p> <tp:rationale> <p>If the handler implements Requests, this tells it - that these channels match previous <tp:dbus-ref + that this channel matches previous <tp:dbus-ref namespace="im.telepathy.v1.Client.Interface.Requests">AddRequest</tp:dbus-ref> calls that it may have received.</p> @@ -246,20 +252,19 @@ im.telepathy.v1.Channel.Interface.MediaSignalling/video/h264=true </tp:docstring> </arg> - <arg name="User_Action_Time" type="t" direction="in"> + <arg name="User_Action_Time" type="x" direction="in" + tp:type="User_Action_Timestamp"> <tp:docstring> The time at which user action occurred, or 0 if this channel is to be handled for some reason not involving user action. Handlers SHOULD use this for focus-stealing prevention, if applicable. - This property has the same semantic as <tp:type>User_Action_Timestamp</tp:type> - but is unsigned for historical reasons. </tp:docstring> </arg> <arg name="Handler_Info" type="a{sv}" direction="in"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Additional information about these channels. Currently defined + <p>Additional information about this channel. Currently defined keys are:</p> <dl> diff --git a/spec/Client_Handler_Future.xml b/spec/Client_Handler_Future.xml index 49a740d8..39dab918 100644 --- a/spec/Client_Handler_Future.xml +++ b/spec/Client_Handler_Future.xml @@ -35,6 +35,7 @@ <property name="BypassObservers" tp:name-for-bindings="Bypass_Observers" type="b" access="read"> + <!-- https://bugs.freedesktop.org/show_bug.cgi?id=30043 --> <tp:added version="0.21.2"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If true, channels destined for this handler are not passed to @@ -59,6 +60,7 @@ BypassObservers=true <property name="RelatedConferencesBypassApproval" tp:name-for-bindings="Related_Conferences_Bypass_Approval" type="b" access="read"> + <!-- https://bugs.freedesktop.org/show_bug.cgi?id=71228 --> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If true, channels destined for this handler that have the <tp:dbus-ref namespace="im.telepathy.v1.Channel.Interface" diff --git a/spec/Client_Interface_Requests.xml b/spec/Client_Interface_Requests.xml index f515abac..c96a29b3 100644 --- a/spec/Client_Interface_Requests.xml +++ b/spec/Client_Interface_Requests.xml @@ -54,7 +54,7 @@ <p>If the request succeeds and is given to the expected Handler, the Requests_Satisfied parameter to <tp:dbus-ref - namespace="im.telepathy.v1.Client.Handler">HandleChannels</tp:dbus-ref> + namespace="im.telepathy.v1.Client.Handler">HandleChannel</tp:dbus-ref> can be used to match the channel to a previous AddRequest call.</p> <tp:rationale> diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml index 1cfd5969..6cba94da 100644 --- a/spec/Client_Observer.xml +++ b/spec/Client_Observer.xml @@ -64,11 +64,11 @@ to the Observer.</p> </tp:rationale> - <p>Whenever a collection of new channels is signalled, the channel + <p>Whenever a new channel is signalled, the channel dispatcher will notify all running or activatable observers whose <tp:member-ref>ObserverChannelFilter</tp:member-ref> property (possibly as cached in the .client file) indicates that they are - interested in some of the channels.</p> + interested in that channel.</p> <p>Observers are activated for all channels in which they have registered an interest - incoming, outgoing or automatically created - @@ -82,7 +82,7 @@ instance, a Text logger needs to wait until pending messages have been downloaded), the channel dispatcher must wait (up to some timeout) for all observers to return from - <tp:member-ref>ObserveChannels</tp:member-ref> before letting anything + <tp:member-ref>ObserveChannel</tp:member-ref> before letting anything destructive happen. Destructive things (e.g. acknowledging messages) are defined to be done by handlers, therefore HandleWith and Claim aren't allowed to succeed until all observers are ready.</p> @@ -93,13 +93,13 @@ be implemented as observers by following these steps:</p> <ol> - <li><tp:member-ref>ObserveChannels</tp:member-ref>() is called + <li><tp:member-ref>ObserveChannel</tp:member-ref>() is called on the observer.</li> <li>The observer calls <tp:dbus-ref namespace="imt1.ChannelDispatchOperation">Claim</tp:dbus-ref>() on the CDO.</li> <li>The observer then returns from - <tp:member-ref>ObserveChannels</tp:member-ref>().</li> + <tp:member-ref>ObserveChannel</tp:member-ref>().</li> <li><tp:dbus-ref namespace="imt1.ChannelDispatchOperation">Claim</tp:dbus-ref> will return successfully if the channels were successfully @@ -109,7 +109,7 @@ <p>Non-interactive approvers implemented as observers SHOULD also set <tp:member-ref>DelayApprovers</tp:member-ref> to TRUE so that other Approvers are not called on until all observers - return from <tp:member-ref>ObserveChannels</tp:member-ref>. + return from <tp:member-ref>ObserveChannel</tp:member-ref>. This gives non-interactive approvers a chance to claim the channels before Approvers are called.</p> </tp:docstring> @@ -119,11 +119,11 @@ type="aa{sv}" access="read" tp:type="Channel_Class[]"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A specification of the channels in which this observer is - interested. The <tp:member-ref>ObserveChannels</tp:member-ref> method - should be called by the channel dispatcher whenever any of the new - channels in a <tp:dbus-ref - namespace="im.telepathy.v1.Connection.Interface.Requests">NewChannels</tp:dbus-ref> - signal match this description.</p> + interested. The <tp:member-ref>ObserveChannel</tp:member-ref> method + should be called by the channel dispatcher whenever the new + channel in a <tp:dbus-ref + namespace="im.telepathy.v1.Connection.Interface.Requests">NewChannel</tp:dbus-ref> + signal matches this description.</p> <p>Only certain D-Bus types have useful semantics for matching like this, so only certain types are allowed:</p> @@ -215,14 +215,14 @@ im.telepathy.v1.Channel.Requested b=true <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If true, upon the startup of this observer, <tp:dbus-ref - namespace="im.telepathy.v1.Client.Observer">ObserveChannels</tp:dbus-ref> + namespace="im.telepathy.v1.Client.Observer">ObserveChannel</tp:dbus-ref> will be called for every already existing channel matching its <tp:dbus-ref namespace="im.telepathy.v1.Client.Observer">ObserverChannelFilter</tp:dbus-ref></p> <p>When an activatable client having this property disappears from the bus and there are channels matching its ObserverChannelFilter, - ObserveChannels will be called immediately to reactivate it + ObserveChannel will be called immediately to reactivate it again. Such clients should specify this property in their <tt>.client</tt> file as follows:</p> @@ -245,28 +245,19 @@ Recover=true currently active at the time that it starts up.</p> </tp:rationale> - <p>When the ObserveChannels method is called due to observer recovery, + <p>When the ObserveChannel method is called due to observer recovery, the <var>Observer_Info</var> dictionary will contain one extra item mapping the key <code>"recovering"</code> to <code>True</code>.</p> </tp:docstring> </property> - <method name="ObserveChannels" tp:name-for-bindings="Observe_Channels"> + <method name="ObserveChannel" tp:name-for-bindings="Observe_Channel"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Called by the channel dispatcher when channels in which the + <p>Called by the channel dispatcher when a channel in which the observer has registered an interest are announced in a <tp:dbus-ref - namespace="im.telepathy.v1.Connection.Interface.Requests">NewChannels</tp:dbus-ref> + namespace="im.telepathy.v1.Connection.Interface.Requests">NewChannel</tp:dbus-ref> signal.</p> - <p>If the same NewChannels signal announces some channels that match - the filter, and some that do not, then only a subset of the channels - (those that do match the filter) are passed to this method.</p> - - <p>If the channel dispatcher will split up the channels from a single - NewChannels signal and dispatch them separately (for instance - because no installed Handler can handle all of them), it will call - ObserveChannels several times.</p> - <p>The observer MUST NOT return from this method call until it is ready for a handler for the channel to run (which may change the channel's state).</p> @@ -274,9 +265,9 @@ Recover=true <tp:rationale> <p>The channel dispatcher must wait for observers to start up, to avoid the following race: text channel logger (observer) gets - ObserveChannels, text channel handler gets + ObserveChannel, text channel handler gets <tp:dbus-ref - namespace="im.telepathy.v1.Client.Handler">HandleChannels</tp:dbus-ref> + namespace="im.telepathy.v1.Client.Handler">HandleChannel</tp:dbus-ref> channel handler starts up faster and acknowledges messages, logger never sees those messages.</p> </tp:rationale> @@ -297,7 +288,7 @@ Recover=true <tp:docstring> The <tp:dbus-ref namespace="im.telepathy.v1">Account</tp:dbus-ref> - with which the channels are associated. The + with which the channel is associated. The well-known bus name to use is that of the <tp:dbus-ref namespace="im.telepathy.v1">AccountManager</tp:dbus-ref>. </tp:docstring> @@ -307,20 +298,25 @@ Recover=true <tp:docstring> The <tp:dbus-ref namespace="im.telepathy.v1">Connection</tp:dbus-ref> - with which the channels are associated. The + with which the channel is associated. The well-known bus name to use can be derived from this object path by removing the leading '/' and replacing all subsequent '/' by '.'. </tp:docstring> </arg> - <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]" - direction="in"> - <tp:docstring> - The <tp:dbus-ref - namespace="im.telepathy.v1">Channel</tp:dbus-ref>s - and their properties. Their well-known bus names are all the same as - that of the Connection. + <arg name="Channel" direction="in" type="o"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The Channel object. Its well-known bus name is the same + as that of the Connection.</p> + </tp:docstring> + </arg> + + <arg name="Channel_Properties" direction="in" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Properties of the channel, equivalent to + the properties in <tp:type>Channel_Details</tp:type>.</p> </tp:docstring> </arg> @@ -328,8 +324,8 @@ Recover=true <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The path to the <tp:dbus-ref namespace="im.telepathy.v1">ChannelDispatchOperation</tp:dbus-ref> - for these channels, or the special value '/' if there is no - ChannelDispatchOperation (because the channels were requested, not + for this channel, or the special value '/' if there is no + ChannelDispatchOperation (because the channel was requested, not incoming).</p> <p>If the Observer calls <tp:dbus-ref @@ -338,12 +334,12 @@ Recover=true namespace="im.telepathy.v1.ChannelDispatchOperation">HandleWith</tp:dbus-ref> on the dispatch operation, it MUST be careful to avoid deadlock, since these methods cannot return until the Observer has returned - from <tp:member-ref>ObserveChannels</tp:member-ref>.</p> + from <tp:member-ref>ObserveChannel</tp:member-ref>.</p> <tp:rationale> <p>This allows an Observer to <tp:dbus-ref namespace="im.telepathy.v1.ChannelDispatchOperation">Claim</tp:dbus-ref> - a set of channels without having to match up calls to this method + a channel without having to match up calls to this method with calls to <tp:dbus-ref namespace="im.telepathy.v1.Client.Approver">AddDispatchOperation</tp:dbus-ref>.</p> </tp:rationale> @@ -354,25 +350,25 @@ Recover=true <tp:docstring> The <tp:dbus-ref namespace="im.telepathy.v1">ChannelRequest</tp:dbus-ref>s - satisfied by these channels. + satisfied by this channel. <tp:rationale> If the same process is an Observer and a Handler, it can be useful to be given this information as soon as possible (it will also be passed to <tp:dbus-ref - namespace="im.telepathy.v1.Client">Handler.HandleChannels</tp:dbus-ref>). + namespace="im.telepathy.v1.Client">Handler.HandleChannel</tp:dbus-ref>). </tp:rationale> </tp:docstring> </arg> <arg name="Observer_Info" type="a{sv}" direction="in"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Additional information about these channels. Currently defined + <p>Additional information about this channel. Currently defined keys are:</p> <dl> <dt><code>recovering</code> - b</dt> - <dd><code>True</code> if ObserveChannels was called for an existing + <dd><code>True</code> if ObserveChannel was called for an existing channel (due to the <tp:member-ref>Recover</tp:member-ref> property being <code>True</code>); <code>False</code> or omitted otherwise. @@ -405,7 +401,7 @@ Recover=true <tp:added version="0.21.11"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If true, the channel dispatcher will wait for - <tp:member-ref>ObserveChannels</tp:member-ref> to return + <tp:member-ref>ObserveChannel</tp:member-ref> to return before calling <tp:dbus-ref namespace="imt1.Client">Approver.AddDispatchOperation</tp:dbus-ref> on appropriate Approvers.</p> diff --git a/spec/Connection.xml b/spec/Connection.xml index 8fb350c2..a7f6ac5c 100644 --- a/spec/Connection.xml +++ b/spec/Connection.xml @@ -836,7 +836,7 @@ USA.</p> <p>The contact's attributes will always include at least the identifier that would be obtained by inspecting the handle - (<code>im.telepathy.v1.Connection/contact-id</code>).</p> + (<code>org.freedesktop.Telepathy.Connection/contact-id</code>).</p> </tp:docstring> </arg> @@ -846,6 +846,147 @@ USA.</p> </tp:possible-errors> </method> + <tp:mapping name="Channel_Class" array-name="Channel_Class_List"> + <tp:added version="0.17.11">(as stable API)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Mapping representing a class of channels that can be requested + from a connection manager, can be handled by a user interface, + are supported by a contact, etc.</p> + + <p>Classes of channel are identified by the fixed values of + a subset of their properties.</p> + + <p>Channel classes SHOULD always include the keys + <tp:dbus-ref>im.telepathy.v1.Channel.ChannelType</tp:dbus-ref> + and + <tp:dbus-ref>im.telepathy.v1.Channel.TargetHandleType</tp:dbus-ref>.</p> + </tp:docstring> + + <tp:member type="s" name="Key" tp:type="DBus_Qualified_Member"> + <tp:docstring> + A D-Bus interface name, followed by a dot and a D-Bus property name. + </tp:docstring> + </tp:member> + + <tp:member type="v" name="Value"> + <tp:docstring> + The value of the property. + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:struct name="Requestable_Channel_Class" + array-name="Requestable_Channel_Class_List"> + <tp:added version="0.17.11">(as stable API)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Structure representing a class of channels that can be requested, + identified by a set of properties that identify that class of + channel.</p> + + <tp:rationale> + <p>This will often just be the channel type and the handle type, + but can include other properties of the channel - for instance, + encrypted channels might require properties that + unencrypted channels do not, like an encryption key.</p> + </tp:rationale> + + <p>In some cases, these classes of channel may overlap, in the sense + that one class fixes all the properties that another class does, + plus some more properties.</p> + + <tp:rationale> + <p>For older clients to still be able to understand how to request + channels in the presence of a hypothetical "encryption" interface, + we'd need to represent it like this:</p> + + <ul> + <li>class 1: ChannelType = Text, TargetHandleType = CONTACT</li> + <li>class 2: Channel.ChannelType = Text, + Channel.TargetHandleType = CONTACT, + Encryption.Encrypted = TRUE</li> + </ul> + </tp:rationale> + </tp:docstring> + + <tp:member name="Fixed_Properties" type="a{sv}" + tp:type="Channel_Class"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The property values that identify this requestable channel class. + These properties MUST be included in requests for a channel of this + class, and MUST take these values.</p> + + <p>Clients that do not understand the semantics of all the + Fixed_Properties MUST NOT request channels of this class, since + they would be unable to avoid making an incorrect request.</p> + + <p>This implies that connection managers wishing to make channels + available to old or minimal clients SHOULD have a channel class + with the minimum number of Fixed_Properties, and MAY additionally + have channel classes with extra Fixed_Properties.</p> + + <p>Interface designers SHOULD avoid introducing fixed properties + whose types are not serializable in a <code>.manager</code> + file.</p> + + <tp:rationale> + <p>Connection managers with a fixed property that is not + serializable cannot have a complete <code>.manager</code> + file.</p> + </tp:rationale> + </tp:docstring> + </tp:member> + + <tp:member name="Allowed_Properties" type="as" + tp:type="DBus_Qualified_Member[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Properties that MAY be set when requesting a channel of this + channel type and handle type.</p> + + <p>This array MUST NOT include properties that are in the + Fixed_Properties mapping.</p> + + <p>Properties in this array may either be required or optional, + according to their documented semantics.</p> + + <tp:rationale> + <p>For instance, if + TargetHandleType takes a value that is not Handle_Type_None, + one or the other of TargetHandle and TargetID is required. + Clients are expected to understand the documented relationship + between the properties, so we do not have separate arrays + of required and optional properties.</p> + </tp:rationale> + </tp:docstring> + </tp:member> + </tp:struct> + + <property name="RequestableChannelClasses" access="read" + type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]" + tp:name-for-bindings="Requestable_Channel_Classes"> + <tp:added version="0.17.11">(as stable API)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The classes of channel that are expected to be available on this + connection, i.e. those for which + <tp:dbus-ref namespace="im.telepathy.v1.Connection.Interface.Requests">CreateChannel</tp:dbus-ref> can reasonably + be expected to succeed. User interfaces can use this information + to show or hide UI components.</p> + + <p>This property cannot change after the connection has gone to + state Connection_Status_Connected, so there is no change + notification (if the connection has context-dependent capabilities, + it SHOULD advertise support for all classes of channel that it might + support during its lifetime). Before this state has been reached, + the value of this property is undefined.</p> + + <tp:rationale> + <p>This is not on an optional interface, because connection + managers can always offer some sort of clue about the channel + classes they expect to support (at worst, they can announce + support for everything for which they have code).</p> + </tp:rationale> + </tp:docstring> + </property> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>This models a connection to a single user account on a communication service. Its basic capability is to provide the facility to request and diff --git a/spec/Connection_Interface_Communication_Policy1.xml b/spec/Connection_Interface_Communication_Policy1.xml index bbb14ab1..77913262 100644 --- a/spec/Connection_Interface_Communication_Policy1.xml +++ b/spec/Connection_Interface_Communication_Policy1.xml @@ -21,6 +21,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <interface name="im.telepathy.v1.Connection.Interface.CommunicationPolicy1" tp:causes-havoc="experimental"> + <!-- https://bugs.freedesktop.org/show_bug.cgi?id=24908 --> <tp:added version="0.21.1">(draft 1)</tp:added> <tp:requires interface="im.telepathy.v1.Connection.Interface.Presence1"/> diff --git a/spec/Connection_Interface_Contact_Capabilities1.xml b/spec/Connection_Interface_Contact_Capabilities1.xml index 51400cbf..d390a676 100644 --- a/spec/Connection_Interface_Contact_Capabilities1.xml +++ b/spec/Connection_Interface_Contact_Capabilities1.xml @@ -194,8 +194,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The contact's capabilities. These should be represented in the same way as in <tp:dbus-ref - namespace="im.telepathy.v1.Connection.Interface.Requests" - >RequestableChannelClasses</tp:dbus-ref>, + namespace="imt1.Connection">RequestableChannelClasses</tp:dbus-ref>, except that they may have more fixed properties or fewer allowed properties, to represent contacts who do not have all the capabilities of the connection.</p> diff --git a/spec/Connection_Interface_Forwarding1.xml b/spec/Connection_Interface_Forwarding1.xml index 28371ddb..cfe9ebaa 100644 --- a/spec/Connection_Interface_Forwarding1.xml +++ b/spec/Connection_Interface_Forwarding1.xml @@ -24,6 +24,7 @@ <interface name="im.telepathy.v1.Connection.Interface.Forwarding1" tp:causes-havoc="experimental"> + <!-- https://bugs.freedesktop.org/show_bug.cgi?id=13351 --> <tp:added version="0.19.6">(draft version, not API-stable)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> diff --git a/spec/Connection_Interface_Keepalive1.xml b/spec/Connection_Interface_Keepalive1.xml index 7a1ed940..c1a0b42f 100644 --- a/spec/Connection_Interface_Keepalive1.xml +++ b/spec/Connection_Interface_Keepalive1.xml @@ -23,6 +23,7 @@ <interface name="im.telepathy.v1.Connection.Interface.Keepalive1" tp:causes-havoc="experimental"> + <!-- https://bugs.freedesktop.org/show_bug.cgi?id=30512 --> <tp:requires interface="im.telepathy.v1.Connection"/> <tp:added version="0.21.2">(draft 1)</tp:added> diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml index c34b8c15..de72f22f 100644 --- a/spec/Connection_Interface_Requests.xml +++ b/spec/Connection_Interface_Requests.xml @@ -68,7 +68,7 @@ race condition would be likely to exist in some cases:</p> <ul> - <li>NewChannels or Get("Channels") includes a property P with + <li>NewChannel or Get("Channels") includes a property P with value V1</li> <li>Client creates a proxy object for the channel</li> <li>The value of P changes to V2</li> @@ -105,7 +105,7 @@ <method name="CreateChannel" tp:name-for-bindings="Create_Channel"> <tp:added version="0.17.11">(as stable API)</tp:added> <tp:changed version="0.17.14">It is now guaranteed that - CreateChannel returns the channel before NewChannels announces it + CreateChannel returns the channel before NewChannel announces it (the reverse was previously guaranteed).</tp:changed> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> @@ -153,12 +153,12 @@ <arg name="Channel" direction="out" type="o"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The Channel object, which MUST NOT be signalled with - <tp:member-ref>NewChannels</tp:member-ref> until after this method + <tp:member-ref>NewChannel</tp:member-ref> until after this method returns.</p> <tp:rationale> <p>This allows the requester to alter its handling of - NewChannels by knowing whether one of the channels satisfied + NewChannel by knowing whether the channel satisfied a request it made.</p> </tp:rationale> </tp:docstring> @@ -201,7 +201,7 @@ <tp:docstring> The request matched the fixed properties of a <tp:type>Requestable_Channel_Class</tp:type> in - <tp:member-ref>RequestableChannelClasses</tp:member-ref>, but the + <tp:dbus-ref namespace="imt1.Connection">RequestableChannelClasses</tp:dbus-ref>, but the allowed arguments did not make sense; for example, a <tp:dbus-ref namespace="im.telepathy.v1.Channel.Type">RoomList1</tp:dbus-ref> was requested, but the <tp:dbus-ref @@ -250,7 +250,7 @@ <tp:added version="0.17.12"/> <tp:changed version="0.17.14">It is now guaranteed that if the channel was created by this call to EnsureChannel, it's returned - before NewChannels announces it (the reverse was previously + before NewChannel announces it (the reverse was previously guaranteed).</tp:changed> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> @@ -297,12 +297,12 @@ <tp:docstring> The Channel object. If it was created as a result of this method call, it MUST NOT be signalled by - <tp:member-ref>NewChannels</tp:member-ref> until after this method + <tp:member-ref>NewChannel</tp:member-ref> until after this method returns. <tp:rationale> <p>This allows the requester to alter its handling of - NewChannels by knowing whether one of the channels satisfied + NewChannel by knowing whether the channel satisfied a request it made.</p> </tp:rationale> </tp:docstring> @@ -345,7 +345,7 @@ <tp:docstring> The request matched the fixed properties of a <tp:type>Requestable_Channel_Class</tp:type> in - <tp:member-ref>RequestableChannelClasses</tp:member-ref>, but the + <tp:dbus-ref namespace="imt1.Connection">RequestableChannelClasses</tp:dbus-ref>, but the allowed arguments did not make sense; for example, a <tp:dbus-ref namespace="im.telepathy.v1.Channel.Type">RoomList1</tp:dbus-ref> was requested, but the <tp:dbus-ref @@ -378,18 +378,15 @@ </tp:possible-errors> </method> - <signal name="NewChannels" tp:name-for-bindings="New_Channels"> - <tp:added version="0.17.11">(as stable API)</tp:added> - <tp:changed version="0.17.14">Added a guarantee of ordering - relative to the old NewChannel signal (now removed)</tp:changed> - <tp:changed version="0.27.1">Added recommendation against - announcing channels together</tp:changed> + <signal name="NewChannel" tp:name-for-bindings="New_Channel"> + <tp:added version="0.99.7"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A new channel has been created. The connection manager - SHOULD emit a single signal for each channel created.</p> + <p>A new channel has been created.</p> - <p>For example, joining a MUC Tube in XMPP requires joining the + <p>Unlike in some previous Telepathy versions, the connection manager + cannot emit a single signal for multiple channels. + For example, joining a MUC Tube in XMPP requires joining the corresponding MUC (chatroom). Either the connection manager should announce a new <tp:dbus-ref namespace="imt1.Channel.Type">Text</tp:dbus-ref> channel @@ -405,9 +402,17 @@ </tp:rationale> </tp:docstring> - <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]"> + <arg name="Channel" type="o"> <tp:docstring> - The channels and their details. + The object path of the channel. + </tp:docstring> + </arg> + + <arg name="Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same properties of the channel that would appear in the + <tp:type>Channel_Details</tp:type> struct.</p> </tp:docstring> </arg> </signal> @@ -418,7 +423,7 @@ <tp:docstring> A list of all the channels which currently exist on this connection. Change notification is via the - <tp:member-ref>NewChannels</tp:member-ref> and + <tp:member-ref>NewChannel</tp:member-ref> and <tp:member-ref>ChannelClosed</tp:member-ref> signals. </tp:docstring> </property> @@ -444,147 +449,6 @@ </arg> </signal> - <tp:mapping name="Channel_Class" array-name="Channel_Class_List"> - <tp:added version="0.17.11">(as stable API)</tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Mapping representing a class of channels that can be requested - from a connection manager, can be handled by a user interface, - are supported by a contact, etc.</p> - - <p>Classes of channel are identified by the fixed values of - a subset of their properties.</p> - - <p>Channel classes SHOULD always include the keys - <tp:dbus-ref>im.telepathy.v1.Channel.ChannelType</tp:dbus-ref> - and - <tp:dbus-ref>im.telepathy.v1.Channel.TargetHandleType</tp:dbus-ref>.</p> - </tp:docstring> - - <tp:member type="s" name="Key" tp:type="DBus_Qualified_Member"> - <tp:docstring> - A D-Bus interface name, followed by a dot and a D-Bus property name. - </tp:docstring> - </tp:member> - - <tp:member type="v" name="Value"> - <tp:docstring> - The value of the property. - </tp:docstring> - </tp:member> - </tp:mapping> - - <tp:struct name="Requestable_Channel_Class" - array-name="Requestable_Channel_Class_List"> - <tp:added version="0.17.11">(as stable API)</tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Structure representing a class of channels that can be requested, - identified by a set of properties that identify that class of - channel.</p> - - <tp:rationale> - <p>This will often just be the channel type and the handle type, - but can include other properties of the channel - for instance, - encrypted channels might require properties that - unencrypted channels do not, like an encryption key.</p> - </tp:rationale> - - <p>In some cases, these classes of channel may overlap, in the sense - that one class fixes all the properties that another class does, - plus some more properties.</p> - - <tp:rationale> - <p>For older clients to still be able to understand how to request - channels in the presence of a hypothetical "encryption" interface, - we'd need to represent it like this:</p> - - <ul> - <li>class 1: ChannelType = Text, TargetHandleType = CONTACT</li> - <li>class 2: Channel.ChannelType = Text, - Channel.TargetHandleType = CONTACT, - Encryption.Encrypted = TRUE</li> - </ul> - </tp:rationale> - </tp:docstring> - - <tp:member name="Fixed_Properties" type="a{sv}" - tp:type="Channel_Class"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The property values that identify this requestable channel class. - These properties MUST be included in requests for a channel of this - class, and MUST take these values.</p> - - <p>Clients that do not understand the semantics of all the - Fixed_Properties MUST NOT request channels of this class, since - they would be unable to avoid making an incorrect request.</p> - - <p>This implies that connection managers wishing to make channels - available to old or minimal clients SHOULD have a channel class - with the minimum number of Fixed_Properties, and MAY additionally - have channel classes with extra Fixed_Properties.</p> - - <p>Interface designers SHOULD avoid introducing fixed properties - whose types are not serializable in a <code>.manager</code> - file.</p> - - <tp:rationale> - <p>Connection managers with a fixed property that is not - serializable cannot have a complete <code>.manager</code> - file.</p> - </tp:rationale> - </tp:docstring> - </tp:member> - - <tp:member name="Allowed_Properties" type="as" - tp:type="DBus_Qualified_Member[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Properties that MAY be set when requesting a channel of this - channel type and handle type.</p> - - <p>This array MUST NOT include properties that are in the - Fixed_Properties mapping.</p> - - <p>Properties in this array may either be required or optional, - according to their documented semantics.</p> - - <tp:rationale> - <p>For instance, if - TargetHandleType takes a value that is not Handle_Type_None, - one or the other of TargetHandle and TargetID is required. - Clients are expected to understand the documented relationship - between the properties, so we do not have separate arrays - of required and optional properties.</p> - </tp:rationale> - </tp:docstring> - </tp:member> - </tp:struct> - - <property name="RequestableChannelClasses" access="read" - type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]" - tp:name-for-bindings="Requestable_Channel_Classes"> - <tp:added version="0.17.11">(as stable API)</tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The classes of channel that are expected to be available on this - connection, i.e. those for which - <tp:member-ref>CreateChannel</tp:member-ref> can reasonably - be expected to succeed. User interfaces can use this information - to show or hide UI components.</p> - - <p>This property cannot change after the connection has gone to - state Connection_Status_Connected, so there is no change - notification (if the connection has context-dependent capabilities, - it SHOULD advertise support for all classes of channel that it might - support during its lifetime). Before this state has been reached, - the value of this property is undefined.</p> - - <tp:rationale> - <p>This is not on an optional interface, because connection - managers can always offer some sort of clue about the channel - classes they expect to support (at worst, they can announce - support for everything for which they have code).</p> - </tp:rationale> - </tp:docstring> - </property> - </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Resources1.xml b/spec/Connection_Interface_Resources1.xml index ad5e4b0d..ccbb885e 100644 --- a/spec/Connection_Interface_Resources1.xml +++ b/spec/Connection_Interface_Resources1.xml @@ -19,6 +19,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:license> <interface name="im.telepathy.v1.Connection.Interface.Resources1" tp:causes-havoc="experimental"> + <!-- https://bugs.freedesktop.org/show_bug.cgi?id=30461 --> <tp:added version="0.21.1">(draft 1)</tp:added> <tp:requires interface="im.telepathy.v1.Connection"/> diff --git a/spec/Connection_Manager_Interface_Account_Storage1.xml b/spec/Connection_Manager_Interface_Account_Storage1.xml index 6cd97ee2..c50a255f 100644 --- a/spec/Connection_Manager_Interface_Account_Storage1.xml +++ b/spec/Connection_Manager_Interface_Account_Storage1.xml @@ -22,6 +22,7 @@ <interface name="im.telepathy.v1.ConnectionManager.Interface.AccountStorage1" tp:causes-havoc="experimental"> + <!-- https://bugs.freedesktop.org/show_bug.cgi?id=33485 --> <tp:added version="0.21.10">(draft 1)</tp:added> <tp:requires interface="im.telepathy.v1.ConnectionManager"/> diff --git a/spec/Protocol.xml b/spec/Protocol.xml index a7293936..8b525bde 100644 --- a/spec/Protocol.xml +++ b/spec/Protocol.xml @@ -153,8 +153,8 @@ allowed=im.telepathy.v1.Channel.TargetHandle;im.telepathy.v1.Channel.TargetID; <tp:dbus-ref namespace="im.telepathy.v1" >Connection</tp:dbus-ref> to this protocol (i.e. they will, or might, appear in the Connection's <tp:dbus-ref - namespace="im.telepathy.v1.Connection.Interface.Requests" - >RequestableChannelClasses</tp:dbus-ref> property).</p> + namespace="imt1.Connection">RequestableChannelClasses</tp:dbus-ref> + property).</p> <p>Whether a Connection will have all, some or none of these requestable channel classes depends on server capabilities; diff --git a/spec/Protocol_Interface_Addressing1.xml b/spec/Protocol_Interface_Addressing1.xml index f42770ff..939c13db 100644 --- a/spec/Protocol_Interface_Addressing1.xml +++ b/spec/Protocol_Interface_Addressing1.xml @@ -116,7 +116,7 @@ AddressableURISchemes=tel;sip; offline. When it is connected the addressable URI schemes should be retrieved from the <tp:dbus-ref - namespace="im.telepathy.v1.Connection.Interface">Requests.RequestableChannelClasses</tp:dbus-ref>'s + namespace="imt1.Connection">RequestableChannelClasses</tp:dbus-ref>'s TargetURIScheme fixed-property instead.</p> <p>Connection managers with a <code>.manager</code> file diff --git a/spec/all.xml b/spec/all.xml index 48515d1a..26fd31de 100644 --- a/spec/all.xml +++ b/spec/all.xml @@ -3,7 +3,7 @@ xmlns:xi="http://www.w3.org/2001/XInclude"> <tp:title>Telepathy D-Bus Interface Specification</tp:title> -<tp:version>0.99.6</tp:version> +<tp:version>0.99.7</tp:version> <tp:copyright>Copyright © 2005-2014 Collabora Limited</tp:copyright> <tp:copyright>Copyright © 2005-2011 Nokia Corporation</tp:copyright> @@ -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> @@ -260,11 +259,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </p> </tp:docstring> <xi:include href="Account_Manager.xml"/> - <xi:include href="Account_Manager_Interface_Hidden1.xml"/> <xi:include href="Account.xml"/> <xi:include href="Account_Interface_Addressing1.xml"/> <xi:include href="Account_Interface_Avatar1.xml"/> - <xi:include href="Account_Interface_Hidden1.xml"/> <xi:include href="Account_Interface_Storage1.xml"/> <xi:include href="Account_Interface_External_Password_Storage1.xml"/> </tp:section> diff --git a/spec/template.xml b/spec/template.xml index 1f829575..55eb7abf 100644 --- a/spec/template.xml +++ b/spec/template.xml @@ -22,6 +22,7 @@ <interface name="im.telepathy.v1.Foo1" tp:causes-havoc="experimental"> + <!-- https://bugs.freedesktop.org/show_bug.cgi?id=XXX --> <tp:added version="0.UNRELEASED">(draft 1)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> |