path: root/spec/Channel_Interface_Tube.xml

<?xml version="1.0" ?>
<node name="/Channel_Interface_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.Interface.Tube">
    <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>A <i>tube</i> is a mechanism for arbitrary data transfer between
      two or more IM users, used to allow applications on the users'
      systems to communicate without having to establish network
      connections themselves. Currently, two types of tube exist:
      <tp:dbus-ref namespace="org.freedesktop.Telepathy"
      >Channel.Type.DBusTube</tp:dbus-ref> and
      <tp:dbus-ref namespace="org.freedesktop.Telepathy"
      >Channel.Type.StreamTube</tp:dbus-ref>. This interface contains
      the properties, signals and methods common to both types of tube;
      you can only create channels of a specific tube type, not of this
      type. A tube channel contains exactly one tube; if you need several
      tubes, you have to create several tube channels.</p>

      <p>Tube channels can be requested for <tp:type>Handle_Type</tp:type>
        Contact (for 1-1 communication) or Room (to communicate with others in
        the room simultaneously).</p>

      <p>As an exception to the usual handling of capabilities, connection managers
        for protocols with capability discovery (such as XMPP) SHOULD advertise the
        capability representing each Tube type that they support
       (<tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.DBusTube</tp:dbus-ref> and/or
        <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.StreamTube</tp:dbus-ref>)
        even if no client has indicated via
        <tp:dbus-ref
          namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities">UpdateCapabilities</tp:dbus-ref>
        that such a tube is supported. They SHOULD also allow clients to offer tubes with any
        <tp:dbus-ref
          namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube">Service</tp:dbus-ref> or
        <tp:dbus-ref
          namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube">ServiceName</tp:dbus-ref>
        to any contact which supports the corresponding tube capability.</p>

      <tp:rationale>
        <p>This lowers the barrier to entry for those writing new tube
          applications, and preserves interoperability with older versions of
          the Telepathy stack which did not support rich capabilities.</p>
      </tp:rationale>
    </tp:docstring>

    <property name="Parameters" type="a{sv}" tp:type="String_Variant_Map"
              access="read" tp:name-for-bindings="Parameters"
              tp:immutable="sometimes">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Each tube has a dictionary of arbitrary parameters. Parameters are
          commonly used to bootstrap legacy protocols where you can't
          negotiate parameters in-band. The allowable keys,
          types and values are defined by the service, but connection managers
          must support the value being a string (D-Bus type <tt>'s'</tt>),
          array of bytes (D-Bus type <tt>'ay'</tt>), unsigned integer (D-Bus
          type <tt>'u'</tt>), integer (D-Bus type <tt>'i'</tt>) and boolean
          (D-Bus type <tt>'b'</tt>).</p>

        <p>When the tube is offered, the parameters are transmitted with the
          offer and appear as a property of the incoming tube for other
          participants.</p>

        <p>For example, a stream tube for <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube">Service</tp:dbus-ref>
          <tt>"smb"</tt> (<cite>Server Message Block over TCP/IP</cite>) might
          use the following properties, as defined in <a
          href="http://www.dns-sd.org/ServiceTypes.html">DNS SRV (RFC 2782)
          Service Types</a>:</p>

        <pre>
{ 'u': 'some-username',
  'p': 'top-secret-password',
  'path': '/etc/passwd',
}</pre>

        <p>When requesting a tube with
          <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>,
          this property MUST NOT be included in the request; instead, it is set
          when <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Channel.Type">StreamTube.Offer</tp:dbus-ref>
          or <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Channel.Type">DBusTube.Offer</tp:dbus-ref>
          (as appropriate) is called. Its value is undefined until the tube is
          offered; once set, its value MUST NOT change.</p>

        <p>When receiving an incoming tube, this property is immutable and so advertised in the
          <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
          signal.</p>
      </tp:docstring>
    </property>

    <property name="State" type="u" tp:type="Tube_Channel_State" access="read"
              tp:name-for-bindings="State">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>State of the tube in this channel.</p>

        <p>When requesting a tube 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:enum name="Tube_Channel_State" type="u">
      <tp:enumvalue suffix="Local_Pending" value="0">
        <tp:docstring>
          The initiator offered the tube. The tube is waiting to be
          accepted/closed locally. If the client accepts the tube, the tube's
          state will be Open.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Remote_Pending" value="1">
        <tp:docstring>
          The tube is waiting to be accepted/closed remotely. If the
          recipient accepts the tube, the tube's state will be Open.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Open" value="2">
        <tp:docstring>
          The initiator offered the tube and the recipient accepted it. The
          tube is open for traffic. The tube's state stays in this state until
          it is closed.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Not_Offered" value="3">
        <tp:docstring>
          The tube channel has been requested but the tube is not yet offered.
          The client should offer the tube to the recipient and the tube's
          state will be Remote_Pending. The method used to offer the tube
          depends on the tube type.
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <signal name="TubeChannelStateChanged"
            tp:name-for-bindings="Tube_Channel_State_Changed">
      <tp:docstring>
        Emitted when the state of the tube channel changes. Valid state
        transitions are documented with <tp:type>Tube_Channel_State</tp:type>.
      </tp:docstring>
      <arg name="State" type="u" tp:type="Tube_Channel_State">
        <tp:docstring>
          The new state of the tube.
        </tp:docstring>
      </arg>
    </signal>

    <tp:enum name="Socket_Address_Type" type="u">
      <tp:enumvalue suffix="Unix" value="0">
        <tp:docstring>
          A Unix socket. The address variant contains a byte-array, signature 'ay',
          containing the path of the socket.
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Abstract_Unix" value="1">
        <tp:docstring>
          An abstract Unix socket. The address variant contains a byte-array,
          signature 'ay', containing the path of the socket including the
          leading null byte.
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="IPv4" value="2">
        <tp:docstring>
          An IPv4 socket. The address variant contains a Socket_Address_IPv4,
          i.e. a structure with signature (sq)
          in which the string is an IPv4 dotted-quad address literal
          (and must not be a DNS name), while the 16-bit unsigned integer is
          the port number.
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="IPv6" value="3">
        <tp:docstring>
          An IPv6 socket. The address variant contains a Socket_Address_IPv6,
          i.e. a structure with signature (sq)
          in which the string is an IPv6 address literal as specified in
          RFC2373 (and must not be a DNS name), while the 16-bit unsigned
          integer is the port number.
        </tp:docstring>
      </tp:enumvalue>

    </tp:enum>

    <tp:enum name="Socket_Access_Control" type="u"
      array-name="Socket_Access_Control_List">
      <tp:enumvalue suffix="Localhost" value="0">
        <tp:docstring>
          <p>The IP or Unix socket can be accessed by any local user (e.g.
            a Unix socket that accepts all local connections, or an IP socket
            listening on 127.0.0.1 (or ::1) or rejecting connections not from
            that address). The associated variant must be ignored.</p>

          <p>For a D-Bus tube, this means that the "same user" access
            control typically provided by default in D-Bus implementations
            SHOULD be disabled. If the socket is only available to local users
            (e.g. a Unix socket, an IPv4 socket bound to 127.0.0.1, or an
            IPv6 socket bound to ::1), the <code>ANONYMOUS</code>
            authentication mechanism MAY be enabled.</p>
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Port" value="1">
        <tp:docstring>
          May only be used on IP sockets, and only for Stream tubes.
          <!-- ... and maybe Datagram tubes, one day... -->
          The associated variant must contain
          a struct Socket_Address_IPv4 (or Socket_Address_IPv6)
          containing the string form of an IP address of the appropriate
          version, and a port number. The socket can only be accessed if the
          connecting process has that address and port number; all other
          connections will be rejected.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Netmask" value="2">
        <tp:deprecated version="0.17.25">This has never been implemented.
        If you want to share a service to your whole LAN, Telepathy is
        not the way to do it.</tp:deprecated>
        <tp:docstring>
          May only be used on IP sockets. The associated variant must contain
          a struct Socket_Netmask_IPv4 (or Socket_Netmask_IPv6) with
          signature (sy), containing the string form of an
          IP address of the appropriate version, and a prefix length "n".
          The socket can only be accessed if the first n bits of the
          connecting address match the first n bits of the given address.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Credentials" value="3">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The high-level meaning of this access control type is that
            only the same user (e.g. same numeric Unix uid) is allowed to
            interact with the tube. Exactly how this is achieved varies by
            channel type.</p>

          <p>For <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type"
              >StreamTube</tp:dbus-ref> channels, this access control type
            may only be used on UNIX sockets.
            The connecting process must send a byte when
            it first connects, which is not considered to be part of the data
            stream. If the operating system uses sendmsg() with SCM_CREDS or
            SCM_CREDENTIALS to pass credentials over sockets, the connecting
            process must do so if possible; if not, it must still send the
            byte, without any attached credentials. (This mechanism is
            very similar to the first byte of a D-Bus connection, except that
            in D-Bus the byte is always zero, whereas in Tubes it can be
            nonzero.)</p>

          <p>For <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type"
              >DBusTube</tp:dbus-ref> channels, this access control type
            may be used on any type of socket, and there is no extra byte
            added by Telepathy at the beginning of the stream: all bytes in
            the stream are part of the D-Bus tube connection. The connecting
            process should prove its identity via any of the SASL
            authentication mechanisms usually used for D-Bus (in typical
            D-Bus implementations this involves either sending and receiving
            credentials as above, or demonstrating the ability to write to a
            file in the user's home directory).</p>

          <p>In either case, the listening process will disconnect the
            connection unless it can determine by OS-specific means that
            the connecting process has the same user ID as the listening
            process.</p>

          <p>In either tube type, the associated variant must be ignored.</p>
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>

  </interface>

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