Start developement.

1 files changed, 300 insertions, 0 deletions

diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml
new file mode 100644
index 0000000..1a9c397
--- /dev/null
+++ b/spec/Channel_Request.xml
@@ -0,0 +1,300 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Request"
+  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+  <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+  <tp:copyright>Copyright © 2008-2009 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">
+    <tp:added version="0.17.26">(as a stable interface)</tp:added>
+
+    <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.CreateChannel</tp:dbus-ref>
+          for rationale for ChannelRequest being a separate object.</p>
+      </tp:rationale>
+
+      <p>A channel request can be cancelled by any client (not just the one
+        that requested it). This means that the ChannelDispatcher will
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>
+        the resulting channel, or refrain from requesting it at all, rather
+        than dispatching it to a handler.</p>
+    </tp:docstring>
+
+    <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>
+        on which this request was made. This property cannot change.
+      </tp:docstring>
+    </property>
+
+    <property name="UserActionTime" tp:name-for-bindings="User_Action_Time"
+      type="x" tp:type="User_Action_Timestamp" 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 property is set when the channel request is created,
+          and can never change.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="PreferredHandler" tp:name-for-bindings="Preferred_Handler"
+      type="s" tp:type="DBus_Well_Known_Name" access="read">
+      <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.</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>
+
+    <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 request.
+        This property cannot change.
+      </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.Error.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
+          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 <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>;
+          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 <tp:member-ref>Failed</tp:member-ref> is emitted in response to
+          this method, the error SHOULD be
+          <code>org.freedesktop.Telepathy.Error.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 <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>,
+            or an error generated
+            to represent failure to establish the <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>.</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>
+
+    <property name="Hints" tp:name-for-bindings="Hints"
+      type="a{sv}" access="read">
+      <tp:added version="0.21.5"/>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>A dictionary of metadata provided by the channel
+          requester, which the handler and other clients MAY choose to
+          interpret.  Currently no standard keys are defined; clients MAY
+          choose to use platform-specific keys for their own purposes, but MUST
+          ignore unknown keys and MUST cope with expected keys being
+          missing. Clients SHOULD namespace hint names by having them
+          start with a reversed domain name, in the same way as D-Bus
+          interface names.</p>
+
+        <tp:rationale>This property might be used to pass a contact ID for a
+          telephone number shared between two contacts from the address book to
+          the call UI, so that if you try to call “Mum”, the call UI knows this
+          rather than having to guess or show “Calling Mum or Dad”. The format
+          of these contact IDs would be platform-specific, so we leave the
+          definition of the dictionary entry up to the platform in question.
+          But third-party channel requesters might not include the contact ID,
+          so the call UI has to be able to deal with it not being
+          there.</tp:rationale>
+
+        <p>The channel dispatcher does not currently interpret any of these
+          hints: they are solely for communication between cooperating
+          clients. If hints that do affect the channel dispatcher are added in
+          future, their names will start with an appropriate reversed domain
+          name (e.g. <code>org.freedesktop.Telepathy</code> for hints defined
+          by this specification, or an appropriate vendor name for third-party
+          plugins).</p>
+
+        <p>This property may be set when the channel request is created, and
+          can never change. Since it is immutable, it SHOULD be included in the
+          dictionary of properties passed to <tp:dbus-ref
+          namespace="ofdT.Client.Interface.Requests">AddRequest</tp:dbus-ref>
+          by the <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>.</p>
+      </tp:docstring>
+    </property>
+
+    <signal name="SucceededWithChannel" tp:name-for-bindings="Succeeded_With_Channel">
+      <tp:added version="0.21.5"/>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Variant of the <tp:dbus-ref
+            namespace="ofdT.ChannelRequest">Succeeded</tp:dbus-ref> signal
+        allowing to get the channel which has been created.</p>
+
+        <p>This signal MUST be emitted if the
+          <tp:dbus-ref namespace="ofdT">ChannelDispatcher</tp:dbus-ref>'s
+          <tp:dbus-ref
+            namespace="ofdT.ChannelDispatcher">SupportsRequestHints</tp:dbus-ref>
+          property is true. If supported, it MUST be emitted before
+          the <tp:member-ref>Succeeded</tp:member-ref> signal.</p>
+      </tp:docstring>
+
+      <arg name="Connection" type="o">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The Connection owning the channel.</p>
+        </tp:docstring>
+      </arg>
+
+      <arg name="Connection_Properties" type="a{sv}"
+        tp:type="Qualified_Property_Value_Map">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>A subset of the Connection's properties, currently unused.
+            This parameter may be used in future.</p>
+        </tp:docstring>
+      </arg>
+
+      <arg name="Channel" type="o">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The channel which has been created.</p>
+        </tp:docstring>
+      </arg>
+
+      <arg name="Channel_Properties" type="a{sv}"
+        tp:type="Qualified_Property_Value_Map">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The same immutable properties of the Channel that would appear
+            in a <tp:dbus-ref namespace="ofdT.Connection.Interface.Requests"
+              >NewChannels</tp:dbus-ref> signal.</p>
+        </tp:docstring>
+      </arg>
+
+    </signal>
+
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->