Upgrade to latest tube draft
[empathy.git] / 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 © 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.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
42       <p>As an exception to the usual handling of capabilities, connection managers
43         for protocols with capability discovery, such as XMPP, SHOULD advertise the
44         capability representing each Tube type that they support
45        (<tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.DBusTube</tp:dbus-ref> and/or
46         <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.StreamTube</tp:dbus-ref>)
47         even if no client has indicated via
48         <tp:dbus-ref
49           namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref>
50         that such a tube is supported.</p>
51
52         <tp:rationale>
53           <p>To lower the barrier entry of new tube application, CM SHOULD accept to offer tubes of any
54             <tp:dbus-ref
55               namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">Service</tp:dbus-ref> or
56             <tp:dbus-ref
57               namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT">ServiceName</tp:dbus-ref>
58             if the contact announced to support tubes.</p>
59         </tp:rationale>
60     </tp:docstring>
61
62     <property name="Parameters" type="a{sv}" tp:type="String_Variant_Map"
63               access="read" tp:name-for-bindings="Parameters">
64       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
65         <p>Each tube has a dictionary of arbitrary parameters. Parameters are
66           commonly used to bootstrap legacy protocols where you can't
67           negotiate parameters in-band. The allowable keys,
68           types and values are defined by the service. Connection managers
69           must support the value being a string (D-Bus type 's'), array of bytes
70           (D-Bus type 'ay'), unsigned integer (D-Bus type 'u'), integer (D-Bus
71           type 'i') and boolean (D-Bus type 'b').</p>
72         <p>When the tube is offered, the parameters are transmitted with the
73           offer and appear as a property of the incoming tube for other
74           participants.</p>
75         <p>Example of valid parameters for 'smb' Server Message Block over
76           TCP/IP (from <a href="http://www.dns-sd.org/ServiceTypes.html">DNS
77           SRV (RFC 2782) Service Types
78           http://www.dns-sd.org/ServiceTypes.html</a>):
79           <code>{'u': 'username', 'p': 'password', 'path': 'path'}</code></p>
80         <p>When requesting a channel with
81           <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
82           this property MUST NOT be included in the request. This property is undefined until the tube is offered
83           (using <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">OfferStreamTube</tp:dbus-ref>
84           or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT">OfferDBusTube</tp:dbus-ref>).
85           Once it has been offered, this property MUST NOT change.</p>
86         <p>When receiving an incoming tube, this property is immutable and so advertised in the
87           <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.NewChannels</tp:dbus-ref>
88           signal.</p>
89       </tp:docstring>
90     </property>
91
92     <property name="State" type="u" tp:type="Tube_Channel_State" access="read"
93               tp:name-for-bindings="State">
94       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
95         <p>State of the tube in this channel.</p>
96         <p>When requesting a channel with
97           <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
98           this property MUST NOT be included in the request.</p>
99       </tp:docstring>
100     </property>
101
102     <tp:enum name="Tube_Channel_State" type="u">
103       <tp:enumvalue suffix="Local_Pending" value="0">
104         <tp:docstring>
105           The initiator offered the tube. The tube is waiting to be
106           accepted/closed locally. If the client accepts the tube, the tube's
107           state will be Open.
108         </tp:docstring>
109       </tp:enumvalue>
110       <tp:enumvalue suffix="Remote_Pending" value="1">
111         <tp:docstring>
112           The tube is waiting to be accepted/closed remotely. If the
113           recipient accepts the tube, the tube's state will be Open.
114         </tp:docstring>
115       </tp:enumvalue>
116       <tp:enumvalue suffix="Open" value="2">
117         <tp:docstring>
118           The initiator offered the tube and the recipient accepted it. The
119           tube is open for traffic. The tube's state stays in this state until
120           it is closed.
121         </tp:docstring>
122       </tp:enumvalue>
123       <tp:enumvalue suffix="Not_Offered" value="3">
124         <tp:docstring>
125           The tube channel has been requested but the tube is not yet offered.
126           The client should offer the tube to the recipient and the tube's
127           state will be Remote_Pending. The method to offer the tube depend on
128           the tube type.
129         </tp:docstring>
130       </tp:enumvalue>
131     </tp:enum>
132
133     <signal name="TubeChannelStateChanged"
134             tp:name-for-bindings="Tube_Channel_State_Changed">
135       <tp:docstring>
136         Emitted when the state of the tube channel changes.
137       </tp:docstring>
138       <arg name="state" type="u" tp:type="Tube_Channel_State">
139         <tp:docstring>
140           The new state of the tube; see the Tube_Channel_State enumeration.
141         </tp:docstring>
142       </arg>
143     </signal>
144
145   </interface>
146
147 </node>
148 <!-- vim:set sw=2 sts=2 et ft=xml: -->