[Telepathy-commits] [telepathy-spec/master] Rename Client.ChannelHandler to Client.Handler
Simon McVittie
simon.mcvittie at collabora.co.uk
Fri Sep 26 08:21:46 PDT 2008
---
spec/Client.xml | 3 +-
spec/Client_Approver.xml | 2 +-
spec/Client_Channel_Handler.xml | 152 ---------------------------------------
spec/Client_Handler.xml | 152 +++++++++++++++++++++++++++++++++++++++
spec/Client_Observer.xml | 2 +-
spec/all.xml | 2 +-
6 files changed, 156 insertions(+), 157 deletions(-)
delete mode 100644 spec/Client_Channel_Handler.xml
create mode 100644 spec/Client_Handler.xml
diff --git a/spec/Client.xml b/spec/Client.xml
index 94de377..f660b18 100644
--- a/spec/Client.xml
+++ b/spec/Client.xml
@@ -100,11 +100,10 @@
tp:type="DBus_Interface[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A list of the extra interfaces provided by this client.
-<<<<<<< HEAD:spec/Client.xml
This SHOULD include at least one of
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer</tp:dbus-ref>,
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Approver</tp:dbus-ref> or
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.ChannelHandler</tp:dbus-ref>.</p>
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Handler</tp:dbus-ref>.</p>
<p>In the <code>.client</code> file, this is represented by key
"<code>Interfaces</code>" in the group named after this interface.
diff --git a/spec/Client_Approver.xml b/spec/Client_Approver.xml
index 5dcad8a..c767f18 100644
--- a/spec/Client_Approver.xml
+++ b/spec/Client_Approver.xml
@@ -103,7 +103,7 @@
<arg name="Handlers" type="as" direction="in">
<tp:docstring>
The well-known bus names of
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.ChannelHandler</tp:dbus-ref>s
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Handler</tp:dbus-ref>s
that could handle this channel.
The channel dispatcher SHOULD order them with the "most preferred"
handler first, in an implementation-dependent way.
diff --git a/spec/Client_Channel_Handler.xml b/spec/Client_Channel_Handler.xml
deleted file mode 100644
index 59ae452..0000000
--- a/spec/Client_Channel_Handler.xml
+++ /dev/null
@@ -1,152 +0,0 @@
-<?xml version="1.0" ?>
-<node name="/Client"
- xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
- <tp:copyright>Copyright (C) 2008 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.ChannelHandler.DRAFT"
- tp:causes-havoc="experimental">
- <tp:added version="0.17.UNRELEASED"/>
-
- <tp:requires interface="org.freedesktop.Telepathy.Client.DRAFT"/>
-
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Channel handlers are the eventual handler for a channel or a
- channel bundle; a typical channel handler is a user interface
- process handling channels of a particular type.</p>
-
- <p>When a new incoming channel is offered to
- <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref>s
- by the channel dispatcher, it also offers the Approvers a list of all
- the running or activatable ChannelHandlers whose
- <tp:member-ref>HandlerChannelFilter</tp:member-ref> property
- (possibly as cached in the .client file) indicates that they
- are able to handle the channel. The Approvers can choose one of
- those channel handlers to handle the channel.</p>
-
- <p>FIXME: interaction with outgoing channels?</p>
-
- <p>FIXME: interaction with automatically created channels?</p>
- </tp:docstring>
-
- <property name="HandlerChannelFilter" type="v" access="read">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>A specification of the channels that this channel handler can
- deal with. It will be offered to approvers as a potential
- channel handler for bundles that contain only suitable channels,
- or for suitable channels that must be handled separately.</p>
-
- <p>This property works in exactly the same way as the
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer.DRAFT.ObserverChannelFilter</tp:dbus-ref>
- property. In the .client file, it is represented in the
- same way as ObserverChannelFilter, but the group has the same
- name as this interface and the keys start with
- HandlerChannelFilter instead of ObserverChannelFilter.</p>
- </tp:docstring>
- </property>
-
- <!-- FIXME: add the HandleAdditionalChannels method, which must
- return instantly, and if successful, fast-tracks the channels past any
- approvers if appropriate - see ChannelDispatchOperation for details -->
-
- <method name="HandleChannels">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Called by the channel dispatcher when an Approver indicates that
- this client should handle these channels.</p>
-
- <p>The channel handler SHOULD NOT take input focus as a result of
- this method; the channel dispatcher SHOULD call HandleChannels
- followed by Present if the channels were requested by explicit
- user action.</p>
-
- <tp:rationale>
- <p>Channels created as a side-effect of a request for other channels
- shouldn't get their handler in the foreground. Suppose AbiWord
- requests an XMPP MUC (chatroom) Tube, and joining this tube
- requires the CM to join a corresponding Text channel which is then
- handled by some handler other than AbiWord. In this case the Text
- channel handler shouldn't take focus away from AbiWord.</p>
- </tp:rationale>
- </tp:docstring>
-
- <!-- FIXME: other dispatching-related info? -->
-
- <arg name="Connection" type="o" direction="in">
- <tp:docstring>
- The Connection with which the channels are 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:docstring>
- The channels and their immutable properties. Their well-known
- bus name is the same as that of the Connection.
- </tp:docstring>
- </arg>
-
- <tp:possible-errors>
- <!-- FIXME -->
- </tp:possible-errors>
- </method>
-
- <method name="Present">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Present any user interface for the given channels to the user, i.e.
- bring it to the foreground, give it focus, or use some other way to
- bring it to the user's attention.</p>
-
- <p>This method is called by the channel dispatcher after channels
- are requested. As a result, it SHOULD only ever be called in
- response to user action, which means that the client
- MAY take input focus as a result.</p>
-
- <!-- FIXME: incorporate a focus-stealing-prevention timestamp
- somehow -->
-
- <p>If any of the given channels are not being handled by this
- channel handler, they MUST be ignored. The channel dispatcher
- MAY include channels in the argument even if this channel
- handler is not actually handling them, but SHOULD NOT call this
- method unless the channel handler is actually handling at least
- one of the channels.</p>
- </tp:docstring>
-
- <arg name="Connection" type="o" direction="in">
- <tp:docstring>
- The Connection with which the channels are 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:docstring>
- The channels and their immutable properties. Their well-known
- bus name is the same as that of the Connection.
- </tp:docstring>
- </arg>
- </method>
-
- </interface>
-</node>
-<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml
new file mode 100644
index 0000000..d38a4d0
--- /dev/null
+++ b/spec/Client_Handler.xml
@@ -0,0 +1,152 @@
+<?xml version="1.0" ?>
+<node name="/Client_Handler"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright (C) 2008 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.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.17.UNRELEASED"/>
+
+ <tp:requires interface="org.freedesktop.Telepathy.Client.DRAFT"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Channel handlers are the eventual handler for a channel or a
+ channel bundle; a typical channel handler is a user interface
+ process handling channels of a particular type.</p>
+
+ <p>When a new incoming channel is offered to
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref>s
+ by the channel dispatcher, it also offers the Approvers a list of all
+ the running or activatable ChannelHandlers whose
+ <tp:member-ref>HandlerChannelFilter</tp:member-ref> property
+ (possibly as cached in the .client file) indicates that they
+ are able to handle the channel. The Approvers can choose one of
+ those channel handlers to handle the channel.</p>
+
+ <p>FIXME: interaction with outgoing channels?</p>
+
+ <p>FIXME: interaction with automatically created channels?</p>
+ </tp:docstring>
+
+ <property name="HandlerChannelFilter" type="v" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A specification of the channels that this channel handler can
+ deal with. It will be offered to approvers as a potential
+ channel handler for bundles that contain only suitable channels,
+ or for suitable channels that must be handled separately.</p>
+
+ <p>This property works in exactly the same way as the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer.DRAFT.ObserverChannelFilter</tp:dbus-ref>
+ property. In the .client file, it is represented in the
+ same way as ObserverChannelFilter, but the group has the same
+ name as this interface and the keys start with
+ HandlerChannelFilter instead of ObserverChannelFilter.</p>
+ </tp:docstring>
+ </property>
+
+ <!-- FIXME: add the HandleAdditionalChannels method, which must
+ return instantly, and if successful, fast-tracks the channels past any
+ approvers if appropriate - see ChannelDispatchOperation for details -->
+
+ <method name="HandleChannels">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Called by the channel dispatcher when an Approver indicates that
+ this client should handle these channels.</p>
+
+ <p>The channel handler SHOULD NOT take input focus as a result of
+ this method; the channel dispatcher SHOULD call HandleChannels
+ followed by Present if the channels were requested by explicit
+ user action.</p>
+
+ <tp:rationale>
+ <p>Channels created as a side-effect of a request for other channels
+ shouldn't get their handler in the foreground. Suppose AbiWord
+ requests an XMPP MUC (chatroom) Tube, and joining this tube
+ requires the CM to join a corresponding Text channel which is then
+ handled by some handler other than AbiWord. In this case the Text
+ channel handler shouldn't take focus away from AbiWord.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <!-- FIXME: other dispatching-related info? -->
+
+ <arg name="Connection" type="o" direction="in">
+ <tp:docstring>
+ The Connection with which the channels are 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:docstring>
+ The channels and their immutable properties. Their well-known
+ bus name is the same as that of the Connection.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <!-- FIXME -->
+ </tp:possible-errors>
+ </method>
+
+ <method name="Present">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Present any user interface for the given channels to the user, i.e.
+ bring it to the foreground, give it focus, or use some other way to
+ bring it to the user's attention.</p>
+
+ <p>This method is called by the channel dispatcher after channels
+ are requested. As a result, it SHOULD only ever be called in
+ response to user action, which means that the client
+ MAY take input focus as a result.</p>
+
+ <!-- FIXME: incorporate a focus-stealing-prevention timestamp
+ somehow -->
+
+ <p>If any of the given channels are not being handled by this
+ channel handler, they MUST be ignored. The channel dispatcher
+ MAY include channels in the argument even if this channel
+ handler is not actually handling them, but SHOULD NOT call this
+ method unless the channel handler is actually handling at least
+ one of the channels.</p>
+ </tp:docstring>
+
+ <arg name="Connection" type="o" direction="in">
+ <tp:docstring>
+ The Connection with which the channels are 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:docstring>
+ The channels and their immutable properties. Their well-known
+ bus name is the same as that of the Connection.
+ </tp:docstring>
+ </arg>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml
index 2a9be15..622ef96 100644
--- a/spec/Client_Observer.xml
+++ b/spec/Client_Observer.xml
@@ -127,7 +127,7 @@ ObserverChannelFilter 1 org.freedesktop.Telepathy.Channel.FUTURE.Requested b=tru
to avoid the following race: text channel logger (observer) gets
ObserveChannel, text channel handler gets
<tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Client.ChannelHandler.DRAFT">HandleChannels</tp:dbus-ref>
+ namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref>
channel handler starts up faster and acknowledges messages,
logger never sees those messages.</p>
</tp:rationale>
diff --git a/spec/all.xml b/spec/all.xml
index 10415c3..3be39ec 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -83,7 +83,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Client.xml"/>
<xi:include href="Client_Observer.xml"/>
<xi:include href="Client_Approver.xml"/>
-<xi:include href="Client_Channel_Handler.xml"/>
+<xi:include href="Client_Handler.xml"/>
<xi:include href="Channel_Handler.xml"/>
--
1.5.6.5
More information about the Telepathy-commits
mailing list