a3b98d7e454abfe76782a09d013ba1388c91ac08
[empathy.git] / 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 (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.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       <tp:possible-errors>
62         <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
63         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
64           <tp:docstring>
65             The contact associated with this channel doesn't have tubes
66             capabilities.
67           </tp:docstring>
68         </tp:error>
69         <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
70           <tp:docstring>
71             The connection manager doesn't support D-Bus tubes.
72           </tp:docstring>
73         </tp:error>
74       </tp:possible-errors>
75     </method>
76
77     <method name="AcceptDBusTube" tp:name-for-bindings="Accept_DBus_Tube">
78       <tp:docstring>
79         Accept a D-Bus tube that's in the "local pending" state. The
80         connection manager will attempt to open the tube. The tube remains in
81         the "local pending" state until the TubeStateChanged signal is
82         emitted.
83       </tp:docstring>
84       <arg direction="out" name="address" type="s">
85         <tp:docstring>
86           The string describing the address of the private bus. The client
87           SHOULD not attempt to connect to the address until the tube is open.
88         </tp:docstring>
89       </arg>
90       <tp:possible-errors>
91         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
92           <tp:docstring>
93             The given tube ID is invalid or does not refer to a D-Bus
94             tube.
95           </tp:docstring>
96         </tp:error>
97       </tp:possible-errors>
98     </method>
99
100     <method name="GetDBusTubeAddress"
101             tp:name-for-bindings="Get_DBus_Tube_Address">
102       <tp:docstring>
103         Return a string describing the address of the private bus.
104       </tp:docstring>
105       <arg direction="out" type="s">
106         <tp:docstring>
107           The bus address.
108         </tp:docstring>
109       </arg>
110       <tp:possible-errors>
111         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
112           <tp:docstring>
113             The tube is not a D-Bus tube.
114           </tp:docstring>
115         </tp:error>
116         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
117           <tp:docstring>
118             This tube is not in the "open" state.
119           </tp:docstring>
120         </tp:error>
121       </tp:possible-errors>
122     </method>
123
124     <method name="GetDBusNames" tp:name-for-bindings="Get_DBus_Names">
125       <tp:docstring>
126         For a multi-user (i.e. Handle_Type_Room) D-Bus tube, obtain a mapping
127         between contact handles and their unique bus names on this tube.
128       </tp:docstring>
129       <arg direction="out" type="a(us)" tp:type="DBus_Tube_Member[]">
130         <tp:docstring>
131           An array of structures, each containing a contact handle and a D-Bus
132           bus name.
133         </tp:docstring>
134       </arg>
135       <tp:possible-errors>
136         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
137           <tp:docstring>
138             The tube is not a multi-user D-Bus tube.
139           </tp:docstring>
140         </tp:error>
141         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
142           <tp:docstring>
143             This tube is not in the "open" state.
144           </tp:docstring>
145         </tp:error>
146       </tp:possible-errors>
147     </method>
148
149     <signal name="DBusNamesChanged" tp:name-for-bindings="DBus_Names_Changed">
150       <tp:docstring>
151         Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a
152         participant opens or closes the tube.
153       </tp:docstring>
154       <arg name="added" type="a(us)" tp:type="DBus_Tube_Member[]">
155         <tp:docstring>
156           Array of handles and D-Bus names of new participants.
157         </tp:docstring>
158       </arg>
159       <arg name="removed" type="au" tp:type="Contact_Handle[]">
160         <tp:docstring>
161           Array of handles of former participants.
162         </tp:docstring>
163       </arg>
164     </signal>
165
166     <property name="ServiceName" type="s" access="read"
167               tp:name-for-bindings="Service_Name">
168       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
169         <p>A string representing the service name that will be used over the
170           tube. It SHOULD be a well-known D-Bus service name, of the form
171           com.example.ServiceName.</p>
172         <p>When the tube is offered, the service name is transmitted to the
173           other end.</p>
174         <p>When requesting a channel with 
175           <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
176           this property MUST be included in the request.</p>
177       </tp:docstring>
178     </property>
179
180   </interface>
181
182 </node>
183 <!-- vim:set sw=2 sts=2 et ft=xml: -->