Update spec to 0.17.12 (no code changes) and prepare 0.7.16 releasetelepathy-glib-0.7.16

20 files changed, 1810 insertions, 25 deletions

diff --git a/NEWS b/NEWS
index 41494b7b9..9bd49e680 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 05a511200..7fc5e8a16 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 000000000..dfd4ec3e2
--- /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 000000000..822e7dd9a
--- /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 000000000..40cd86e54
--- /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 132137eda..0df6e3472 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 000000000..2f82e6980
--- /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 000000000..25f5b066c
--- /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 000000000..da3cfbef4
--- /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 000000000..c912b128c
--- /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 000000000..4e815d030
--- /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 000000000..eccbefdcc
--- /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 ea5282522..83c57ef1b 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 d60f9e398..a9c58c113 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 81ab440e7..679e3f4e2 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 480b2c958..9d8501de9 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 ae2993e50..741290bef 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 f6b6d71ef..e134fa044 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 54c723726..6785bbb5c 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 000000000..7d2ec51de
--- /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