path: root/spec/Channel_Type_Stream_Tube.xml

<?xml version="1.0" ?>
<node name="/Channel_Type_Stream_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright>
  <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
  <tp:license>
    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.

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.

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.
  </tp:license>
  <interface name="org.freedesktop.Telepathy.Channel.Type.StreamTube">
    <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
    <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube"/>
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>A stream tube is a transport for ordered, reliable data transfer,
        similar to SOCK_STREAM sockets.</p>

      <p>When offering a stream tube, the initiating client creates a local
        listening socket and offers it to the recipient client using the
        <tp:member-ref>Offer</tp:member-ref> method.  When a
        recipient accepts a stream tube using the
        <tp:member-ref>Accept</tp:member-ref> method, the
        recipient's connection manager creates a new local listening socket.
        Each time the recipient's client connects to this socket, the
        initiator's connection manager proxies this connection to the
        originally offered socket.</p>

    </tp:docstring>

    <method name="Offer" tp:name-for-bindings="Offer">
      <tp:docstring>
        Offer a stream tube exporting the local socket specified.
      </tp:docstring>
      <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type">
        <tp:docstring>
          The type of the listening address of the local service, as a member of
          Socket_Address_Type.
        </tp:docstring>
      </arg>
      <arg direction="in" name="address" type="v">
        <tp:docstring>
          The listening address of the local service, as indicated by the
          address_type.
        </tp:docstring>
      </arg>
      <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
        <tp:docstring>
          The access control the local service applies to the local socket,
          specified so the connection manager can behave appropriately
          when it connects.
        </tp:docstring>
      </arg>
      <arg direction="in" name="parameters" type="a{sv}"
        tp:type="String_Variant_Map">
        <tp:docstring>
          The dictionary of arbitrary
          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube">Parameters</tp:dbus-ref>
          to send with the tube offer.
        </tp:docstring>
      </arg>
      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
          <tp:docstring>
            The contact associated with this channel doesn't have tube
            capabilities.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
          <tp:docstring>
            The connection manager doesn't support the given address type
            or access-control type.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <method name="Accept" tp:name-for-bindings="Accept">
      <tp:docstring>
        Accept a stream tube that's in the "local pending" state. The
        connection manager will attempt to open the tube. The tube remains in
        the "local pending" state until the <tp:dbus-ref
          namespace="org.freedesktop.Telepathy.Channel.Interface.Tube">TubeChannelStateChanged</tp:dbus-ref>
        signal is emitted.
      </tp:docstring>
      <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type">
        <tp:docstring>
          The type of address the connection manager should listen on.
        </tp:docstring>
      </arg>
      <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The type of access control the connection manager should apply to
          the socket.</p>

          <p>Note that if you plan to establish more than one connection
          through the tube, the Socket_Access_Control_Port access control
          can't be used as you can't connect more than once from the same
          port.</p>
        </tp:docstring>
      </arg>
      <arg direction="in" name="access_control_param" type="v">
        <tp:docstring>
          A parameter for the access control type, to be interpreted as
          specified in the documentation for the Socket_Access_Control enum.
        </tp:docstring>
      </arg>
      <arg direction="out" name="address" type="v">
        <tp:docstring>
          The address on which the connection manager will listen for
          connections to this tube. The client should not attempt to connect
          to the address until the tube is open.
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
          <tp:docstring>
            The access_control_param is invalid with the given access_control.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
          <tp:docstring>
            The given address type or access-control mechanism is not supported.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <signal name="NewRemoteConnection"
            tp:name-for-bindings="New_Remote_Connection">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Emitted each time a participant opens a new connection to its
        socket.</p>

        <p>This signal is only fired on the offering side.</p>
      </tp:docstring>
      <arg name="Handle" type="u" tp:type="Contact_Handle">
        <tp:docstring>
          The handle of the participant who opened the new connection
        </tp:docstring>
      </arg>
      <arg name="Connection_Param" type="v">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>A parameter which can be used by the listening process to identify
          the connection. Note that this parameter has a meaningful value
          only in the Socket_Access_Control_Port and
          Socket_Access_Control_Credentials cases. If a different
          Socket_Access_Control has been chosen when offering the tube, this
          parameter should be ignored.</p>

          <p>In the Socket_Access_Control_Port case, the variant
          contains a struct Socket_Address_IPv4 (or Socket_Address_IPv6)
          containing the address from which the CM is connected to the client
          application.</p>

          <p>In the Socket_Access_Control_Credentials case, the variant
          contains the byte (D-Bus signature 'y') that has been sent with
          the credentials.</p>
        </tp:docstring>
      </arg>
      <arg name="Connection_ID" type="u" tp:type="Stream_Tube_Connection_ID">
        <tp:docstring>
          The unique ID associated with this connection. This ID will be used
          to identifiy the connection when reporting errors with
          <tp:member-ref>ConnectionClosed</tp:member-ref>.
        </tp:docstring>
      </arg>
    </signal>

    <signal name="NewLocalConnection"
            tp:name-for-bindings="New_Local_Connection">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Emitted when the tube application connects to the CM's socket.</p>

        <p>This signal is only fired on the accepting side.</p>
      </tp:docstring>
      <arg name="Connection_ID" type="u" tp:type="Stream_Tube_Connection_ID">
        <tp:docstring>
          The unique ID associated with this connection. This ID will be used
          to identifiy the connection when reporting errors with
          <tp:member-ref>ConnectionClosed</tp:member-ref>.
        </tp:docstring>
      </arg>
    </signal>

    <signal name="ConnectionClosed"
            tp:name-for-bindings="Connection_Closed"
            tp:type="Stream_Tube_Connection_Closed">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Emitted when a connection has been closed.</p>
      </tp:docstring>
      <arg name="Connection_ID" type="u" tp:type="Stream_Tube_Connection_ID">
        <tp:docstring>
          The ID of the connection.
        </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 describing the error that occurred.</p>

          <p>The following errors can be used:</p>
          <ul>
            <li><code>org.freedesktop.Telepathy.Error.Cancelled</code>:
               user closed the socket or the tube.</li>
            <li><code>org.freedesktop.Telepathy.Error.ConnectionLost</code>:
               the bytestream relaying connection's data has been broken.</li>
            <li><code>org.freedesktop.Telepathy.Error.ConnectionRefused</code>:
               the tube offer refused the connection.</li>
          </ul>
        </tp:docstring>
      </arg>
      <arg name="Message" type="s">
        <tp:docstring>
          A debug message.
        </tp:docstring>
      </arg>
    </signal>

    <property name="Service" type="s" access="read"
              tp:name-for-bindings="Service">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p> A string representing the service name that will be used over the
          tube.  It should be a well-known TCP service name as defined by
          <a href="http://www.iana.org/assignments/port-numbers">
            http://www.iana.org/assignments/port-numbers</a> or
          <a href="http://www.dns-sd.org/ServiceTypes.html">
            http://www.dns-sd.org/ServiceTypes.html</a>, for instance
          "rsync" or "daap".</p>
        <p>When the tube is offered, the service name is transmitted to the
          other end.</p>
        <p>When requesting a channel with
          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
          this property MUST be included in the request.</p>
      </tp:docstring>
    </property>

    <property name="SupportedSocketTypes" type="a{uau}"
              tp:type="Supported_Socket_Map" access="read"
              tp:name-for-bindings="Supported_Socket_Types">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>A mapping from address types (members of Socket_Address_Type) to
        arrays of access-control type (members of Socket_Access_Control)
        that the connection manager supports for stream tubes with that
        address type. For simplicity, if a CM supports offering a
        particular type of tube, it is assumed to support accepting it.</p>

        <p>A typical value for a host without IPv6 support:</p>

        <pre>
          {
            Socket_Address_Type_IPv4:
              [Socket_Access_Control_Localhost, Socket_Access_Control_Port,
               Socket_Access_Control_Netmask],
            Socket_Address_Type_Unix:
              [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
          }
        </pre>

        <p>Connection Managers MUST support at least IPv4 with the localhost
          access control.</p>

        <p>When requesting a channel with
          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
          this property MUST NOT be included in the request.</p>

      </tp:docstring>
    </property>

    <tp:simple-type name="Stream_Tube_Connection_ID" type="u">
      <tp:docstring>An identifier for a stream tube connection.
        These are defined with the
        <tp:member-ref>NewLocalConnection</tp:member-ref> or
        <tp:member-ref>NewRemoteConnection</tp:member-ref> signals
        and are used by <tp:member-ref>ConnectionClosed</tp:member-ref>
        to identify the closed connection.
        </tp:docstring>
    </tp:simple-type>

  </interface>

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