[Telepathy-commits] [telepathy-glib/master] Update spec to 0.17.12 (no code changes) and prepare 0.7.16 release
Simon McVittie
simon.mcvittie at collabora.co.uk
Fri Sep 26 10:50:55 PDT 2008
---
NEWS | 28 ++-
configure.ac | 8 +-
spec/Channel_Dispatch_Operation.xml | 331 ++++++++++++++++++++
spec/Channel_Dispatcher.xml | 222 +++++++++++++
...Channel_Dispatcher_Interface_Operation_List.xml | 138 ++++++++
spec/Channel_Interface_Call_State.xml | 8 +
spec/Channel_Interface_Destroyable.xml | 79 +++++
spec/Channel_Request.xml | 178 +++++++++++
spec/Client.xml | 123 ++++++++
spec/Client_Approver.xml | 135 ++++++++
spec/Client_Handler.xml | 268 ++++++++++++++++
spec/Client_Observer.xml | 230 ++++++++++++++
spec/Makefile.am | 9 +
spec/all.xml | 34 ++-
spec/errors.xml | 21 ++-
spec/generic-types.xml | 3 +-
telepathy-glib/Makefile.am | 3 +-
telepathy-glib/channel-manager.c | 6 +-
telepathy-glib/connection.c | 2 +-
telepathy-glib/versions/0.7.16.abi | 9 +
20 files changed, 1810 insertions(+), 25 deletions(-)
create mode 100644 spec/Channel_Dispatch_Operation.xml
create mode 100644 spec/Channel_Dispatcher.xml
create mode 100644 spec/Channel_Dispatcher_Interface_Operation_List.xml
create mode 100644 spec/Channel_Interface_Destroyable.xml
create mode 100644 spec/Channel_Request.xml
create mode 100644 spec/Client.xml
create mode 100644 spec/Client_Approver.xml
create mode 100644 spec/Client_Handler.xml
create mode 100644 spec/Client_Observer.xml
create mode 100644 telepathy-glib/versions/0.7.16.abi
diff --git a/NEWS b/NEWS
index 41494b7..9bd49e6 100644
--- a/NEWS
+++ b/NEWS
@@ -1,15 +1,37 @@
-telepathy-glib 0.7.16 (UNRELEASED)
+telepathy-glib 0.7.16 (2008-09-26)
==================================
+The "could you say that again? I was looking at that bee" release.
+
Dependencies:
-Deprecations:
+* To use --enable-gtk-doc you must now have at least gtkdoc 1.10
Enhancements:
+* Updated to spec 0.17.12, mainly featuring EnsureChannel
+
+* We now support EnsureChannel on the Requests interface - to implement this,
+ put a suitable function pointer in TpChannelManagerIface::ensure_channel
+
+* Channel factories' RequestChannel implementations no longer need to
+ validate handles - TpBaseConnection now does this automatically
+
+* Added a function to compare presence types in order of "availability"
+
Fixes:
-Release notes for projects using code generation:
+* The gtkdoc now documents GInterfaces' signals and properties (fd.o #16995,
+ fd.o #17308)
+
+* TpBaseConnection::self_handle is unreffed and cleared slightly later,
+ for the benefit of channel managers that want to use it in their
+ status-changed(Disconnected) callback
+
+* Fixed a compiler warning on platforms with daemon(3) in their libc
+
+* TpChannelManager can no longer be crashed by asking for unsupported
+ handle types
telepathy-glib 0.7.15 (2008-09-18)
==================================
diff --git a/configure.ac b/configure.ac
index 05a5112..7fc5e8a 100644
--- a/configure.ac
+++ b/configure.ac
@@ -11,8 +11,8 @@ AC_PREREQ([2.59])
m4_define([tp_glib_major_version], [0])
m4_define([tp_glib_minor_version], [7])
-m4_define([tp_glib_micro_version], [15])
-m4_define([tp_glib_nano_version], [1])
+m4_define([tp_glib_micro_version], [16])
+m4_define([tp_glib_nano_version], [0])
# If library source has changed since last release, increment revision
# If interfaces have been added, removed or changed since last release,
@@ -26,9 +26,9 @@ m4_define([tp_glib_nano_version], [1])
# (we don't guarantee that we won't add ABI then remove it again, if it was
# never seen in a release).
-m4_define([tp_glib_lt_current], [16])
+m4_define([tp_glib_lt_current], [17])
m4_define([tp_glib_lt_revision], [0])
-m4_define([tp_glib_lt_age], [16])
+m4_define([tp_glib_lt_age], [17])
# Some magic
m4_define([tp_glib_base_version],
diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml
new file mode 100644
index 0000000..dfd4ec3
--- /dev/null
+++ b/spec/Channel_Dispatch_Operation.xml
@@ -0,0 +1,331 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Dispatch_Operation"
+ 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.ChannelDispatchOperation.DRAFT"
+ tp:causes-havoc="experimental">
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A channel dispatch operation is an object in the ChannelDispatcher
+ representing a bundle of unrequested channels being announced to
+ client
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Approver.DRAFT</tp:dbus-ref>
+ processes.</p>
+
+ <p>These objects can result from new incoming channels or channels
+ which are automatically created for some reason, but cannot result
+ from outgoing requests for channels.</p>
+
+ <p>More specifically, whenever the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.NewChannels</tp:dbus-ref>
+ signal contains channels whose
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.FUTURE.Requested</tp:dbus-ref>
+ property is false, or whenever the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref>
+ signal contains a channel with suppress_handler false,
+ one or more ChannelDispatchOperation objects are created for those
+ channels.</p>
+
+ <p>(If some channels in a NewChannels signal are in different bundles,
+ this is an error. The channel dispatcher SHOULD recover by treating
+ the NewChannels signal as if it had been several NewChannels signals
+ each containing one channel.)</p>
+
+ <p>First, the channel dispatcher SHOULD construct a list of all the
+ channel handlers that could handle all the channels, ordered by
+ priority in some implementation-dependent way. If there are handlers
+ which could handle all the channels, one channel dispatch operation
+ SHOULD be created for all the channels. If there are not, one channel
+ dispatch operation SHOULD be created for each channel, each with
+ a list of channel handlers that could handle that channel.</p>
+
+ <p>When listing channel handlers, priority SHOULD be given to
+ channel handlers that are already handling channels from the same
+ bundle.</p>
+
+ <p>Processing of a channel dispatch operation proceeds as follows.
+ If the channels in a channel dispatch operation are in the same
+ bundle as a channel that is already being handled, and the handler
+ could also handle the channels being dispatched, the channel
+ dispatcher SHOULD call the handler's
+ HandleAdditionalChannels
+ method to see whether the handler will accept the new channels too.
+ If the handler takes responsibility for the channels,
+ processing stops, and no approvers are run.</p>
+
+ <p>(FIXME: this is far too subtle and everyone will get it wrong.
+ Open issue: how else do we address this use case?)</p>
+
+ <tp:rationale>
+ <p>Some channel types can be picked up "quietly" by an existing
+ channel handler. If a Text channel is added to an existing
+ bundle containing a StreamedMedia channel, there shouldn't be
+ any approvers, flashing icons or notification bubbles, if the
+ the UI for the StreamedMedia channel can just add a text box
+ and display the message.</p>
+ </tp:rationale>
+
+ <p>If not, the channel dispatcher SHOULD send the channel dispatch
+ operation to all relevant approvers (in parallel) and wait for an
+ approver to claim the channels or request that they are handled.
+ See
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Approver.DRAFT">AddDispatchOperation</tp:dbus-ref>
+ for more details on this.</p>
+
+ <p>Finally, if the approver requested it, the channel dispatcher SHOULD
+ send the channels to a handler.</p>
+ </tp:docstring>
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ type="as" access="read" tp:type="DBus_Interface[]">
+ <tp:docstring>
+ A list of the extra interfaces provided by this channel dispatch
+ operation. This property cannot change.
+ </tp:docstring>
+ </property>
+
+ <property name="Connection" tp:name-for-bindings="Connection"
+ type="o" access="read">
+ <tp:docstring>
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
+ with which the <tp:member-ref>Channels</tp:member-ref> 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 '.'. This property cannot change.
+ </tp:docstring>
+ </property>
+
+ <property name="Account" tp:name-for-bindings="Account"
+ type="o" access="read">
+ <tp:docstring>
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
+ with which the <tp:member-ref>Connection</tp:member-ref>
+ and <tp:member-ref>Channels</tp:member-ref> are
+ associated. This property cannot change.
+ </tp:docstring>
+ </property>
+
+ <property name="Channels" tp:name-for-bindings="Channels"
+ type="a(oa{sv})" access="read" tp:type="Channel_Details[]">
+ <tp:docstring>
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s
+ to be dispatched, and their properties. Change notification is via
+ the <tp:member-ref>ChannelLost</tp:member-ref> signal (channels
+ cannot be added to this property, only removed).
+ </tp:docstring>
+ </property>
+
+ <signal name="ChannelLost" tp:name-for-bindings="Channel_Lost">
+ <tp:docstring>
+ A channel has closed before it could be claimed or handled.
+ </tp:docstring>
+
+ <arg name="Error" type="s" tp:type="DBus_Error_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The name of a D-Bus error indicating why the channel closed. If
+ no better reason can be found,
+ <code>org.freedesktop.Telepathy.Errors.NotAvailable</code> MAY
+ be used as a fallback; this means that this error SHOULD NOT be
+ given any more specific meaning.</p>
+
+ <p>FIXME: or should we invent a new OtherError for that purpose?</p>
+
+ <p>FIXME: we need to specify errors for these situations:</p>
+
+ <ul>
+ <li>kicked from a chatroom</li>
+ <li>outgoing call rejected</li>
+ <li>outgoing call timed out</li>
+ <li>incoming call terminated</li>
+ </ul>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Message" type="s">
+ <tp:docstring>
+ A string associated with the D-Bus error.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="PossibleHandlers" tp:name-for-bindings="Possible_Handlers"
+ type="as" access="read" tp:type="DBus_Well_Known_Name[]">
+ <tp:docstring>
+ The well known bus names (starting with
+ <code>org.freedesktop.Telepathy.Client.</code>) of the possible
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>s
+ for these channels. The channel dispatcher MUST place the most
+ preferred handlers first, according to some reasonable heuristic.
+ As a result, approvers SHOULD use the first handler by default.
+ </tp:docstring>
+ </property>
+
+ <method name="HandleWith" tp:name-for-bindings="Handle_With">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Called by an approver to accept a channel bundle and request that
+ the given handler be used to handle it.</p>
+
+ <p>If successful, this method will cause the ChannelDispatchOperation
+ object to disappear, emitting
+ <tp:member-ref>Finished</tp:member-ref>.</p>
+
+ <p>However, this method may fail because the dispatch has already been
+ completed and the object has already gone. If this occurs, it
+ indicates that another approver has asked for the bundle to be
+ handled by a particular handler. The approver MUST NOT attempt
+ to interact with the channels further in this case, unless it is
+ separately invoked as the handler.</p>
+
+ <p>Approvers which are also channel handlers SHOULD use Claim instead
+ of HandleWith to request that they can handle a channel bundle
+ themselves.</p>
+
+ <p>(FIXME: list some possible errors)</p>
+
+ <p>If the channel handler raises an error from Handle, this method
+ MAY respond by raising that same error, even if it is not
+ specifically documented here.</p>
+ </tp:docstring>
+
+ <arg direction="in" type="s" tp:type="DBus_Bus_Name" name="Handler">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The well-known bus name (starting with
+ <code>org.freedesktop.Telepathy.Client.</code>) of the channel
+ handler that should handle the channel.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The selected handler is not a syntactically correct
+ <tp:type>DBus_Bus_Name</tp:type> or does not start with
+ "<code>org.freedesktop.Telepathy.Client.</code>".
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The selected handler is temporarily unable to handle these
+ channels.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The selected handler is syntactically correct, but will never
+ be able to handle these channels (for instance because the channels
+ do not match its HandlerChannelFilter, or because HandleChannels
+ raised NotImplemented).
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotYours">
+ <tp:docstring>
+ At the time that HandleWith was called, this dispatch operation was
+ processing an earlier call to HandleWith. The earlier call has
+ now succeeded, so some Handler nominated by another approver is
+ now responsible for the channels. In this situation, the second
+ call to HandleWith MUST NOT return until the first one has
+ returned successfully or unsuccessfully, and if the first call
+ to HandleChannels fails, the channel dispatcher SHOULD try to obey
+ the choice of Handler made by the second call to HandleWith.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="Claim" tp:name-for-bindings="Claim">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Called by an approver to claim channels for handling
+ internally. If this method is called successfully, the process
+ calling this method becomes the handler for the channel, but
+ <em>does not</em> have the HandleChannels method called on it.</p>
+ <!-- FIXME: tp:dbus-ref -->
+
+ <p>Clients that call Claim on channels but do not immediately
+ close them SHOULD implement the Handler interface and its
+ CurrentlyHandledChannels property.</p>
+ <!-- FIXME: tp:dbus-ref -->
+
+ <p>Approvers wishing to reject channels MUST call this method to
+ claim ownership of them, and MUST NOT call
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>
+ on the channels unless/until this method returns successfully.</p>
+
+ <tp:rationale>
+ <p>The channel dispatcher can't know how best to close arbitrary
+ channel types, so it leaves it up to the approver to do so.
+ For instance, for Text channels it is necessary
+ to acknowledge any messages that have already been displayed to
+ the user first - ideally, the approver would display and then
+ acknowledge the messages.</p>
+ </tp:rationale>
+
+ <p>If successful, this method will cause the ChannelDispatchOperation
+ object to disappear, emitting
+ <tp:member-ref>Finished</tp:member-ref>, in the same way as for
+ <tp:member-ref>HandleWith</tp:member-ref>.</p>
+
+ <p>This method may fail because the dispatch operation has already
+ been completed. Again, see HandleWith for more details. The approver
+ MUST NOT attempt to interact with the channels further in this
+ case.</p>
+
+ <p>(FIXME: list some other possible errors)</p>
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotYours">
+ <tp:docstring>
+ At the time that Claim was called, this dispatch operation was
+ processing a call to HandleWith which has now succeeded, so
+ some Handler nominated by another approver is now responsible for
+ the channel.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="Finished" tp:name-for-bindings="Finished">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when this dispatch operation finishes. The dispatch
+ operation is no longer present and further methods must not be
+ called on it.</p>
+
+ <p>Its object path SHOULD NOT be reused for a subsequent dispatch
+ operation; the ChannelDispatcher MUST choose object paths
+ in a way that avoids immediate re-use.</p>
+
+ <tp:rationale>
+ <p>Otherwise, clients might accidentally call HandleWith or Claim
+ on a new dispatch operation instead of the one they
+ intended to handle.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </signal>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml
new file mode 100644
index 0000000..822e7dd
--- /dev/null
+++ b/spec/Channel_Dispatcher.xml
@@ -0,0 +1,222 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Dispatcher"
+ 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.ChannelDispatcher.DRAFT"
+ tp:causes-havoc="experimental">
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The channel dispatcher is responsible for responding to new
+ channels and launching client processes to handle them. It also
+ provides functionality for client processes to request that new
+ channels are created.</p>
+
+ <p>If a channel dispatcher is running, it is responsible for dispatching
+ new channels on all
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>s
+ created by the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>.
+ Connections not created by the AccountManager are outside the scope
+ of the channel dispatcher.</p>
+
+ <tp:rationale>
+ <p>Connections created by standalone Telepathy clients
+ that do not intend to interact with the channel dispatcher
+ should be ignored - otherwise, the channel dispatcher would try
+ to launch handlers for channels that the standalone client
+ was already handling internally.</p>
+ </tp:rationale>
+
+ <p>The current channel dispatcher is defined to be the process that
+ owns the well-known bus name
+ <code>org.freedesktop.Telepathy.ChannelDispatcher</code> on
+ the session bus. This process MUST export an object with this
+ interface at the object path
+ <code>/org/freedesktop/Telepathy/ChannelDispatcher</code>.</p>
+
+ <p>Until a mechanism exists for making a reasonable automatic choice
+ of ChannelDispatcher implementation, implementations SHOULD NOT
+ register as an activatable service for the ChannelDispatcher's
+ well-known bus name. Instead, it is RECOMMENDED that some component
+ of the user's session will select and activate a particular
+ implementation, and that other Telepathy-enabled programs
+ can detect whether channel request/dispatch functionality is available
+ by checking whether the ChannelDispatcher's well-known name is in use
+ at runtime.</p>
+
+ <p>There are three categories of client process defined by this
+ specification:</p>
+
+ <dl>
+ <dt>Observer</dt>
+ <dd><p>Observers monitor the creation of new channels. This
+ functionality can be used for things like message logging.
+ All observers are notified simultaneously.</p></dd>
+
+ <dt>Approver</dt>
+ <dd>
+ <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.</p>
+ </dd>
+
+ <dt>Handler</dt>
+ <dd>
+ <p>Each new channel or set of channels is passed to exactly one
+ handler as its final destination. A typical channel handler is a
+ user interface process handling channels of a particular type.</p>
+ </dd>
+ </dl>
+ </tp:docstring>
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ type="as" access="read" tp:type="DBus_Interface[]">
+ <tp:docstring>
+ A list of the extra interfaces provided by this channel dispatcher.
+ </tp:docstring>
+ </property>
+
+ <method name="CreateChannel" tp:name-for-bindings="Create_Channel">
+ <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.DRAFT</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.DRAFT.Proceed</tp:dbus-ref>
+ is called, at which point
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT.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="t"
+ tp:type="Unix_Timestamp64">
+ <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.DRAFT">UserActionTime</tp:dbus-ref>
+ property will be set to this value.</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, 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
+ HandleChannel on it, and partly so the channel dispatcher
+ can recover state if it crashes and is restarted.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Request" type="o">
+ <tp:docstring>
+ A
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT</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>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Dispatcher_Interface_Operation_List.xml b/spec/Channel_Dispatcher_Interface_Operation_List.xml
new file mode 100644
index 0000000..40cd86e
--- /dev/null
+++ b/spec/Channel_Dispatcher_Interface_Operation_List.xml
@@ -0,0 +1,138 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Dispatcher_Interface_Operation_List"
+ 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.ChannelDispatcher.Interface.OperationList.DRAFT"
+ tp:causes-havoc="experimental">
+
+ <tp:requires interface="org.freedesktop.Telepathy.ChannelDispatcher.DRAFT"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface allows users of the ChannelDispatcher to enumerate
+ all the pending dispatch operations, with change notification.</p>
+
+ <tp:rationale>
+ <p>The existence of the DispatchOperations property allows a newly
+ started approver to pick up existing dispatch operations.</p>
+
+ <p>This is on a separate interface so clients that aren't interested
+ in doing this aren't woken up by its signals.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <tp:struct name="Dispatch_Operation_Details"
+ array-name="Dispatch_Operation_Details_List">
+
+ <tp:docstring>
+ Details of a channel dispatch operation.
+ </tp:docstring>
+
+ <tp:member name="Channel_Dispatch_Operation" type="o">
+ <tp:docstring>
+ The object path of the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref>.
+ </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 dispatch operation.</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>The rationale is the same as for
+ <tp:type-ref>Channel_Details</tp:type-ref>.</p>
+ </tp:rationale>
+
+ <p>Each dictionary MUST contain at least the following keys:</p>
+ <ul>
+ <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.Interfaces</tp:dbus-ref></li>
+ <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.Connection</tp:dbus-ref></li>
+ <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.Account</tp:dbus-ref></li>
+ <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.Channels</tp:dbus-ref></li>
+ <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.PossibleHandlers</tp:dbus-ref></li>
+ </ul>
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <property
+ name="DispatchOperations" tp:name-for-bindings="Dispatch_Operations"
+ type="a(oa{sv})" tp:type="Dispatch_Operation_Details[]" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The list of ChannelDispatchOperation objects currently being
+ processed. Change notification is via the NewDispatch and
+ DispatchFinished signals.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="NewDispatchOperation"
+ tp:name-for-bindings="New_Dispatch_Operation">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when a dispatch operation is added to
+ <tp:member-ref>DispatchOperations</tp:member-ref>.</p>
+ </tp:docstring>
+
+ <arg name="Dispatch_Operation" type="o">
+ <tp:docstring>
+ The dispatch operation that was created.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Properties"
+ type="a{sv}" tp:type="Qualified_Property_Value_Map">
+ <tp:docstring>
+ The same properties that would appear in the Properties member of
+ <tp:type-ref>Dispatch_Operation_Details</tp:type-ref>.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="DispatchOperationFinished"
+ tp:name-for-bindings="Dispatch_Operation_Finished">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Emitted when a dispatch operation finishes (i.e. exactly once per
+ emission of <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.DRAFT.Finished</tp:dbus-ref>).
+
+ <tp:rationale>
+ Strictly speaking this is redundant with
+ ChannelDispatchOperation.Finished, but it provides full
+ change-notification for the DispatchOperations property.
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Dispatch_Operation" type="o">
+ <tp:docstring>
+ The dispatch operation that was closed.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Call_State.xml b/spec/Channel_Interface_Call_State.xml
index 132137e..0df6e34 100644
--- a/spec/Channel_Interface_Call_State.xml
+++ b/spec/Channel_Interface_Call_State.xml
@@ -101,6 +101,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
unhold the call again.
</tp:docstring>
</tp:flag>
+
+ <tp:flag suffix="Forwarded" value="8">
+ <tp:docstring>
+ The initiator of the call originally called a contact other than the
+ current recipient of the call, but the call was then forwarded or
+ diverted.
+ </tp:docstring>
+ </tp:flag>
</tp:flags>
</interface>
diff --git a/spec/Channel_Interface_Destroyable.xml b/spec/Channel_Interface_Destroyable.xml
new file mode 100644
index 0000000..2f82e69
--- /dev/null
+++ b/spec/Channel_Interface_Destroyable.xml
@@ -0,0 +1,79 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Destroyable"
+ 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.Channel.Interface.Destroyable.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:added version="0.17.UNRELEADED">(draft, not API-stable)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface exists to support channels where
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>
+ is insufficiently destructive.</p>
+ </tp:docstring>
+
+ <method name="Destroy" tp:name-for-bindings="Destroy">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Close the channel abruptly, possibly with loss of data. The
+ connection manager MUST NOT re-create the channel unless/until
+ more events occur.</p>
+
+ <tp:rationale>
+ <p>The main motivating situation for this method is that when a Text
+ channel with pending messages is closed with Close, it comes back
+ as an incoming channel (to avoid a race between Close and an
+ incoming message). If Destroy is called on a Text channel, the CM
+ should delete all pending messages and close the channel, and
+ the channel shouldn't be re-created until/unless another message
+ arrives.</p>
+ </tp:rationale>
+
+ <p>Most clients SHOULD call
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>
+ instead. However, if a client explicitly intends to destroy the
+ channel with possible loss of data, it SHOULD call this method
+ if this interface is supported (according to the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Interfaces</tp:dbus-ref>
+ property), falling back to Close if not.</p>
+
+ <p>In particular, channel dispatchers SHOULD use this method if
+ available when terminating channels that cannot be handled
+ correctly (for instance, if no handler has been installed for
+ a channel type, or if the handler crashes repeatedly).</p>
+
+ <p>Connection managers do not need to implement this interface on
+ channels where Close and Destroy would be equivalent.</p>
+
+ <tp:rationale>
+ <p>Callers need to be able to fall back to Close in any case.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml
new file mode 100644
index 0000000..25f5b06
--- /dev/null
+++ b/spec/Channel_Request.xml
@@ -0,0 +1,178 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Request"
+ 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.ChannelRequest.DRAFT"
+ tp:causes-havoc="experimental">
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A channel request is an object in the ChannelDispatcher representing
+ an ongoing request for some channels to be created or found. There
+ can be any number of ChannelRequest objects at the same time.</p>
+
+ <p>Its well-known bus name is the same as that of the ChannelDispatcher,
+ "org.freedesktop.Telepathy.ChannelDispatcher".</p>
+
+ <tp:rationale>
+ <p>See
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatcher.DRAFT.CreateChannel</tp:dbus-ref>
+ for rationale for ChannelRequest being a separate object.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <property name="UserActionTime" tp:name-for-bindings="User_Action_Time"
+ type="t" tp:type="Unix_Timestamp64" access="read">
+ <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 corresponds to the _NET_WM_USER_TIME property in
+ <a href="http://standards.freedesktop.org/wm-spec/wm-spec-latest.html">EWMH</a>.</p>
+
+ <p>This property is set when the channel request is created,
+ and can never change.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="Requests" tp:name-for-bindings="Requests" type="aa{sv}"
+ tp:type="Qualified_Property_Value_Map[]"
+ access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An array of dictionaries containing desirable properties for
+ the channel or channels to be created.</p>
+
+ <tp:rationale>
+ <p>This is an array so that we could add a CreateChannels method in
+ future without redefining the API of ChannelRequest.</p>
+ </tp:rationale>
+
+ <p>This property is set when the channel request is created,
+ and can never change.</p>
+ </tp:docstring>
+ </property>
+
+ <method name="Proceed" tp:name-for-bindings="Proceed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Proceed with the channel request.</p>
+
+ <tp:rationale>
+ <p>The client that created this object calls this method
+ when it has connected signal handlers for
+ <tp:member-ref>Succeeded</tp:member-ref> and
+ <tp:member-ref>Failed</tp:member-ref>.</p>
+ </tp:rationale>
+
+ <p>Clients other than the client which created the ChannelRequest
+ MUST NOT call this method.</p>
+
+ <p>This method SHOULD return immediately; on success, the request
+ might still fail, but this will be indicated asynchronously
+ by the <tp:member-ref>Failed</tp:member-ref> signal.</p>
+
+ <p>Proceed cannot fail, unless clients have got the life-cycle
+ of a ChannelRequest seriously wrong (e.g. a client calls this
+ method twice, or a client that did not create the ChannelRequest
+ calls this method). If it fails, clients SHOULD assume that the
+ whole ChannelRequest has become useless.</p>
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Errors.NotAvailable">
+ <tp:docstring>
+ This method has already been called, so it is no longer
+ available. Stop calling it.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="Cancel" tp:name-for-bindings="Cancel">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Cancel the channel request. The precise effect depends on the
+ current progress of the request.</p>
+
+ <p>If the connection manager has not already been asked to create
+ a channel, then <tp:member-ref>Failed</tp:member-ref> is emitted
+ immediately, and the channel request is removed.</p>
+
+ <p>If the connection manager has already been asked to create a
+ channel but has not produced one yet (e.g. if <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+ has been called, but has not yet returned), then the
+ ChannelDispatcher will remember that the request has been cancelled.
+ When the channel appears, it will be closed (if it was newly
+ created and can be closed), and will not be dispatched to a
+ handler.</p>
+
+ <p>If the connection manager has already returned a channel, but the
+ channel has not yet been dispatched to a handler
+ (e.g. if <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+ has returned a channel, but the dispatch operation is waiting for
+ approvers) then the channel dispatcher will not dispatch that
+ channel to a handler. If the channel was newly created for this
+ request, the channel dispatcher will close it with Close; otherwise,
+ the channel dispatcher will ignore it. In either case,
+ <tp:member-ref>Failed</tp:member-ref> will be emitted when processing
+ has been completed.</p>
+
+ <p>If Failed is emitted in response to this method, the error SHOULD be
+ <code>org.freedesktop.Telepathy.Errors.Cancelled</code>.</p>
+
+ <p>If the channel has already been dispatched to a handler, then
+ it's too late to call this method, and the channel request will
+ no longer exist.</p>
+ </tp:docstring>
+ </method>
+
+ <signal name="Failed" tp:name-for-bindings="Failed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The channel request has failed. It is no longer present,
+ and further methods must not be called on it.</p>
+ </tp:docstring>
+
+ <arg name="Error" type="s" tp:type="DBus_Error_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The name of a D-Bus error. This can come from various sources,
+ including the error raised by CreateChannel, or an error generated
+ to represent failure to establish the Connection.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Message" type="s">
+ <tp:docstring>
+ If the first argument of the D-Bus error message was a string,
+ that string. Otherwise, an empty string.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="Succeeded" tp:name-for-bindings="Succeeded">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The channel request has succeeded. It is no longer present,
+ and further methods must not be called on it.</p>
+ </tp:docstring>
+ </signal>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Client.xml b/spec/Client.xml
new file mode 100644
index 0000000..da3cfbe
--- /dev/null
+++ b/spec/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/spec/Client_Approver.xml b/spec/Client_Approver.xml
new file mode 100644
index 0000000..c912b12
--- /dev/null
+++ b/spec/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/spec/Client_Handler.xml b/spec/Client_Handler.xml
new file mode 100644
index 0000000..4e815d0
--- /dev/null
+++ b/spec/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/spec/Client_Observer.xml b/spec/Client_Observer.xml
new file mode 100644
index 0000000..eccbefd
--- /dev/null
+++ b/spec/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/spec/Makefile.am b/spec/Makefile.am
index ea52825..83c57ef 100644
--- a/spec/Makefile.am
+++ b/spec/Makefile.am
@@ -3,12 +3,16 @@ EXTRA_DIST = \
Account_Manager.xml \
Account.xml \
all.xml \
+ Channel_Dispatch_Operation.xml \
+ Channel_Dispatcher.xml \
+ Channel_Dispatcher_Interface_Operation_List.xml \
Channel_Future.xml \
Channel_Handler.xml \
Channel_Interface_Call_Merging.xml \
Channel_Interface_Call_State.xml \
Channel_Interface_Chat_State.xml \
Channel_Interface_Delivery_Reporting.xml \
+ Channel_Interface_Destroyable.xml \
Channel_Interface_DTMF.xml \
Channel_Interface_Group.xml \
Channel_Interface_Hold.xml \
@@ -17,6 +21,7 @@ EXTRA_DIST = \
Channel_Interface_Messages.xml \
Channel_Interface_Password.xml \
Channel_Interface_Transfer.xml \
+ Channel_Request.xml \
Channel_Type_Contact_List.xml \
Channel_Type_Contact_Search.xml \
Channel_Type_Room_List.xml \
@@ -24,6 +29,10 @@ EXTRA_DIST = \
Channel_Type_Text.xml \
Channel_Type_Tubes.xml \
Channel.xml \
+ Client.xml \
+ Client_Approver.xml \
+ Client_Handler.xml \
+ Client_Observer.xml \
Connection_Interface_Aliasing.xml \
Connection_Interface_Avatars.xml \
Connection_Interface_Capabilities.xml \
diff --git a/spec/all.xml b/spec/all.xml
index d60f9e3..a9c58c1 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -3,7 +3,7 @@
xmlns:xi="http://www.w3.org/2001/XInclude">
<tp:title>Telepathy D-Bus Interface Specification</tp:title>
-<tp:version>0.17.11</tp:version>
+<tp:version>0.17.12</tp:version>
<tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright>
<tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright>
@@ -31,14 +31,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Connection_Interface_Avatars.xml"/>
<xi:include href="Connection_Interface_Capabilities.xml"/>
<xi:include href="Connection_Interface_Contacts.xml"/>
-<!-- Never implemented, is a terrible API
-<xi:include href="Connection_Interface_Contact_Info.xml"/> -->
-<!-- Never implemented, insufficient (needs conditions)
-<xi:include href="Connection_Interface_Forwarding.xml"/> -->
<xi:include href="Connection_Interface_Simple_Presence.xml"/>
<xi:include href="Connection_Interface_Presence.xml"/>
-<!-- Never implemented, vague
-<xi:include href="Connection_Interface_Privacy.xml"/> -->
<xi:include href="Connection_Interface_Renaming.xml"/>
<xi:include href="Connection_Interface_Requests.xml"/>
@@ -47,8 +41,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Channel.xml"/>
<xi:include href="Channel_Future.xml"/>
<xi:include href="Channel_Type_Contact_List.xml"/>
-<!-- Never implemented, can't be implemented with current dbus-glib, vague
-<xi:include href="Channel_Type_Contact_Search.xml"/> -->
<xi:include href="Channel_Type_Streamed_Media.xml"/>
<xi:include href="Channel_Type_Room_List.xml"/>
<xi:include href="Channel_Type_Text.xml"/>
@@ -58,13 +50,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Channel_Interface_Call_State.xml"/>
<xi:include href="Channel_Interface_Chat_State.xml"/>
<xi:include href="Channel_Interface_Delivery_Reporting.xml"/>
+<xi:include href="Channel_Interface_Destroyable.xml"/>
<xi:include href="Channel_Interface_DTMF.xml"/>
<xi:include href="Channel_Interface_Group.xml"/>
<xi:include href="Channel_Interface_Hold.xml"/>
<xi:include href="Channel_Interface_HTML.xml"/>
<xi:include href="Channel_Interface_Password.xml"/>
-<!-- Causes havoc, never implemented, unclear requirements
-<xi:include href="Channel_Interface_Transfer.xml"/> -->
<xi:include href="Channel_Interface_Media_Signalling.xml"/>
<xi:include href="Channel_Interface_Messages.xml"/>
@@ -77,9 +68,30 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Account.xml"/>
<xi:include href="Account_Interface_Avatar.xml"/>
+<xi:include href="Channel_Dispatcher.xml"/>
+<xi:include href="Channel_Dispatcher_Interface_Operation_List.xml"/>
+<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_Handler.xml"/>
+
<xi:include href="Channel_Handler.xml"/>
<xi:include href="errors.xml"/>
<xi:include href="generic-types.xml"/>
+<!-- Never implemented, is a terrible API
+<xi:include href="Connection_Interface_Contact_Info.xml"/> -->
+<!-- Never implemented, insufficient (needs conditions)
+<xi:include href="Connection_Interface_Forwarding.xml"/> -->
+<!-- Never implemented, vague
+<xi:include href="Connection_Interface_Privacy.xml"/> -->
+<!-- Never implemented, can't be implemented with current dbus-glib, vague
+<xi:include href="Channel_Type_Contact_Search.xml"/> -->
+<!-- Causes havoc, never implemented, unclear requirements
+<xi:include href="Channel_Interface_Transfer.xml"/> -->
+
</tp:spec>
diff --git a/spec/errors.xml b/spec/errors.xml
index 81ab440..679e3f4 100644
--- a/spec/errors.xml
+++ b/spec/errors.xml
@@ -1,5 +1,8 @@
<?xml version="1.0" ?>
<tp:errors xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" namespace="org.freedesktop.Telepathy.Error">
+ <!-- Don't re-order these errors until fd.o #17588 is fixed, or you will
+ break telepathy-glib's ABI.
+ -->
<tp:error name="Network Error">
<tp:docstring>
Raised when there is an error reading from or writing to the network.
@@ -60,8 +63,22 @@
</tp:docstring>
</tp:error>
- <tp:copyright>Copyright (C) 2005, 2006, 2007 Collabora Limited</tp:copyright>
- <tp:copyright>Copyright (C) 2005, 2006, 2007 Nokia Corporation</tp:copyright>
+ <tp:error name="Not Yours">
+ <tp:docstring>
+ The requested channel or other resource already exists, and another
+ client is responsible for it
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Cancelled">
+ <tp:docstring>
+ Raised by an ongoing request if it is cancelled by user request before
+ it has completed.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright (C) 2005-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
diff --git a/spec/generic-types.xml b/spec/generic-types.xml
index 480b2c9..9d8501d 100644
--- a/spec/generic-types.xml
+++ b/spec/generic-types.xml
@@ -67,7 +67,8 @@
"org.freedesktop.DBus.Peer.Ping".</tp:docstring>
</tp:simple-type>
- <tp:mapping name="Qualified_Property_Value_Map">
+ <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">
diff --git a/telepathy-glib/Makefile.am b/telepathy-glib/Makefile.am
index ae2993e..741290b 100644
--- a/telepathy-glib/Makefile.am
+++ b/telepathy-glib/Makefile.am
@@ -18,7 +18,8 @@ ABI_LISTS = \
versions/0.7.12.abi \
versions/0.7.13.abi \
versions/0.7.14.abi \
- versions/0.7.15.abi
+ versions/0.7.15.abi \
+ versions/0.7.16.abi
EXTRA_DIST = \
$(ABI_LISTS) \
diff --git a/telepathy-glib/channel-manager.c b/telepathy-glib/channel-manager.c
index f6b6d71..e134fa0 100644
--- a/telepathy-glib/channel-manager.c
+++ b/telepathy-glib/channel-manager.c
@@ -154,12 +154,14 @@
* @ensure_channel: Respond to a request for a (new or existing) channel made
* with the Connection.Interface.Requests.EnsureChannel method. See
* #TpChannelManagerRequestFunc for details.
- * Since: 0.7.UNRELEASED+1
+ * Since: 0.7.16
*
* The vtable for a channel manager implementation.
*
* In addition to the fields documented here there are several GCallback
* fields which must currently be %NULL.
+ *
+ * Since: 0.7.15
*/
@@ -639,7 +641,7 @@ tp_channel_manager_request_channel (TpChannelManager *manager,
*
* Returns: %TRUE if this request will be handled by @manager; else %FALSE.
*
- * Since: 0.7.UNRELEASED+1
+ * Since: 0.7.16
*/
gboolean
tp_channel_manager_ensure_channel (TpChannelManager *manager,
diff --git a/telepathy-glib/connection.c b/telepathy-glib/connection.c
index 54c7237..6785bbb 100644
--- a/telepathy-glib/connection.c
+++ b/telepathy-glib/connection.c
@@ -1066,7 +1066,7 @@ get_presence_type_availability (TpConnectionPresenceType type)
*
* Returns: -1, 0 or 1, if @p1 is <, == or > than @p2.
*
- * Since: 0.7.UNRELEASED
+ * Since: 0.7.16
*/
gint
tp_connection_presence_type_cmp_availability (TpConnectionPresenceType p1,
diff --git a/telepathy-glib/versions/0.7.16.abi b/telepathy-glib/versions/0.7.16.abi
new file mode 100644
index 0000000..7d2ec51
--- /dev/null
+++ b/telepathy-glib/versions/0.7.16.abi
@@ -0,0 +1,9 @@
+Version: TELEPATHY_GLIB_0.7.16
+Extends: TELEPATHY_GLIB_0.7.15
+Release: 0.7.16
+
+tp_channel_manager_ensure_channel
+tp_cli_connection_interface_requests_call_ensure_channel
+tp_cli_connection_interface_requests_run_ensure_channel
+tp_connection_presence_type_cmp_availability
+tp_svc_connection_interface_requests_implement_ensure_channel
--
1.5.6.5
More information about the Telepathy-commits
mailing list