diff options
Diffstat (limited to 'xml')
-rw-r--r-- | xml/Channel_Dispatcher_Future.xml | 377 | ||||
-rw-r--r-- | xml/Channel_Request_Future.xml | 98 | ||||
-rw-r--r-- | xml/Makefile.am | 2 |
3 files changed, 477 insertions, 0 deletions
diff --git a/xml/Channel_Dispatcher_Future.xml b/xml/Channel_Dispatcher_Future.xml new file mode 100644 index 00000000..33ef9071 --- /dev/null +++ b/xml/Channel_Dispatcher_Future.xml @@ -0,0 +1,377 @@ +<?xml version="1.0" ?> +<node name="/Channel_Dispatcher_Future" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2008-2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2008-2009 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="org.freedesktop.Telepathy.ChannelDispatcher.FUTURE"> + <tp:added version="0.17.26">(as a stable interface)</tp:added> + + <tp:requires interface="org.freedesktop.Telepathy.ChannelDispatcher"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface contains functionality which we intend to incorporate + into the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref> + interface in future. It should be considered to + be conceptually part of the core ChannelDispatcher interface, but without + API or ABI guarantees.</p> + </tp:docstring> + + <method name="CreateChannelWithHints" + tp:name-for-bindings="Create_Channel_With_Hints"> + <tp:added version="0.19.UNRELEASED"> + Support for this method is indicated by the + <tp:member-ref>SupportsRequestHints</tp:member-ref> property. + Clients MUST recover from this method being unsupported by falling back + to <tp:dbus-ref + namespace="ofdT.ChannelDispatcher">CreateChannel</tp:dbus-ref>. + </tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Start a request to create a channel. This initially just creates a + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> + object, which can be used to continue the request and track its + success or failure.</p> + + <tp:rationale> + <p>The request can take a long time - in the worst case, the + channel dispatcher has to ask the account manager to put the + account online, the account manager has to ask the operating + system to obtain an Internet connection, and the operating + system has to ask the user whether to activate an Internet + connection using an on-demand mechanism like dialup.</p> + + <p>This means that using a single D-Bus method call and response + to represent the whole request will tend to lead to that call + timing out, which is not the behaviour we want.</p> + </tp:rationale> + + <p>If this method is called for an Account that is disabled, invalid + or otherwise unusable, no error is signalled until + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest.Proceed</tp:dbus-ref> + is called, at which point + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref> + is emitted with an appropriate error.</p> + + <tp:rationale> + <p>This means there's only one code path for errors, apart from + InvalidArgument for "that request makes no sense".</p> + + <p>It also means that the request will proceed if the account is + enabled after calling CreateChannel, but before calling + Proceed.</p> + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Account" type="o"> + <tp:docstring> + The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> + for which the new channel is to be created. + </tp:docstring> + </arg> + + <arg direction="in" name="Requested_Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary containing desirable properties. This has the same + semantics as the corresponding parameter to + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>. + </p> + + <p>Certain properties will not necessarily make sense in this + dictionary: for instance, + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + can only be given if the requester is able to interact with a + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> + to the desired account.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="User_Action_Time" type="x" + tp:type="User_Action_Timestamp"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The time at which user action occurred, or 0 if this channel + request is for some reason not involving user action. + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy.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="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="Preferred_Handler" type="s" + tp:type="DBus_Well_Known_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Either the well-known bus name (starting with + <code>org.freedesktop.Telepathy.Client.</code>) + of the preferred handler for this + channel, or an empty string to indicate that any handler would be + acceptable. The channel dispatcher SHOULD dispatch as many as + possible of the resulting channels (ideally, all of them) + to that handler—irrespective of whether that handler's <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref> + matches the channel—and SHOULD remember the preferred handler + so it can try to dispatch subsequent channels in the same bundle + to the same handler.</p> + + <tp:rationale> + <p>This must be the well-known bus name, not the unique name, + to ensure that all handlers do indeed have the Client API, + and the Client object on the handler can be located easily.</p> + + <p>This is partly so the channel dispatcher can call + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref> + on it, and partly so the channel dispatcher + can recover state if it crashes and is restarted.</p> + + <p>The filter should be disregarded for ease of use of this + interface: clients will usually use this argument to request + channels be sent to themself, and this should trump the filter + not matching. This also allows a client to become the handler + for a channel produced by one of its own requests, while not + being a candidate to handle other channels of that type.</p> + </tp:rationale> + + <p>If this is a well-known bus name and the handler has the + Requests interface, the channel dispatcher SHOULD + call <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Interface.Requests">AddRequest</tp:dbus-ref> + on that Handler after this method has returned.</p> + + <tp:rationale> + <p>This ordering allows a Handler which calls CreateChannel with + itself as the preferred handler to associate the call to + AddRequest with that call.</p> + </tp:rationale> + + <p>This is copied to the ChannelRequest that is returned, + as the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelRequest">PreferredHandler</tp:dbus-ref> + property.</p> + </tp:docstring> + + <tp:changed version="0.19.0"> + Previously, the spec didn't say that this should disregard the + handler's filter. This has been implemented since + telepathy-mission-control 5.3.2. + </tp:changed> + </arg> + + <arg direction="in" name="Hints" type="a{sv}"> + <tp:docstring> + <p>Additional information about the channel request, which will be + used as the value for the resulting request's <tp:dbus-ref + namespace="ofdT.ChannelRequest.FUTURE">Hints</tp:dbus-ref> + property, but will not otherwise be interpreted by the Channel + Dispatcher.</p> + + <tp:rationale> + <p>See the Hints property's documentation for rationale.</p> + </tp:rationale> + </tp:docstring> + </arg> + + <arg direction="out" name="Request" type="o"> + <tp:docstring> + A + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> + object. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The Preferred_Handler is syntactically invalid or does + not start with <code>org.freedesktop.Telepathy.Client.</code>, + the Account does not exist, or one of the Requested_Properties + is invalid + </tp:docstring> + </tp:error> + </tp:possible-errors> + + </method> + + <method name="EnsureChannelWithHints" + tp:name-for-bindings="Ensure_Channel_With_Hints"> + <tp:added version="0.19.UNRELEASED"> + Support for this method is indicated by the + <tp:member-ref>SupportsRequestHints</tp:member-ref> property. + Clients MUST recover from this method being unsupported by falling back + to <tp:dbus-ref + namespace="ofdT.ChannelDispatcher">EnsureChannel</tp:dbus-ref>. + </tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Start a request to ensure that a channel exists, creating it if + necessary. This initially just creates a <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> + object, which can be used to continue the request and track its + success or failure.</p> + + <p>If this method is called for an Account that is disabled, invalid + or otherwise unusable, no error is signalled until + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest.Proceed</tp:dbus-ref> + is called, at which point + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref> + is emitted with an appropriate error.</p> + + <tp:rationale> + <p>The rationale is as for <tp:dbus-ref + namespace='org.freedesktop.Telepathy.ChannelDispatcher'>CreateChannel</tp:dbus-ref>.</p> + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Account" type="o"> + <tp:docstring> + The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> + for which the new channel is to be created. + </tp:docstring> + </arg> + + <arg direction="in" name="Requested_Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary containing desirable properties. This has the same + semantics as the corresponding parameter to + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>. + </p> + + <p>Certain properties will not necessarily make sense in this + dictionary: for instance, + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + can only be given if the requester is able to interact with a + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> + to the desired account.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="User_Action_Time" type="x" + tp:type="User_Action_Timestamp"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The time at which user action occurred, or 0 if this channel + request is for some reason not involving user action.</p> + + <p>This parameter is used in the same way as the corresponding + parameter to + <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="Preferred_Handler" type="s" + tp:type="DBus_Well_Known_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Either the well-known bus name (starting with + <code>org.freedesktop.Telepathy.Client.</code>) + of the preferred handler for this + channel, or an empty string to indicate that any handler would be + acceptable. The behaviour and rationale are the same as for the + corresponding parameter to + <tp:member-ref>CreateChannelWithHints</tp:member-ref>, except + as noted here.</p> + + <p>If any new channels are created in response to this + request, the channel dispatcher SHOULD dispatch as many as + possible of the resulting channels (ideally, all of them) + to that handler, and SHOULD remember the preferred handler + so it can try to dispatch subsequent channels in the same bundle + to the same handler. If the requested channel already exists (that + is, <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref> + returns <code>Yours=False</code>) then the channel dispatcher + SHOULD re-dispatch the channel to its existing handler, and MUST + NOT dispatch it to this client (unless it is the existing handler); + the request is still deemed to have succeeded in this case.</p> + + <tp:rationale> + <p>An address book application, for example, might call <tp:dbus-ref + namespace='org.freedesktop.Telepathy.ChannelDispatcher'>EnsureChannel</tp:dbus-ref> + to ensure that a text channel with a particular contact is + displayed to the user; it does not care whether a new channel was + made. An IM client might call <tp:dbus-ref + namespace='org.freedesktop.Telepathy.ChannelDispatcher'>EnsureChannel</tp:dbus-ref> + in response to the user double-clicking an entry in the contact + list, with itself as the <code>Preferred_Handler</code>; if the + user already has a conversation with that contact in another + application, they would expect the existing window to be + presented, rather than their double-click leading to an error + message. So the request should succeed, even if its + <code>Preferred_Handler</code> is not used.</p> + </tp:rationale> + + </tp:docstring> + </arg> + + <arg direction="in" name="Hints" type="a{sv}"> + <tp:docstring> + Additional information about the channel request, which will be used + as the value for the resulting request's <tp:dbus-ref + namespace="ofdT.ChannelRequest.FUTURE">Hints</tp:dbus-ref> + property.</tp:docstring> + </arg> + + <arg direction="out" name="Request" type="o"> + <tp:docstring> + A + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> + object. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The Preferred_Handler is syntactically invalid or does + not start with <code>org.freedesktop.Telepathy.Client.</code>, + the Account does not exist, or one of the Requested_Properties + is invalid + </tp:docstring> + </tp:error> + </tp:possible-errors> + + </method> + + <property name="SupportsRequestHints" + tp:name-for-bindings="Supports_Request_Hints" + type="b" access="read"> + <tp:added version="0.19.UNRELEASED"/> + <tp:docstring> + If <code>True</code>, the channel dispatcher is new enough to support + <tp:member-ref>CreateChannelWithHints</tp:member-ref> and + <tp:member-ref>EnsureChannelWithHints</tp:member-ref>, in addition + to the older <tp:dbus-ref + namespace="ofdT.ChannelDispatcher">CreateChannel</tp:dbus-ref> + and <tp:dbus-ref + namespace="ofdT.ChannelDispatcher">EnsureChannel</tp:dbus-ref>. + methods. If <code>False</code> or missing, only the metadata-less + variants are supported. + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/xml/Channel_Request_Future.xml b/xml/Channel_Request_Future.xml new file mode 100644 index 00000000..5e3a7015 --- /dev/null +++ b/xml/Channel_Request_Future.xml @@ -0,0 +1,98 @@ +<?xml version="1.0" ?> +<node name="/Channel_Request_Future" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2008-2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2008-2009 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="org.freedesktop.Telepathy.ChannelRequest.FUTURE" + tp:causes-havoc="a staging area for future Channel functionality"> + + <tp:requires interface="org.freedesktop.Telepathy.ChannelRequest"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface contains functionality which we intend to incorporate + into the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> + interface in future. It should be considered to + be conceptually part of the core ChannelRequest interface, but without + API or ABI guarantees.</p> + </tp:docstring> + + <property name="Hints" tp:name-for-bindings="Hints" + type="a{sv}" access="read"> + <tp:added version="0.19.UNRELEASED"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary of metadata provided by the channel + requester, which the handler and other clients MAY choose to + interpret. Currently no standard keys are defined; clients MAY + choose to use platform-specific keys for their own purposes, but MUST + ignore unknown keys and MUST cope with expected keys being + missing.</p> + + <tp:rationale>This property might be used to pass a contact ID for a + telephone number shared between two contacts from the address book to + the call UI, so that if you try to call “Mum”, the call UI knows this + rather than having to guess or show “Calling Mum or Dad”. The format + of these contact IDs would be platform-specific, so we leave the + definition of the dictionary entry up to the platform in question. + But third-party channel requesters might not include the contact ID, + so the call UI has to be able to deal with it not being + there.</tp:rationale> + + <p>The channel dispatcher will not interpret these hints: they are + solely for communication between cooperating clients.</p> + + <tp:rationale> + <p>Any extra parameters that do affect the channel dispatcher should + be designed separately.</p> + </tp:rationale> + + <p>This property may be set when the channel request is created, and + can never change. Since it is immutable, it SHOULD be included in the + dictionary of properties passed to <tp:dbus-ref + namespace="ofdT.Client.Interface.Requests">AddRequest</tp:dbus-ref> + by the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>.</p> + </tp:docstring> + </property> + + <signal name="SucceededWithChannel" tp:name-for-bindings="Succeeded_With_Channel"> + <tp:added version="0.19.UNRELEASED"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Variant of the <tp:dbus-ref + namespace="ofdT.ChannelRequest">Succeeded</tp:dbus-ref> signal + allowing to get the channel which has been created.</p> + </tp:docstring> + + <arg name="Connection" type="o"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The Connection owning the channel.</p> + </tp:docstring> + </arg> + + <arg name="Channel" type="o"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The channel which has been created.</p> + </tp:docstring> + </arg> + + </signal> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/xml/Makefile.am b/xml/Makefile.am index 166e2bdc..43b548f1 100644 --- a/xml/Makefile.am +++ b/xml/Makefile.am @@ -17,8 +17,10 @@ SPECS = \ Account_Interface_Stats.xml \ Channel_Dispatch_Operation.xml \ Channel_Dispatcher.xml \ + Channel_Dispatcher_Future.xml \ Channel_Dispatcher_Interface_Operation_List.xml \ Channel_Request.xml \ + Channel_Request_Future.xml \ Client.xml \ Client_Approver.xml \ Client_Handler.xml \ |