[telepathy-spec/master] Handler: move request notification to its own interface
Simon McVittie
simon.mcvittie at collabora.co.uk
Fri Apr 10 05:08:19 PDT 2009
---
spec/Channel_Dispatcher.xml | 5 +-
spec/Client_Handler.xml | 136 +---------------
...ient_Handler_Interface_Request_Notification.xml | 168 ++++++++++++++++++++
spec/all.xml | 1 +
4 files changed, 176 insertions(+), 134 deletions(-)
create mode 100644 spec/Client_Handler_Interface_Request_Notification.xml
diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml
index 8896e66..2780fe5 100644
--- a/spec/Channel_Dispatcher.xml
+++ b/spec/Channel_Dispatcher.xml
@@ -201,9 +201,10 @@
can recover state if it crashes and is restarted.</p>
</tp:rationale>
- <p>If this is a well-known bus name, the channel dispatcher SHOULD
+ <p>If this is a well-known bus name and the handler has the
+ RequestNotification interface, the channel dispatcher SHOULD
call <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">AddRequest</tp:dbus-ref>
+ namespace="org.freedesktop.Telepathy.Client.Handler.Interface.RequestNotification.DRAFT">AddRequest</tp:dbus-ref>
on that Handler after this method has returned.</p>
<tp:rationale>
diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml
index 8d96f30..333e744 100644
--- a/spec/Client_Handler.xml
+++ b/spec/Client_Handler.xml
@@ -183,9 +183,10 @@
<p>The requests satisfied by these channels.</p>
<tp:rationale>
- <p>This tells the handler that these channels match previous
- <tp:member-ref>AddRequest</tp:member-ref> calls that it may have
- received.</p>
+ <p>If the handler implements RequestNotification, this tells it
+ that these channels match previous <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler.Interface.RequestNotification.DRAFT">AddRequest</tp:dbus-ref>
+ calls that it may have received.</p>
<p>There can be more than one, if they were EnsureChannel
requests.</p>
@@ -205,135 +206,6 @@
<!-- FIXME: invent a way to say "any error is possible" in spec markup -->
</method>
- <method name="AddRequest" tp:name-for-bindings="Add_Request">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Called by the ChannelDispatcher to indicate that channels have been
- requested, and that if the request is successful, they will probably
- be handled by this Handler.</p>
-
- <tp:rationale>
- <p>This allows the UI to start preparing to handle the channels
- in advance (e.g. render a window with an "in progress" message),
- improving perceived responsiveness.</p>
-
- <p>The use of "probably" is because you can't necessarily tell from
- a channel request which handler will handle particular channels.
- A reasonable heuristic would be to match the request against the
- <tp:member-ref>HandlerChannelFilter</tp:member-ref>, and respect
- the preferred handler (if any).</p>
- </tp:rationale>
-
- <p>If the request succeeds and is given to the expected Handler,
- the Requests_Satisfied parameter to
- <tp:member-ref>HandleChannels</tp:member-ref> can be used to match
- the channel to a previous <tp:member-ref>AddRequest</tp:member-ref>
- call.</p>
-
- <tp:rationale>
- <p>This lets the UI direct the channels to the window that it
- already opened.</p>
- </tp:rationale>
-
- <p>If the request fails, the expected handler is notified by the
- channel dispatcher calling its
- <tp:member-ref>RemoveFailedRequest</tp:member-ref> method.</p>
-
- <tp:rationale>
- <p>This lets the UI close the window or display the error.</p>
- </tp:rationale>
-
- <p>If the request succeeds but the channel is not dispatched to the
- expected handler, the handler that was expected is notified by
- the channel dispatcher calling its
- <tp:member-ref>RemoveFailedRequest</tp:member-ref> method
- with the NotYours error.</p>
-
- <tp:rationale>
- <p>Expected handling is for the UI to close the window it
- previously opened.</p>
- </tp:rationale>
-
- <p>Handlers SHOULD NOT return an error from this method; errors
- returned from this method SHOULD NOT alter the channel dispatcher's
- behaviour.</p>
-
- <tp:rationale>
- <p>Calls to this method are merely a notification.</p>
- </tp:rationale>
- </tp:docstring>
-
- <arg name="Request" type="o" direction="in">
- <tp:docstring>
- The <tp:dbus-ref
- namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT</tp:dbus-ref>
- object, which MUST have been returned by <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.ChannelDispatcher.DRAFT">CreateChannel</tp:dbus-ref>
- or <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.ChannelDispatcher.DRAFT">EnsureChannel</tp:dbus-ref>
- before this method is called.
-
- <tp:rationale>
- See those methods for the rationale of this ordering.
- </tp:rationale>
- </tp:docstring>
- </arg>
-
- <arg name="Properties" type="a{sv}"
- tp:type="Qualified_Property_Value_Map" direction="in">
- <tp:docstring>
- <p>Some of the properties of the ChannelRequest. To avoid race
- conditions, this dictionary MUST NOT include properties whose
- values could subsequently change. It SHOULD include as many
- properties as possible, given that constraint.</p>
-
- <p>In particular, the properties <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.ChannelRequest.DRAFT">Requests</tp:dbus-ref>
- and <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.ChannelRequest.DRAFT">UserActionTime</tp:dbus-ref>
- MUST be included.</p>
- </tp:docstring>
- </arg>
- </method>
-
- <method name="RemoveFailedRequest"
- tp:name-for-bindings="Remove_Failed_Request">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Called by the ChannelDispatcher to indicate that a request
- previously passed to <tp:member-ref>AddRequest</tp:member-ref>
- has failed and should be disregarded.</p>
-
- <p>Handlers SHOULD NOT return an error from this method; errors
- returned from this method SHOULD NOT alter the channel dispatcher's
- behaviour.</p>
-
- <tp:rationale>
- <p>Calls to this method are merely a notification.</p>
- </tp:rationale>
- </tp:docstring>
-
- <arg name="Request" type="o" direction="in">
- <tp:docstring>
- The request that failed.
- </tp:docstring>
- </arg>
-
- <arg name="Error" type="s" tp:type="DBus_Error_Name" direction="in">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>The name of the D-Bus error with which the request failed.</p>
-
- <p>If this is <code>org.freedesktop.Telepathy.Error.NotYours</code>,
- this indicates that the request succeeded, but all the resulting
- channels were given to some other handler.</p>
- </tp:docstring>
- </arg>
-
- <arg name="Message" type="s" direction="in">
- <tp:docstring>
- Any message supplied with the D-Bus error.
- </tp:docstring>
- </arg>
- </method>
-
<property name="HandledChannels" tp:name-for-bindings="Handled_Channels"
type="ao" access="read">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
diff --git a/spec/Client_Handler_Interface_Request_Notification.xml b/spec/Client_Handler_Interface_Request_Notification.xml
new file mode 100644
index 0000000..6bef3d4
--- /dev/null
+++ b/spec/Client_Handler_Interface_Request_Notification.xml
@@ -0,0 +1,168 @@
+<?xml version="1.0" ?>
+<node name="/Client_Handler_Interface_Request_Notification"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2008-2009 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.Client.Handler.Interface.RequestNotification.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.17.UNRELEASED">(as a draft; functionality
+ moved from Handler)</tp:added>
+
+ <tp:requires interface="org.freedesktop.Telepathy.Client.DRAFT"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Client.Handler.DRAFT"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface can be implemented by a Handler to be notified about
+ requests for channels that it is likely to be asked to handle.</p>
+ </tp:docstring>
+
+ <method name="AddRequest" tp:name-for-bindings="Add_Request">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Called by the ChannelDispatcher to indicate that channels have been
+ requested, and that if the request is successful, they will probably
+ be handled by this Handler.</p>
+
+ <tp:rationale>
+ <p>This allows the UI to start preparing to handle the channels
+ in advance (e.g. render a window with an "in progress" message),
+ improving perceived responsiveness.</p>
+
+ <p>The use of "probably" is because you can't necessarily tell from
+ a channel request which handler will handle particular channels.
+ A reasonable heuristic would be to match the request against the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandlerChannelFilter</tp:dbus-ref>,
+ and respect the preferred handler (if any).</p>
+ </tp:rationale>
+
+ <p>If the request succeeds and is given to the expected Handler,
+ the Requests_Satisfied parameter to
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref>
+ can be used to match the channel to a previous AddRequest call.</p>
+
+ <tp:rationale>
+ <p>This lets the UI direct the channels to the window that it
+ already opened.</p>
+ </tp:rationale>
+
+ <p>If the request fails, the expected handler is notified by the
+ channel dispatcher calling its
+ <tp:member-ref>RemoveFailedRequest</tp:member-ref> method.</p>
+
+ <tp:rationale>
+ <p>This lets the UI close the window or display the error.</p>
+ </tp:rationale>
+
+ <p>If the request succeeds but the channel is not dispatched to the
+ expected handler, the handler that was expected is notified by
+ the channel dispatcher calling its
+ <tp:member-ref>RemoveFailedRequest</tp:member-ref> method
+ with the NotYours error.</p>
+
+ <tp:rationale>
+ <p>Expected handling is for the UI to close the window it
+ previously opened.</p>
+ </tp:rationale>
+
+ <p>Handlers SHOULD NOT return an error from this method; errors
+ returned from this method SHOULD NOT alter the channel dispatcher's
+ behaviour.</p>
+
+ <tp:rationale>
+ <p>Calls to this method are merely a notification.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Request" type="o" direction="in">
+ <tp:docstring>
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT</tp:dbus-ref>
+ object, which MUST have been returned by <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelDispatcher.DRAFT">CreateChannel</tp:dbus-ref>
+ or <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelDispatcher.DRAFT">EnsureChannel</tp:dbus-ref>
+ before this method is called.
+
+ <tp:rationale>
+ See those methods for the rationale of this ordering.
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map" direction="in">
+ <tp:docstring>
+ <p>Some of the properties of the ChannelRequest. To avoid race
+ conditions, this dictionary MUST NOT include properties whose
+ values could subsequently change. It SHOULD include as many
+ properties as possible, given that constraint.</p>
+
+ <p>In particular, the properties <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelRequest.DRAFT">Requests</tp:dbus-ref>
+ and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelRequest.DRAFT">UserActionTime</tp:dbus-ref>
+ MUST be included.</p>
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <method name="RemoveFailedRequest"
+ tp:name-for-bindings="Remove_Failed_Request">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Called by the ChannelDispatcher to indicate that a request
+ previously passed to <tp:member-ref>AddRequest</tp:member-ref>
+ has failed and should be disregarded.</p>
+
+ <p>Handlers SHOULD NOT return an error from this method; errors
+ returned from this method SHOULD NOT alter the channel dispatcher's
+ behaviour.</p>
+
+ <tp:rationale>
+ <p>Calls to this method are merely a notification.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Request" type="o" direction="in">
+ <tp:docstring>
+ The request that failed.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Error" type="s" tp:type="DBus_Error_Name" direction="in">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The name of the D-Bus error with which the request failed.</p>
+
+ <p>If this is <code>org.freedesktop.Telepathy.Error.NotYours</code>,
+ this indicates that the request succeeded, but all the resulting
+ channels were given to some other handler.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Message" type="s" direction="in">
+ <tp:docstring>
+ Any message supplied with the D-Bus error.
+ </tp:docstring>
+ </arg>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/all.xml b/spec/all.xml
index 4a307c6..8e8b706 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -157,6 +157,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Client_Observer.xml"/>
<xi:include href="Client_Approver.xml"/>
<xi:include href="Client_Handler.xml"/>
+ <xi:include href="Client_Handler_Interface_Request_Notification.xml"/>
<xi:include href="Channel_Handler.xml"/>
</tp:section>
--
1.5.6.5
More information about the telepathy-commits
mailing list