[Telepathy-commits] [telepathy-spec/master] Add skeletal versions of the Observer, Approver and ChannelHandler APIs
Simon McVittie
simon.mcvittie at collabora.co.uk
Fri Sep 26 08:21:25 PDT 2008
20080603111917-53eee-2f12fa5d89df5eae1ad39452fa9ab410ee09afa1.gz
---
spec/Client_Approver.xml | 111 +++++++++++++++++++++++++++++++++++++++
spec/Client_Channel_Handler.xml | 52 ++++++++++++++++++
spec/Client_Observer.xml | 75 ++++++++++++++++++++++++++
spec/all.xml | 5 ++
4 files changed, 243 insertions(+), 0 deletions(-)
create mode 100644 spec/Client_Approver.xml
create mode 100644 spec/Client_Channel_Handler.xml
create mode 100644 spec/Client_Observer.xml
diff --git a/spec/Client_Approver.xml b/spec/Client_Approver.xml
new file mode 100644
index 0000000..afcd109
--- /dev/null
+++ b/spec/Client_Approver.xml
@@ -0,0 +1,111 @@
+<?xml version="1.0" ?>
+<node name="/Client_Approver"
+ 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.Approver.DRAFT"
+ tp:causes-havoc="experimental">
+
+ <tp:requires interface="org.freedesktop.Telepathy.Client.DRAFT"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Approvers notify the user that new channels have been created,
+ and also select which channel handler will be used for the channel,
+ either by asking the user or by choosing the most appropriate
+ channel handler (for instance, a GNOME or KDE approver could
+ give preference to a channel handler from the same desktop
+ environment on the basis that it is likely to integrate better
+ with other applications). It is possible to have an approver and
+ a channel handler in the same process.</p>
+
+ <p>All approvers are notified simultaneously. For instance, in a
+ desktop system, there might be one approver that displays a
+ notification-area icon, one that is part of a contact list
+ window and highlights contacts there, and one that is part
+ of a full-screen media player.</p>
+
+ <p>Any approver can approve the handling of a channel with a
+ particular channel handler. Approvers can also request that the
+ channel is rejected, or request that they are allowed to handle
+ the channel internally (for the case where an approver is also
+ a channel handler). The first approver to reply gets its decision
+ acted on; any other approvers that reply at the same time will
+ get a D-Bus error, indicating that the channel has already been
+ dealt with.</p>
+
+ <p>Approvers should usually prompt the user and ask for
+ confirmation, rather than dispatching the channel to a handler
+ straight away.</p>
+ </tp:docstring>
+
+ <method name="HandleDispatch">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Called by the channel dispatcher when a ChannelDispatch in which the
+ approver has registered an interest is created.</p>
+
+ <p>The channel dispatcher SHOULD call this method on all approvers
+ at the same time. If no approvers return from this method
+ successfully (for instance because no approvers are running),
+ the channel dispatcher SHOULD consider this to be an error, and
+ recover by dispatching the channel to a handler chosen in an
+ implementation-dependent way.</p>
+
+ <tp:rationale>
+ Processes that aren't approvers shouldn't be making connections
+ anyway - there should always be at least one approver running.
+ (FIXME: or should the CD attempt to service-activate an approver?)
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Handlers" type="as">
+ <tp:docstring>
+ The list of clients that could handle this channel. The channel
+ dispatcher SHOULD order them with the "most preferred" handler
+ first, in some implementation-dependent way.
+ </tp:docstring>
+ <!-- FIXME: what type is a client? An object path? A bus name? -->
+ </arg>
+
+ <arg name="Dispatch" type="o">
+ <tp:docstring>
+ The channel dispatch operation, which is an object inside the
+ channel dispatcher (and hence has the same bus name as the
+ channel dispatcher).
+ </tp:docstring>
+ </arg>
+
+ <arg name="Connection" type="o">
+ <tp:docstring>
+ The Telepathy connection. Its well-known bus name can be derived
+ from its object path by replacing all '/' with '.' and removing
+ the leading '.' that results.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Channels" type="a(oa{sv})">
+ <tp:docstring>
+ The channel bundle. The well-known bus name for all these channels
+ is the same as for the Connection.
+ </tp:docstring>
+ </arg>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Client_Channel_Handler.xml b/spec/Client_Channel_Handler.xml
new file mode 100644
index 0000000..044c981
--- /dev/null
+++ b/spec/Client_Channel_Handler.xml
@@ -0,0 +1,52 @@
+<?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: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>
+ </tp:docstring>
+
+ <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 this channel.</p>
+ </tp:docstring>
+
+ <arg name="Connection" type="o">
+ <tp:docstring>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Channels" type="a(oa{sv})">
+ <tp:docstring>
+ </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
new file mode 100644
index 0000000..9c8bd8f
--- /dev/null
+++ b/spec/Client_Observer.xml
@@ -0,0 +1,75 @@
+<?xml version="1.0" ?>
+<node name="/Client_Observer"
+ 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.Observer.DRAFT"
+ tp:causes-havoc="experimental">
+
+ <tp:requires interface="org.freedesktop.Telepathy.Client.DRAFT"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Observers monitor the creation of new channels. This
+ functionality can be used for things like message logging.
+ All observers are notified simultaneously, and they are not
+ given an opportunity to delay channel handling; they should not
+ alter the state of the channel.</p>
+ </tp:docstring>
+
+ <method name="ObserveChannel">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Called by the channel dispatcher when a channel in which the
+ observer has registered an interest is created.</p>
+
+ <p>For observers that are always running, this is somewhat
+ redundant, because the observer could monitor the NewChannel
+ signal. However, observers can also be registered to be
+ started on demand using service activation.</p>
+
+ <p>The channel dispatcher SHOULD call this method on all observers
+ at the same time, and SHOULD NOT wait for replies before proceeding.
+ It MAY accept replies asynchronously for logging purposes.</p>
+ </tp:docstring>
+
+ <arg name="Connection" type="o">
+ <tp:docstring>
+ The Telepathy connection. Its well-known bus name can be derived
+ from its object path by replacing all '/' with '.' and removing
+ the leading '.' that results.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Channel" type="o">
+ <tp:docstring>
+ The channel. Its well-known bus name is the same as that of the
+ Connection.
+ </tp:docstring>
+ </arg>
+ <!-- FIXME: or should observers be invoked per bundle? -->
+
+ <arg name="Properties" type="a{sv}">
+ <tp:docstring>
+ Immutable properties of the channel.
+ </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 99e4037..10415c3 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -80,6 +80,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Channel_Dispatch_Operation.xml"/>
<xi:include href="Channel_Request.xml"/>
+<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="Channel_Handler.xml"/>
<xi:include href="errors.xml"/>
--
1.5.6.5
More information about the Telepathy-commits
mailing list