extensions/Channel_Type_DBus_Tube.xml

   1 <?xml version="1.0" ?>
   2 <node name="/Channel_Type_DBus_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
   3   <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright>
   4   <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
   5   <tp:license>
   6     This library is free software; you can redistribute it and/or
   7 modify it under the terms of the GNU Lesser General Public
   8 License as published by the Free Software Foundation; either
   9 version 2.1 of the License, or (at your option) any later version.
  10
  11 This library is distributed in the hope that it will be useful,
  12 but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 Lesser General Public License for more details.
  15
  16 You should have received a copy of the GNU Lesser General Public
  17 License along with this library; if not, write to the Free Software
  18 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  19   </tp:license>
  20   <interface name="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT"
  21       tp:causes-havoc="experimental">
  22     <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
  23     <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT"/>
  24     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  25       <p>A D-Bus tube is an ordered reliable transport, for transporting D-Bus
  26         traffic.</p>
  27
  28       <p>For each D-Bus tube, the connection manager listens on a D-Bus
  29         server address, as detailed in the D-Bus specification. On this
  30         address, it emulates a bus upon which each tube participant appears
  31         as an endpoint.</p>
  32
  33       <p>The objects and interfaces which are expected to exist on the
  34         emulated bus depend on the well-known name; typically, either the
  35         participant who initiated the tube is expected to export the same
  36         objects/interfaces that would be exported by a service of that name
  37         on a bus, or all participants are expected to export those
  38         objects/interfaces.</p>
  39
  40       <p>In a multi-user context (Handle_Type_Room) the tube behaves
  41         like the D-Bus bus daemon, so participants can send each other
  42         private messages, or can send broadcast messages which are
  43         received by everyone in the tube (including themselves).
  44         Each participant has a D-Bus unique name; connection managers
  45         MUST prevent participants from sending messages with the wrong
  46         sender unique name, and SHOULD attempt to avoid participants
  47         receiving messages not intended for them.</p>
  48
  49       <p>In a 1-1 context (Handle_Type_Contact) the tube behaves like
  50         a peer-to-peer D-Bus connection - arbitrary D-Bus messages with
  51         any sender and/or destination can be sent by each participant,
  52         and each participant receives all messages sent by the other
  53         participant.</p>
  54
  55     </tp:docstring>
  56
  57     <method name="OfferDBusTube" tp:name-for-bindings="Offer_DBus_Tube">
  58       <tp:docstring>
  59         Offers a D-Bus tube providing the service specified.
  60       </tp:docstring>
  61       <arg direction="in" name="parameters" type="a{sv}"
  62         tp:type="String_Variant_Map">
  63         <tp:docstring>
  64           The dictionary of arbitrary
  65           <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT">Parameters</tp:dbus-ref>
  66           to send with the tube offer.
  67         </tp:docstring>
  68       </arg>
  69       <arg direction="out" name="address" type="s">
  70         <tp:docstring>
  71           The string describing the address of the private bus. The client
  72           SHOULD not attempt to connect to the address until the tube is open.
  73         </tp:docstring>
  74       </arg>
  75       <tp:possible-errors>
  76         <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
  77         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
  78           <tp:docstring>
  79             The contact associated with this channel doesn't have tubes
  80             capabilities.
  81           </tp:docstring>
  82         </tp:error>
  83       </tp:possible-errors>
  84     </method>
  85
  86     <method name="AcceptDBusTube" tp:name-for-bindings="Accept_DBus_Tube">
  87       <tp:docstring>
  88         Accept a D-Bus tube that's in the "local pending" state. The
  89         connection manager will attempt to open the tube. The tube remains in
  90         the "local pending" state until the TubeStateChanged signal is
  91         emitted.
  92       </tp:docstring>
  93       <arg direction="out" name="address" type="s">
  94         <tp:docstring>
  95           The string describing the address of the private bus. The client
  96           SHOULD not attempt to connect to the address until the tube is open.
  97         </tp:docstring>
  98       </arg>
  99     </method>
 100
 101     <signal name="DBusNamesChanged" tp:name-for-bindings="DBus_Names_Changed">
 102       <tp:docstring>
 103         Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a
 104         participant opens or closes the tube.  This provides change
 105         notification for the <tp:member-ref>DBusNames</tp:member-ref> property.
 106       </tp:docstring>
 107       <arg name="added" type="a{us}" tp:type="DBus_Tube_Participants">
 108         <tp:docstring>
 109           Array of handles and D-Bus names of new participants.
 110         </tp:docstring>
 111       </arg>
 112       <arg name="removed" type="au" tp:type="Contact_Handle[]">
 113         <tp:docstring>
 114           Array of handles of former participants.
 115         </tp:docstring>
 116       </arg>
 117     </signal>
 118
 119     <property name="ServiceName" type="s" access="read"
 120               tp:name-for-bindings="Service_Name">
 121       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 122         <p>A string representing the service name that will be used over the
 123           tube. It SHOULD be a well-known D-Bus service name, of the form
 124           com.example.ServiceName.</p>
 125         <p>When the tube is offered, the service name is transmitted to the
 126           other end.</p>
 127         <p>When requesting a channel with
 128           <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
 129           this property MUST be included in the request.</p>
 130       </tp:docstring>
 131     </property>
 132
 133     <property name="DBusNames" tp:name-for-bindings="DBus_Names"
 134       access="read" type="a{us}" tp:type="DBus_Tube_Participants">
 135       <tp:docstring>
 136         For a multi-user (i.e. Handle_Type_Room) D-Bus tube, a mapping
 137         between contact handles and their unique bus names on this tube.
 138         For a peer-to-peer (i.e. Handle_Type_Contact) D-Bus tube, the empty
 139         dictionary.  Change notification is via
 140         <tp:member-ref>DBusNamesChanged</tp:member-ref>.
 141       </tp:docstring>
 142     </property>
 143
 144     <tp:mapping name="DBus_Tube_Participants">
 145       <tp:docstring>Represents the participants in a multi-user D-Bus tube, as
 146         used by the <tp:member-ref>DBusNames</tp:member-ref> property and the
 147         <tp:member-ref>DBusNamesChanged</tp:member-ref> signal.</tp:docstring>
 148       <tp:member type="u" tp:type="Contact_Handle" name="Handle">
 149         <tp:docstring>
 150           The handle of a participant in this D-Bus tube.
 151         </tp:docstring>
 152       </tp:member>
 153       <tp:member type="s" tp:type="DBus_Unique_Name" name="Unique_Name">
 154         <tp:docstring>
 155           That participant's unique name.
 156         </tp:docstring>
 157       </tp:member>
 158     </tp:mapping>
 159
 160   </interface>
 161
 162 </node>
 163 <!-- vim:set sw=2 sts=2 et ft=xml: -->