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: -->