path: root/xml/Account_Interface_ChannelRequests.xml

<?xml version="1.0" ?>
<node name="/Account_Interface_ChannelRequests" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <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="com.nokia.Account.Interface.ChannelRequests">
    <tp:requires interface="org.freedesktop.Telepathy.Account"/>
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>The ChannelRequests interface provides methods to create and cancel channel requests, and signals to monitor them.</p>
    </tp:docstring>

    <method name="Create" tp:name-for-bindings="Create">
      <tp:docstring>
        Create a channel request.
      </tp:docstring>

      <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: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.
            This value will eventually be passed as the
            <code>User_Action_Time</code> parameter of <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref>.</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
              <tp:dbus-ref
                namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref>
              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. Currently the object itself is not implemented and this
          object path should be used only like a unique indentifier for the
          channel request.
        </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>

    <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Start a request to ensure that a channel exists, creating it if
          necessary.</p>
      </tp:docstring>

      <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.EnsureChannel</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: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.
            This value will eventually be passed as the
            <code>User_Action_Time</code> parameter of <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref>.</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.</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
              <tp:dbus-ref
                namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref>
              on it, and partly so the channel dispatcher
              can recover state if it crashes and is restarted.</p>
          </tp:rationale>

          <p>If any new channels are created in response to this
            request, 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. If the requested channel already exists (that
            is, <tp:dbus-ref
              namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>
            returns <code>Yours=False</code>) then the channel dispatcher
            SHOULD re-dispatch the channel to its existing handler, and MUST
            NOT dispatch it to this client (unless it is the existing handler);
            the request is still deemed to have succeeded in this case.</p>

          <tp:rationale>
            <p>An address book application, for example, might call <tp:dbus-ref
                namespace='org.freedesktop.Telepathy.ChannelDispatcher.DRAFT'>EnsureChannel</tp:dbus-ref>
              to ensure that a text channel with a particular contact is
              displayed to the user; it does not care whether a new channel was
              made. An IM client might call <tp:dbus-ref
                namespace='org.freedesktop.Telepathy.ChannelDispatcher.DRAFT'>EnsureChannel</tp:dbus-ref>
              in response to the user double-clicking an entry in the contact
              list, with itself as the <code>Preferred_Handler</code>; if the
              user already has a conversation with that contact in another
              application, they would expect the existing window to be
              presented, rather than their double-click leading to an error
              message.  So the request should succeed, even if its
              <code>Preferred_Handler</code> is not used.</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>

    <method name="Cancel" tp:name-for-bindings="Cancel">
      <tp:docstring>
        <p>Cancel a 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 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>

      <arg type="o" name="Request" direction="in">
        <tp:docstring>The channel request to be cancelled.</tp:docstring>
      </arg>

    </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="Request" type="o">
        <tp:docstring>The channel request.</tp:docstring>
      </arg>

      <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>

      <arg name="Request" type="o">
        <tp:docstring>The channel request.</tp:docstring>
      </arg>
    </signal>

  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->