<?xml version="1.0" ?>
<node name="/Channel_Type_DBus_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.DBusTube">
    <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 D-Bus tube is an ordered reliable transport, for transporting D-Bus
        traffic.</p>

      <p>For each D-Bus tube, the connection manager listens on a D-Bus
        server address, as detailed in the D-Bus specification. On this
        address, it emulates a bus upon which each tube participant appears
        as an endpoint.</p>

      <p>The objects and interfaces which are expected to exist on the
        emulated bus depend on the well-known name; typically, either the
        participant who initiated the tube is expected to export the same
        objects/interfaces that would be exported by a service of that name
        on a bus, or all participants are expected to export those
        objects/interfaces.</p>

      <p>In a multi-user context (Handle_Type_Room) the tube behaves
        like the D-Bus bus daemon, so participants can send each other
        private messages, or can send broadcast messages which are
        received by everyone in the tube (including themselves).
        Each participant has a D-Bus unique name; connection managers
        MUST prevent participants from sending messages with the wrong
        sender unique name, and SHOULD attempt to avoid participants
        receiving messages not intended for them.</p>

      <p>In a 1-1 context (Handle_Type_Contact) the tube behaves like
        a peer-to-peer D-Bus connection - arbitrary D-Bus messages with
        any sender and/or destination can be sent by each participant,
        and each participant receives all messages sent by the other
        participant.</p>

    </tp:docstring>

    <method name="Offer" tp:name-for-bindings="Offer">
      <tp:docstring>
        Offers a D-Bus tube providing the service specified.
      </tp:docstring>
      <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>
      <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
        <tp:docstring>
          The access control the connection manager applies to the D-Bus socket.
        </tp:docstring>
      </arg>
      <arg direction="out" name="address" type="s">
        <tp:docstring>
          The string describing the address of the private bus. 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.NetworkError"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
          <tp:docstring>
            The contact associated with this channel doesn't have tubes
            capabilities.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <method name="Accept" tp:name-for-bindings="Accept">
      <tp:docstring>
        Accept a D-Bus 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="access_control" type="u" tp:type="Socket_Access_Control">
        <tp:docstring>
          The access control the connection manager applies to the D-Bus socket.
        </tp:docstring>
      </arg>
      <arg direction="out" name="address" type="s">
        <tp:docstring>
          The string describing the address of the private bus. The client
          SHOULD NOT attempt to connect to the address until the tube is open.
        </tp:docstring>
      </arg>
    </method>

    <signal name="DBusNamesChanged" tp:name-for-bindings="DBus_Names_Changed">
      <tp:docstring>
        Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a
        participant opens or closes the tube.  This provides change
        notification for the <tp:member-ref>DBusNames</tp:member-ref> property.
      </tp:docstring>
      <arg name="Added" type="a{us}" tp:type="DBus_Tube_Participants">
        <tp:docstring>
          Array of handles and D-Bus names of new participants.
        </tp:docstring>
      </arg>
      <arg name="Removed" type="au" tp:type="Contact_Handle[]">
        <tp:docstring>
          Array of handles of former participants.
        </tp:docstring>
      </arg>
    </signal>

    <property name="ServiceName" type="s" access="read"
              tp:name-for-bindings="Service_Name"
              tp:requestable="yep"
              tp:immutable="yep">
      <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 D-Bus service name, of the form
          <tt>com.example.ServiceName</tt>.</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="DBusNames" tp:name-for-bindings="DBus_Names"
      access="read" type="a{us}" tp:type="DBus_Tube_Participants">
      <tp:docstring>
        For a multi-user (i.e. Handle_Type_Room) D-Bus tube, a mapping
        between contact handles and their unique bus names on this tube.
        For a peer-to-peer (i.e. Handle_Type_Contact) D-Bus tube, the empty
        dictionary.  Change notification is via
        <tp:member-ref>DBusNamesChanged</tp:member-ref>.
      </tp:docstring>
    </property>

    <tp:mapping name="DBus_Tube_Participants">
      <tp:docstring>Represents the participants in a multi-user D-Bus tube, as
        used by the <tp:member-ref>DBusNames</tp:member-ref> property and the
        <tp:member-ref>DBusNamesChanged</tp:member-ref> signal.</tp:docstring>
      <tp:member type="u" tp:type="Contact_Handle" name="Handle">
        <tp:docstring>
          The handle of a participant in this D-Bus tube.
        </tp:docstring>
      </tp:member>
      <tp:member type="s" tp:type="DBus_Unique_Name" name="Unique_Name">
        <tp:docstring>
          That participant's unique name.
        </tp:docstring>
      </tp:member>
    </tp:mapping>

    <property name="SupportedAccessControls" type="au"
              tp:type="Socket_Access_Control[]" access="read"
              tp:name-for-bindings="Supported_Access_Controls"
              tp:immutable="yep">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>A list of the access control types that are supported with this channel.
        Note that only Socket_Access_Control_Localhost and
        Socket_Access_Control_Credentials can be used with D-Bus tubes.
        Using Socket_Access_Control_Credentials is recommended.</p>

        <tp:rationale>
          <p>Socket_Access_Control_Credentials is easy to implement for a
            D-Bus tube, because typical D-Bus library implementations like
            libdbus and GDBus already have to support it to be able to
            connect to the system or session bus, and usually enable it
            by default; so there's typically no good reason to relax
            access control to Localhost.</p>
        </tp:rationale>

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

  </interface>

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