extensions/Channel_Interface_Tube.xml

   1 <?xml version="1.0" ?>
   2 <node name="/Channel_Interface_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
   3   <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright>
   4   <tp:copyright>Copyright (C) 2008 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.Interface.Tube.DRAFT"
  21       tp:causes-havoc="experimental">
  22     <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
  23     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  24       <p>A <i>tube</i> is a mechanism for arbitrary data transfer between
  25       two or more IM users, used to allow applications on the users'
  26       systems to communicate without having to establish network
  27       connections themselves. Currently, two types of tube exist:
  28       <tp:dbus-ref namespace="org.freedesktop.Telepathy"
  29       >Channel.Type.DBusTube</tp:dbus-ref> and
  30       <tp:dbus-ref namespace="org.freedesktop.Telepathy"
  31       >Channel.Type.StreamTube</tp:dbus-ref>. This interface contains
  32       the properties, signals and methods common to both types of tube;
  33       you can only create channels of a specific tube type, not of this
  34       type. A tube channel contains exactly one tube; if you need several
  35       tubes, you have to create several tube channels.</p>
  36
  37       <p>Tube channels can be requested for handles of type
  38       HANDLE_TYPE_CONTACT (for 1-1 communication) or of type
  39       HANDLE_TYPE_ROOM (to communicate with others in the room
  40       simultaneously).</p>
  41     </tp:docstring>
  42
  43     <property name="Parameters" type="a{sv}" tp:type="String_Variant_Map"
  44               access="readwrite" tp:name-for-bindings="Parameters">
  45       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  46         <p>Each tube has a dictionary of arbitrary parameters. Parameters are
  47           commonly used to bootstrap legacy protocols where you can't
  48           negotiate parameters in-band. The allowable keys,
  49           types and values are defined by the service. Connection managers
  50           must support the value being a string (D-Bus type 's'), array of bytes
  51           (D-Bus type 'ay'), unsigned integer (D-Bus type 'u'), integer (D-Bus
  52           type 'i') and boolean (D-Bus type 'b').</p>
  53         <p>When the tube is offered, the parameters are transmitted with the
  54           offer and appear as a property of the incoming tube for other
  55           participants.</p>
  56         <p>Example of valid parameters for 'smb' Server Message Block over
  57           TCP/IP (from <a href="http://www.dns-sd.org/ServiceTypes.html">DNS
  58           SRV (RFC 2782) Service Types
  59           http://www.dns-sd.org/ServiceTypes.html</a>):
  60           <code>{'u': 'username', 'p': 'password', 'path': 'path'}</code></p>
  61         <p>When requesting a channel with
  62           <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
  63           this property MAY be included in the request. If it is not included in
  64           the request, the connection manager MUST consider the property to be
  65           empty. This property MAY be changed after the channel creation when
  66           the tube is in the state Not_Offered. If the tube is in another
  67           state, changing this property MUST fail without side effects.</p>
  68       </tp:docstring>
  69     </property>
  70
  71     <property name="Status" type="u" tp:type="Tube_Channel_State" access="read"
  72               tp:name-for-bindings="Status">
  73       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  74         <p>Status of the tube in this channel.</p>
  75         <p>When requesting a channel with
  76           <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
  77           this property MUST NOT be included in the request.</p>
  78       </tp:docstring>
  79     </property>
  80
  81     <tp:enum name="Tube_Channel_State" type="u">
  82       <tp:enumvalue suffix="Local_Pending" value="0">
  83         <tp:docstring>
  84           The initiator offered the tube. The tube is waiting to be
  85           accepted/closed locally. If the client accepts the tube, the tube's
  86           state will be Open.
  87         </tp:docstring>
  88       </tp:enumvalue>
  89       <tp:enumvalue suffix="Remote_Pending" value="1">
  90         <tp:docstring>
  91           The tube is waiting to be accepted/closed remotely. If the
  92           recipient accepts the tube, the tube's state will be Open.
  93         </tp:docstring>
  94       </tp:enumvalue>
  95       <tp:enumvalue suffix="Open" value="2">
  96         <tp:docstring>
  97           The initiator offered the tube and the recipient accepted it. The
  98           tube is open for traffic. The tube's state stays in this state until
  99           it is closed.
 100         </tp:docstring>
 101       </tp:enumvalue>
 102       <tp:enumvalue suffix="Not_Offered" value="3">
 103         <tp:docstring>
 104           The tube channel has been requested but the tube is not yet offered.
 105           The client should offer the tube to the recipient and the tube's
 106           state will be Remote_Pending. The method to offer the tube depend on
 107           the tube type.
 108         </tp:docstring>
 109       </tp:enumvalue>
 110     </tp:enum>
 111
 112     <signal name="TubeChannelStateChanged"
 113             tp:name-for-bindings="Tube_Channel_State_Changed">
 114       <tp:docstring>
 115         Emitted when the state of the tube channel changes.
 116       </tp:docstring>
 117       <arg name="state" type="u" tp:type="Tube_Channel_State">
 118         <tp:docstring>
 119           The new state of the tube; see the Tube_Channel_State enumeration.
 120         </tp:docstring>
 121       </arg>
 122     </signal>
 123
 124   </interface>
 125
 126 </node>
 127 <!-- vim:set sw=2 sts=2 et ft=xml: -->