Upgrade to latest tube draft
[empathy.git] / extensions / Channel_Type_Stream_Tube.xml
1 <?xml version="1.0" ?>
2 <node name="/Channel_Type_Stream_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.StreamTube.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 stream tube is a transport for ordered, reliable data transfer,
26         similar to SOCK_STREAM sockets.</p>
27
28       <p>When offering a stream tube, the initiating client creates a local
29         listening socket and offers it to the recipient client using the
30         <tp:member-ref>OfferStreamTube</tp:member-ref> method.  When a
31         recipient accepts a stream tube using the
32         <tp:member-ref>AcceptStreamTube</tp:member-ref> method, the
33         recipient's connection manager creates a new local listening socket.
34         Each time the recipient's client connects to this socket, the
35         initiator's connection manager proxies this connection to the
36         originally offered socket.</p>
37
38     </tp:docstring>
39
40     <method name="OfferStreamTube" tp:name-for-bindings="Offer_Stream_Tube">
41       <tp:docstring>
42         Offer a stream tube exporting the local socket specified.
43       </tp:docstring>
44       <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type">
45         <tp:docstring>
46           The type of the listening address of the local service, as a member of
47           Socket_Address_Type.
48         </tp:docstring>
49       </arg>
50       <arg direction="in" name="address" type="v">
51         <tp:docstring>
52           The listening address of the local service, as indicated by the
53           address_type.
54         </tp:docstring>
55       </arg>
56       <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
57         <tp:docstring>
58           The access control the local service applies to the local socket,
59           specified so the connection manager can behave appropriately
60           when it connects.
61         </tp:docstring>
62       </arg>
63       <arg direction="in" name="access_control_param" type="v">
64         <tp:docstring>
65           A parameter for the access control type, to be interpreted as
66           specified in the documentation for the Socket_Access_Control enum.
67         </tp:docstring>
68       </arg>
69       <arg direction="in" name="parameters" type="a{sv}"
70         tp:type="String_Variant_Map">
71         <tp:docstring>
72           The dictionary of arbitrary
73           <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT">Parameters</tp:dbus-ref>
74           to send with the tube offer.
75         </tp:docstring>
76       </arg>
77       <tp:possible-errors>
78         <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
79         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
80           <tp:docstring>
81             The contact associated with this channel doesn't have tube
82             capabilities.
83           </tp:docstring>
84         </tp:error>
85         <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
86           <tp:docstring>
87             The connection manager doesn't support the given address type
88             or access-control type.
89           </tp:docstring>
90         </tp:error>
91       </tp:possible-errors>
92     </method>
93
94     <method name="AcceptStreamTube" tp:name-for-bindings="Accept_Stream_Tube">
95       <tp:docstring>
96         Accept a stream tube that's in the "local pending" state. The
97         connection manager will attempt to open the tube. The tube remains in
98         the "local pending" state until the TubeStateChanged signal is
99         emitted.
100       </tp:docstring>
101       <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type">
102         <tp:docstring>
103           The type of address the connection manager should listen on.
104         </tp:docstring>
105       </arg>
106       <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
107         <tp:docstring>
108           The type of access control the connection manager should apply to
109           the socket.
110         </tp:docstring>
111       </arg>
112       <arg direction="in" name="access_control_param" type="v">
113         <tp:docstring>
114           A parameter for the access control type, to be interpreted as
115           specified in the documentation for the Socket_Access_Control enum.
116         </tp:docstring>
117       </arg>
118       <arg direction="out" name="address" type="v">
119         <tp:docstring>
120           The address on which the connection manager will listen for
121           connections to this tube. The client should not attempt to connect
122           to the address until the tube is open.
123         </tp:docstring>
124       </arg>
125
126       <tp:possible-errors>
127         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
128           <tp:docstring>
129             The access_control_param is invalid with the given access_control.
130           </tp:docstring>
131         </tp:error>
132         <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
133           <tp:docstring>
134             The given address type or access-control mechanism is not supported.
135           </tp:docstring>
136         </tp:error>
137       </tp:possible-errors>
138     </method>
139
140     <signal name="StreamTubeNewConnection"
141             tp:name-for-bindings="Stream_Tube_New_Connection">
142       <tp:docstring>
143         Emitted on a stream tube when a participant opens a new connection
144         to its socket.
145       </tp:docstring>
146       <arg name="handle" type="u" tp:type="Contact_Handle">
147         <tp:docstring>
148           The handle of the participant who opened the new connection
149         </tp:docstring>
150       </arg>
151     </signal>
152
153     <property name="Service" type="s" access="read"
154               tp:name-for-bindings="Service">
155       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
156         <p> A string representing the service name that will be used over the
157           tube.  It should be a well-known TCP service name as defined by
158           <a href="http://www.iana.org/assignments/port-numbers">
159             http://www.iana.org/assignments/port-numbers</a> or
160           <a href="http://www.dns-sd.org/ServiceTypes.html">
161             http://www.dns-sd.org/ServiceTypes.html</a>, for instance
162           "rsync" or "daap".</p>
163         <p>When the tube is offered, the service name is transmitted to the
164           other end.</p>
165         <p>When requesting a channel with
166           <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
167           this property MUST be included in the request.</p>
168       </tp:docstring>
169     </property>
170
171     <property name="SupportedSocketTypes" type="a{uau}"
172               tp:type="Supported_Socket_Map" access="read"
173               tp:name-for-bindings="Supported_Socket_Types">
174       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
175         <p>A mapping from address types (members of Socket_Address_Type) to
176         arrays of access-control type (members of Socket_Access_Control)
177         that the connection manager supports for stream tubes with that
178         address type. For simplicity, if a CM supports offering a
179         particular type of tube, it is assumed to support accepting it.</p>
180
181         <p>A typical value for a host without IPv6 support:</p>
182
183         <pre>
184           {
185             Socket_Address_Type_IPv4:
186               [Socket_Access_Control_Localhost, Socket_Access_Control_Port,
187                Socket_Access_Control_Netmask],
188             Socket_Address_Type_Unix:
189               [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
190           }
191         </pre>
192
193         <p>Connection Managers MUST support at least IPv4 with the localhost
194           access control.</p>
195
196         <p>When requesting a channel with
197           <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
198           this property MUST NOT be included in the request.</p>
199
200       </tp:docstring>
201     </property>
202
203   </interface>
204
205 </node>
206 <!-- vim:set sw=2 sts=2 et ft=xml: -->