[Telepathy-commits] [telepathy-mission-control/master] Add Client, Approver, Handler, Observer to libmcclient
Alberto Mardegan
alberto.mardegan at nokia.com
Mon Nov 17 00:05:12 PST 2008
---
libmcclient/Makefile.am | 12 ++
libmcclient/client.xml | 10 ++
xml/Client.xml | 123 ++++++++++++++++++++++
xml/Client_Approver.xml | 135 ++++++++++++++++++++++++
xml/Client_Handler.xml | 268 +++++++++++++++++++++++++++++++++++++++++++++++
xml/Client_Observer.xml | 230 ++++++++++++++++++++++++++++++++++++++++
xml/Makefile.am | 7 +-
xml/all.xml | 1 +
xml/generic-types.xml | 61 ++++++++++-
xml/nmc5.xml | 5 +
xml/telepathy-types.xml | 96 +++++++++++++++++
11 files changed, 945 insertions(+), 3 deletions(-)
create mode 100644 libmcclient/client.xml
create mode 100644 xml/Client.xml
create mode 100644 xml/Client_Approver.xml
create mode 100644 xml/Client_Handler.xml
create mode 100644 xml/Client_Observer.xml
create mode 100644 xml/telepathy-types.xml
diff --git a/libmcclient/Makefile.am b/libmcclient/Makefile.am
index 028841a..b9b76e1 100644
--- a/libmcclient/Makefile.am
+++ b/libmcclient/Makefile.am
@@ -46,6 +46,7 @@ nodist_geninclude_HEADERS = \
_gen/mc-quark.h \
_gen/cli-account.h \
_gen/cli-account-manager.h \
+ _gen/svc-client.h \
_gen/enums.h \
_gen/interfaces.h \
_gen/gtypes.h
@@ -54,6 +55,7 @@ nodist_libmcclient_la_SOURCES = \
_gen/mc-quark.c \
_gen/cli-account-body.h \
_gen/cli-account-manager-body.h \
+ _gen/svc-client.c \
_gen/gtypes-body.h \
_gen/interfaces-body.h \
_gen/register-dbus-glib-marshallers-body.h \
@@ -83,6 +85,7 @@ EXTRA_DIST = \
$(libmcclient_include_DATA) \
account.xml \
account-manager.xml \
+ client.xml \
mc-quark.list \
mc-signals-marshal.list
@@ -163,3 +166,12 @@ _gen/cli-%-body.h _gen/cli-%.h: _gen/%.xml \
--iface-quark-prefix=MC_IFACE_QUARK \
$< Mc_Cli _gen/cli-$*
+_gen/svc-%.c _gen/svc-%.h: _gen/%.xml \
+ $(tools_dir)/glib-ginterface-gen.py Makefile.am
+ $(PYTHON) $(tools_dir)/glib-ginterface-gen.py \
+ --filename=_gen/svc-$* \
+ --signal-marshal-prefix=_mc_ext \
+ --include='<telepathy-glib/dbus.h>' \
+ --include='"_gen/signals-marshal.h"' \
+ --not-implemented-func='tp_dbus_g_method_return_not_implemented' \
+ $< Mc_Svc_
diff --git a/libmcclient/client.xml b/libmcclient/client.xml
new file mode 100644
index 0000000..93bb711
--- /dev/null
+++ b/libmcclient/client.xml
@@ -0,0 +1,10 @@
+<tp:spec
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+
+<xi:include href="../xml/Client.xml"/>
+<xi:include href="../xml/Client_Approver.xml"/>
+<xi:include href="../xml/Client_Handler.xml"/>
+<xi:include href="../xml/Client_Observer.xml"/>
+
+</tp:spec>
diff --git a/xml/Client.xml b/xml/Client.xml
new file mode 100644
index 0000000..da3cfbe
--- /dev/null
+++ b/xml/Client.xml
@@ -0,0 +1,123 @@
+<?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.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.17.UNRELEASED"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Telepathy clients use connection managers, the channel dispatcher
+ and optionally the account manager to provide useful
+ functionality.</p>
+
+ <p>User interface processes are the obvious example of Telepathy
+ clients, but they can provide other functionality, such as
+ address-book synchronization.</p>
+
+ <p>Every running or activatable process with a well-known
+ name of the form org.freedesktop.Telepathy.Client.<em>clientname</em>
+ should be probed by the channel dispatcher to discover its
+ capabilities. Each client is either an <em>observer</em>, an
+ <em>approver</em>, a <em>channel handler</em>, or some combination
+ of these.</p>
+
+ <tp:rationale>
+ <p>Activatable services (those with a D-Bus <code>.service</code>
+ file) must be supported so that we can run clients
+ in response to channel creation.</p>
+
+ <p>Non-activatable services (those that do not register a D-Bus
+ <code>.service</code> file for their well-known name, but do
+ request it at runtime) must be supported so that we can have
+ programs that process channels, but only if they are already
+ running - for instance, a full-screen media centre
+ application might do this.</p>
+ </tp:rationale>
+
+ <p>The client name, <em>clientname</em>, MUST be a non-empty string of
+ ASCII digits, letters, dots and/or underscores, starting with a
+ letter, and without sets of two consecutive dots or a dot
+ followed by a digit. For non-activatable services, it MAY contain a
+ part that is generated per instance at runtime.</p>
+
+ <tp:rationale>
+ <p>If each of a client Foo's instances should be able to manipulate
+ channels separately, the instance with unique name
+ <code>:1.25</code> might request a well-known name like
+ <code>org.freedesktop.Telepathy.Client.Foo._1._25</code>.</p>
+
+ <p>(Note that well-known bus-name components may not start with a
+ digit, so o.f.T.Client.Foo.1.25 would not be acceptable.)</p>
+ </tp:rationale>
+
+ <p>Each Client MUST export an object whose object path may be
+ determined by replacing '.' with '/' in the well-known name and
+ prepending '/'. This object represents its API as a Telepathy
+ client; the channel dispatcher will call its methods and read
+ its properties when appropriate.</p>
+
+ <p>As an optimization, activatable clients SHOULD install a file
+ <code><a href="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">$XDG_DATA_DIRS</a>/telepathy/clients/<em>clientname</em>.client</code>
+ containing a cached version of its immutable properties,
+ so that for most clients, the channel dispatcher can
+ just read a file to discover capabilities, instead of
+ having to service-activate the client immediately in order to fetch
+ its read-only properties. However, the D-Bus API is canonical, and
+ the channel dispatcher MUST support clients without such a file.</p>
+
+ <p>Non-activatable clients MAY install a <code>.client</code> file,
+ but there's not much point in them doing so.</p>
+
+ <p>The .client files MUST contain UTF-8 text with the same syntax
+ as
+ <a href="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop
+ Entry files</a> (although the allowed groups, keys and values differ).
+ Every <code>.client</code> file MUST contain a group whose name is
+ the name of this interface.</p>
+
+ <p>The groups, keys and values in the <code>.client</code> file are
+ defined by individual interfaces. Each interface that can usefully
+ cache information in the <code>.client</code> file SHOULD correspond
+ to a group with the same name.</p>
+ </tp:docstring>
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ type="as" access="read" tp:type="DBus_Interface[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of the extra interfaces provided by this client.
+ 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.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.
+ The value of the key is a list of interface names each followed by
+ a semicolon (so it always ends with a semicolon unless it is empty),
+ i.e. a key of type "strings" as described in the Desktop Entry
+ specification.</p>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/xml/Client_Approver.xml b/xml/Client_Approver.xml
new file mode 100644
index 0000000..c912b12
--- /dev/null
+++ b/xml/Client_Approver.xml
@@ -0,0 +1,135 @@
+<?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:added version="0.17.UNRELEASED"/>
+
+ <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 allow the user to accept or reject those channels.</p>
+
+ <p>They can also select which channel handler will be used for the
+ channel, for instance by offering the user a list of possible
+ handlers rather than just an accept/reject choice.</p>
+
+ <p>However, the Channel Dispatcher must be able to prioritize
+ possible handlers on its own using some reasonable heuristic,
+ probably based on user configuration.</p>
+
+ <p>It is possible (and useful) to have an approver and
+ a channel handler in the same process; this is particularly useful
+ if a channel handler wants to claim responsibility for particular
+ channels itself.</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. 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>
+
+ <property name="ApproverChannelFilter"
+ tp:name-for-bindings="Approver_Channel_Filter"
+ 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 approver is
+ interested. The <tp:member-ref>AddDispatchOperation</tp:member-ref>
+ method should be called by the channel dispatcher whenever the
+ channels in a channel dispatch operation
+ match this description.</p>
+
+ <p>(FIXME: what happens if some but not all of the channels
+ match this?)</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
+ ApproverChannelFilter instead of ObserverChannelFilter.</p>
+ </tp:docstring>
+ </property>
+
+ <method name="AddDispatchOperation"
+ tp:name-for-bindings="Add_Dispatch_Operation">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Called by the channel dispatcher when a ChannelDispatchOperation
+ 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 (including situations where there are no matching
+ approvers at all), the channel dispatcher SHOULD consider this
+ to be an error, and recover by dispatching the channel to the
+ most preferred handler.</p>
+
+ <tp:rationale>
+ Processes that aren't approvers shouldn't be making connections
+ anyway - there should always be at least one approver running.
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="DispatchOperation" type="o" direction="in">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref>
+ to be processed.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map" direction="in">
+ <tp:docstring>
+ Properties of the channel dispatch operation. This MUST NOT include
+ properties that could change, SHOULD include as many properties as
+ possible given that constraint, and MUST include at least the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Account</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Connection</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Channels</tp:dbus-ref>
+ and
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">PossibleHandlers</tp:dbus-ref>
+ properties.
+ </tp:docstring>
+ </arg>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/xml/Client_Handler.xml b/xml/Client_Handler.xml
new file mode 100644
index 0000000..4e815d0
--- /dev/null
+++ b/xml/Client_Handler.xml
@@ -0,0 +1,268 @@
+<?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 (one with
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.FUTURE">Requested</tp:dbus-ref>
+ = TRUE) 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>When a new outgoing channel (one with
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.FUTURE">Requested</tp:dbus-ref>
+ = FALSE) appears, the channel dispatcher passes it to an appropriate
+ channel handler automatically.
+ </p>
+
+ </tp:docstring>
+
+ <property name="HandlerChannelFilter"
+ tp:name-for-bindings="Handler_Channel_Filter"
+ type="aa{sv}" access="read" tp:type="Channel_Class[]">
+ <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>
+
+ <property name="BypassApproval" tp:name-for-bindings="Bypass_Approval"
+ type="b" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, channels destined for this handler are automatically
+ handled, without invoking approvers.</p>
+
+ <tp:rationale>
+ <p>The intended usage is to allow a client handling one channel to
+ pick up closely related channels. Suppose a client capable of
+ handling both Text and StreamedMedia,
+ <code>org.freedesktop.Telepathy.Client.Empathy</code>, is
+ handling a StreamedMedia channel. That client can take a second
+ well-known bus name, say
+ <code>org.freedesktop.Telepathy.Client.Empathy._1._42.Bundle1</code>,
+ and configure an object at
+ <code>/org/freedesktop/Telepathy/Client/Empathy/_1/_42/Bundle1</code>
+ with BypassApproval = TRUE,
+ whose <tp:member-ref>HandlerChannelFilter</tp:member-ref>
+ matches closely related Text channels by their Bundle property.
+ (This is use-case dis5)</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <method name="HandleChannels" tp:name-for-bindings="Handle_Channels">
+ <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>
+
+ <tp:rationale>
+ <p>Clients are expected to know what channels they're already handling,
+ and which channel object path corresponds to which window or tab.
+ This can easily be done using a hash table keyed by channels' object
+ paths.</p>
+ </tp:rationale>
+
+ <p>This method can raise any D-Bus error. If it does, or if the
+ handler loses its bus name before all the channels have closed, the
+ handler is assumed to have failed or crashed, and the channel
+ dispatcher MUST recover in an implementation-specific way.</p>
+
+ <p>It is RECOMMENDED that the channel dispatcher attempts to
+ close the channels using
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>,
+ but resorts to calling
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Interface.Destroyable.DRAFT.Destroy</tp:dbus-ref>
+ (if available) or ignoring the channel (if not) if the same handler
+ repeatedly fails to handle channels.</p>
+ </tp:docstring>
+
+ <arg name="Account" type="o" direction="in">
+ <tp:docstring>
+ The
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
+ with which the channels are associated. The
+ well-known bus name to use is that of the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>.
+ </tp:docstring>
+ </arg>
+
+ <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>
+
+ <arg name="Requests_Satisfied" type="ao" direction="in">
+ <tp:docstring>
+ The requests satisfied by these channels.
+
+ <tp:rationale>
+ There can be more than one, if they were EnsureChannel
+ requests.
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <arg name="User_Action_Time" type="t" direction="in">
+ <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.
+ </tp:docstring>
+ </arg>
+
+ <!-- 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 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>
+ </tp:rationale>
+
+ <p>(FIXME: how do we know the returned channels will be handled by
+ this handler? Do we just assume that they'll match the
+ HandlerChannelFilter iff the request does?)</p>
+ </tp:docstring>
+
+ <arg name="Request" type="o" direction="in">
+ <tp:docstring>
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
+ object.
+ </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 Requests and UserActionTimestamp
+ 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>
+ </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.Errors.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">
+ <p>A list of the channels that this Handler is currently handling.
+ </p>
+
+ <p>There is no change notification.</p>
+
+ <tp:rationale>
+ <p>This property exists for state recovery - it makes it possible
+ for channel handling to survive a ChannelDispatcher crash.</p>
+
+ <p>If the channel dispatcher is automatically replaced, the
+ replacement can discover all Handlers by looking for the Client
+ well-known bus names, and discover which channels they are
+ currently handling. Once this has been done, all unhandled
+ channels can be re-dispatched, and the only issue visible to
+ the user is that unhandled channels that they have already
+ approved might be sent back to Approvers.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/xml/Client_Observer.xml b/xml/Client_Observer.xml
new file mode 100644
index 0000000..eccbefd
--- /dev/null
+++ b/xml/Client_Observer.xml
@@ -0,0 +1,230 @@
+<?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:added version="0.17.UNRELEASED"/>
+
+ <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.</p>
+
+ <p>Observers SHOULD NOT modify the state of a channel except
+ via user interaction.</p>
+
+ <tp:rationale>
+ <p>We want Observer UIs for file transfer channels (a progress
+ bar for the transfer) to be able to have a Cancel button.</p>
+ </tp:rationale>
+
+ <p>Observers MUST NOT carry out actions that exactly one process
+ must take responsibility for (e.g. acknowledging Text
+ messages, or carrying out the actual transfer in a file transfer
+ channel).</p>
+
+ <tp:rationale>
+ <p>Since arbitrarily many observers can be activated for
+ each channel, it would not make sense for observers to do things
+ that can only be done by one process (acknowledging
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>
+ messages, carrying out streaming for
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ channels, doing the actual data transfer for file transfers,
+ setting up the out-of-band connection for Tubes). The
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>
+ is responsible for such tasks.</p>
+
+ <p>Handlers MAY, of course, delegate responsibility for these
+ tasks to other processes (including those run as observers),
+ but this MUST be done explicitly via a request from the Handler
+ to the Observer.</p>
+ </tp:rationale>
+
+ <p>Whenever new channels are 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 the channel.</p>
+
+ <p>Observers are activated for all channels in which they have
+ registered an interest - incoming, outgoing or automatically created -
+ although of course the ObserverChannelFilter property can be set
+ to filter on the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.FUTURE.Requested</tp:dbus-ref>
+ property.</p>
+ </tp:docstring>
+
+ <property name="ObserverChannelFilter"
+ tp:name-for-bindings="Observer_Channel_Filter"
+ 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 NewChannels signal match this description.</p>
+
+ <p>(FIXME: open issue: do we want this, and the corresponding
+ Approver and Handler properties, to be able to change at
+ runtime?)</p>
+
+ <p>Only certain D-Bus types have useful semantics for matching like this,
+ so only certain types are allowed:</p>
+
+ <dl>
+ <dt>Integers of all sizes, including byte (y, n, q, i, u, x, t)</dt>
+ <dd>Matched by numeric value, regardless of type (e.g. 42 as a
+ 16-bit signed integer 'n' is considered equal to 42 as a 32-bit
+ unsigned integer 'u')</dd>
+
+ <dt>Booleans (b)</dt>
+ <dd>Matched by equality in the obvious way; not considered equal to any
+ other type</dd>
+
+ <dt>Strings (s)</dt>
+ <dd>Matched by equality in the obvious way; not considered equal to any
+ other type</dd>
+
+ <dt>Object paths (o)</dt>
+ <dd>Matched by equality in the obvious way; not considered equal to any
+ other type</dd>
+
+ </dl>
+
+ <p>This property never changes while the observer process is
+ running. For activatable processes, the filter can change due to an
+ upgrade - the channel dispatcher SHOULD observe changes to .client files
+ using a mechanism like inotify.</p>
+
+ <p>For observers that have a .client file, the channel dispatcher
+ may discover this property from keys of the form
+ <code><em>propertyname</em>/<em>type</em></code>,
+ in groups in the .client file whose name is the name of this
+ interface followed by <code>.ObserverChannelFilter</code>,
+ a space and an ASCII decimal number starting from 0.</p>
+
+ <p>Integers in the .client file are encoded in ASCII decimal, booleans
+ are encoded as "true" or "false", and strings are encoded in the usual
+ way for desktop files (including the C-style backslash escapes
+ documented in the Desktop Entry specification).</p>
+
+ <p>For instance, a .client file for an observer that is only interested
+ in Text channels, with CONTACT or ROOM handles, that were requested by
+ a local client:</p>
+
+<pre>
+[org.freedesktop.Telepathy.Client.DRAFT]
+Interfaces=org.freedesktop.Telepathy.Client.Observer.DRAFT;
+
+[org.freedesktop.Telepathy.Client.Observer.DRAFT.ObserverChannelFilter 0]
+org.freedesktop.Telepathy.Channel.Type s=org.freedesktop.Telepathy.Channel.Type.Text
+org.freedesktop.Telepathy.Channel.TargetHandleType u=1
+org.freedesktop.Telepathy.Channel.FUTURE.Requested b=true
+
+[org.freedesktop.Telepathy.Client.Observer.DRAFT.ObserverChannelFilter 1]
+org.freedesktop.Telepathy.Channel.Type s=org.freedesktop.Telepathy.Channel.Type.Text
+org.freedesktop.Telepathy.Channel.TargetHandleType u=2
+org.freedesktop.Telepathy.Channel.FUTURE.Requested b=true
+</pre>
+
+ </tp:docstring>
+ </property>
+
+ <method name="ObserveChannels" tp:name-for-bindings="Observe_Channels">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Called by the channel dispatcher when channels in which the
+ observer has registered an interest are created.</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>
+
+ <tp:rationale>
+ <p>The channel dispatcher must wait for observers to start up,
+ to avoid the following race: text channel logger (observer) gets
+ ObserveChannel, text channel handler gets
+ <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>
+ </tp:docstring>
+
+ <arg name="Account" type="o" direction="in">
+ <tp:docstring>
+ The
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
+ with which the channels are associated. The
+ well-known bus name to use is that of the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Connection" type="o" direction="in">
+ <tp:docstring>
+ The
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
+ 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})" tp:type="Channel_Details[]"
+ direction="in">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s
+ and their properties. Their well-known bus names are all the same
+ as that of the Connection.</p>
+
+ <tp:rationale>
+ <p>The ChannelDispatchOperation is <em>not</em> supplied: for
+ requests, there isn't one, and for incoming channels, it hasn't
+ been created yet.</p>
+ </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. No keys are
+ currently defined.</p>
+
+ <p>If keys are defined for this dictionary, all will be optional;
+ observers MAY safely ignore any entry in this dictionary.</p>
+ </tp:docstring>
+ </arg>
+
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/xml/Makefile.am b/xml/Makefile.am
index a32207f..4518f68 100644
--- a/xml/Makefile.am
+++ b/xml/Makefile.am
@@ -11,7 +11,11 @@ SPECS = MissionControl.xml \
Account.xml \
Account_Interface_Avatar.xml \
Account_Interface_Compat.xml \
- Account_Interface_Conditions.xml
+ Account_Interface_Conditions.xml \
+ Client.xml \
+ Client_Approver.xml \
+ Client_Handler.xml \
+ Client_Observer.xml
SPECS_GEN = ${SPECS:.xml=-gen.xml}
@@ -34,4 +38,5 @@ EXTRA_DIST = \
nmc4.xml \
nmc5.xml \
generic-types.xml \
+ telepathy-types.xml \
$(SPECS)
diff --git a/xml/all.xml b/xml/all.xml
index dbc0bdd..f39f616 100644
--- a/xml/all.xml
+++ b/xml/all.xml
@@ -21,5 +21,6 @@
</tp:generic-types>
<xi:include href="generic-types.xml"/>
+<xi:include href="telepathy-types.xml"/>
</tp:spec>
diff --git a/xml/generic-types.xml b/xml/generic-types.xml
index a96237d..9d8501d 100644
--- a/xml/generic-types.xml
+++ b/xml/generic-types.xml
@@ -2,7 +2,19 @@
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:simple-type name="Unix_Timestamp" type="u">
- <tp:docstring>An unsigned 32-bit integer representing time since 1970</tp:docstring>
+ <tp:docstring>An unsigned 32-bit integer representing time as the number
+ of seconds elapsed since the Unix epoch
+ (1970-01-01T00:00:00Z)</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="Unix_Timestamp64" type="t">
+ <tp:docstring>An unsigned 64-bit integer representing time as the number
+ of seconds elapsed since the Unix epoch
+ (1970-01-01T00:00:00Z)</tp:docstring>
+
+ <tp:rationale>The Text interface is the only user of Unix_Timestamp so
+ far, and we'd like to be Y2038 compatible in future
+ interfaces.</tp:rationale>
</tp:simple-type>
<tp:simple-type name="DBus_Bus_Name" type="s">
@@ -11,13 +23,28 @@
like ":1.123"</tp:docstring>
</tp:simple-type>
+ <tp:simple-type name="DBus_Well_Known_Name" type="s">
+ <tp:docstring>A string representing a D-Bus well-known
+ name like "org.freedesktop.Telepathy.MissionControl".</tp:docstring>
+ </tp:simple-type>
+
<tp:simple-type name="DBus_Unique_Name" type="s">
<tp:docstring>A string representing a D-Bus unique name, such as
":1.123"</tp:docstring>
</tp:simple-type>
<tp:simple-type name="DBus_Interface" type="s">
- <tp:docstring>A string representing a D-Bus interface</tp:docstring>
+ <tp:docstring>An ASCII string representing a D-Bus interface - two or more
+ elements separated by dots, where each element is a non-empty
+ string of ASCII letters, digits and underscores, not starting with
+ a digit. The maximum total length is 255 characters. For example,
+ "org.freedesktop.DBus.Peer".</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="DBus_Error_Name" type="s">
+ <tp:docstring>An ASCII string representing a D-Bus error. This is
+ syntactically the same as a <tp:type>DBus_Interface</tp:type>, but the
+ meaning is different.</tp:docstring>
</tp:simple-type>
<tp:simple-type name="DBus_Signature" type="s">
@@ -26,6 +53,36 @@
with dbus-glib)</tp:docstring>
</tp:simple-type>
+ <tp:simple-type name="DBus_Member" type="s">
+ <tp:docstring>An ASCII string representing a D-Bus method, signal
+ or property name - a non-empty string of ASCII letters, digits and
+ underscores, not starting with a digit, with a maximum length of 255
+ characters. For example, "Ping".</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="DBus_Qualified_Member" type="s">
+ <tp:docstring>A string representing the full name of a D-Bus method,
+ signal or property, consisting of a DBus_Interface, followed by
+ a dot, followed by a DBus_Member. For example,
+ "org.freedesktop.DBus.Peer.Ping".</tp:docstring>
+ </tp:simple-type>
+
+ <tp:mapping name="Qualified_Property_Value_Map"
+ array-name="Qualified_Property_Value_Map_List">
+ <tp:docstring>A mapping from strings representing D-Bus
+ properties (by their namespaced names) to their values.</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:mapping name="String_Variant_Map">
<tp:docstring>A mapping from strings to variants representing extra
key-value pairs.</tp:docstring>
diff --git a/xml/nmc5.xml b/xml/nmc5.xml
index c0aab5c..ab23c6c 100644
--- a/xml/nmc5.xml
+++ b/xml/nmc5.xml
@@ -12,4 +12,9 @@
<xi:include href="Account_Manager_Interface_Query.xml"/>
<xi:include href="Account_Manager_Interface_Creation.xml"/>
+<xi:include href="Client.xml"/>
+<xi:include href="Client_Approver.xml"/>
+<xi:include href="Client_Handler.xml"/>
+<xi:include href="Client_Observer.xml"/>
+
</tp:spec>
diff --git a/xml/telepathy-types.xml b/xml/telepathy-types.xml
new file mode 100644
index 0000000..8225aa0
--- /dev/null
+++ b/xml/telepathy-types.xml
@@ -0,0 +1,96 @@
+<tp:telepathy-types
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:mapping name="Channel_Class" array-name="Channel_Class_List">
+ <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>org.freedesktop.Telepathy.Channel.ChannelType</tp:dbus-ref>
+ and
+ <tp:dbus-ref>org.freedesktop.Telepathy.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="Channel_Details" array-name="Channel_Details_List">
+ <tp:added version="0.17.11">(as stable API)</tp:added>
+
+ <tp:docstring>
+ Enough details of a channel that clients can work out how to dispatch
+ or handle it.
+ </tp:docstring>
+
+ <tp:member name="Channel" type="o">
+ <tp:docstring>
+ The object path of the channel.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Properties of the channel.</p>
+
+ <p>Connection managers MUST NOT include properties in this mapping
+ if their values can change. Clients MUST ignore properties
+ that appear in this mapping if their values can change.</p>
+
+ <tp:rationale>
+ <p>If properties that could change were included, the following
+ race condition would be likely to exist in some cases:</p>
+
+ <ul>
+ <li>NewChannels 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>
+ <li>Client connects to PChanged signal</li>
+ <li>Client should call Get("P") or GetAll here, to avoid the
+ race, but client's author has forgotten to do so</li>
+ <li>Proxy object thinks P == V1, but actually P == V2</li>
+ </ul>
+
+ <p>We've taken the opportunity to make the API encourage the
+ client author to get it right. Where possible, we intend that
+ properties whose value will be used in channel dispatching
+ or other "early" processing will be defined so that they are
+ immutable (can never change).</p>
+ </tp:rationale>
+
+ <p>Each dictionary MUST contain the keys
+ <tp:dbus-ref>org.freedesktop.Telepathy.Channel.ChannelType</tp:dbus-ref>,
+ <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandleType</tp:dbus-ref>,
+ <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandle</tp:dbus-ref>
+ and
+ <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetID</tp:dbus-ref>.
+ </p>
+ <!-- FIXME: maybe also Requested, InitiatorHandle,
+ InitiatorID once they leave the FUTURE pseudo-interface -->
+
+ <tp:rationale>
+ <p>We expect these to be crucial to the channel-dispatching
+ process.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+</tp:telepathy-types>
--
1.5.6.5
More information about the Telepathy-commits
mailing list