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 (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.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       <tp:possible-errors>
  70         <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
  71         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
  72           <tp:docstring>
  73             The contact associated with this channel doesn't have tube
  74             capabilities.
  75           </tp:docstring>
  76         </tp:error>
  77         <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
  78           <tp:docstring>
  79             The connection manager doesn't support the given address type
  80             or access-control type.
  81           </tp:docstring>
  82         </tp:error>
  83       </tp:possible-errors>
  84     </method>
  85
  86     <method name="AcceptStreamTube" tp:name-for-bindings="Accept_Stream_Tube">
  87       <tp:docstring>
  88         Accept a stream tube that's in the "local pending" state. The
  89         connection manager will attempt to open the tube. The tube remains in
  90         the "local pending" state until the TubeStateChanged signal is
  91         emitted.
  92       </tp:docstring>
  93       <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type">
  94         <tp:docstring>
  95           The type of address the connection manager should listen on.
  96         </tp:docstring>
  97       </arg>
  98       <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
  99         <tp:docstring>
 100           The type of access control the connection manager should apply to
 101           the socket.
 102         </tp:docstring>
 103       </arg>
 104       <arg direction="in" name="access_control_param" type="v">
 105         <tp:docstring>
 106           A parameter for the access control type, to be interpreted as
 107           specified in the documentation for the Socket_Access_Control enum.
 108         </tp:docstring>
 109       </arg>
 110       <arg direction="out" name="address" type="v">
 111         <tp:docstring>
 112           The address on which the connection manager will listen for
 113           connections to this tube. The client should not attempt to connect
 114           to the address until the tube is open.
 115         </tp:docstring>
 116       </arg>
 117
 118       <tp:possible-errors>
 119         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
 120           <tp:docstring>
 121             The access_control_param is invalid with the given access_control.
 122           </tp:docstring>
 123         </tp:error>
 124         <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
 125           <tp:docstring>
 126             The given address type or access-control mechanism is not supported.
 127           </tp:docstring>
 128         </tp:error>
 129       </tp:possible-errors>
 130     </method>
 131
 132     <signal name="StreamTubeNewConnection"
 133             tp:name-for-bindings="Stream_Tube_New_Connection">
 134       <tp:docstring>
 135         Emitted on a stream tube when a participant opens a new connection
 136         to its socket.
 137       </tp:docstring>
 138       <arg name="handle" type="u" tp:type="Contact_Handle">
 139         <tp:docstring>
 140           The handle of the participant who opened the new connection
 141         </tp:docstring>
 142       </arg>
 143     </signal>
 144
 145     <property name="Service" type="s" access="read"
 146               tp:name-for-bindings="Service">
 147       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 148         <p> A string representing the service name that will be used over the
 149           tube.  It should be a well-known TCP service name as defined by
 150           <a href="http://www.iana.org/assignments/port-numbers">
 151             http://www.iana.org/assignments/port-numbers</a> or
 152           <a href="http://www.dns-sd.org/ServiceTypes.html">
 153             http://www.dns-sd.org/ServiceTypes.html</a>, for instance
 154           "rsync" or "daap".</p>
 155         <p>When the tube is offered, the service name is transmitted to the
 156           other end.</p>
 157         <p>When requesting a channel with
 158           <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
 159           this property MUST be included in the request.</p>
 160       </tp:docstring>
 161     </property>
 162
 163     <property name="SupportedSocketTypes" type="a{uau}"
 164               tp:type="Supported_Socket_Map" access="read"
 165               tp:name-for-bindings="Supported_Socket_Types">
 166       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 167         <p>A mapping from address types (members of Socket_Address_Type) to
 168         arrays of access-control type (members of Socket_Access_Control)
 169         that the connection manager supports for stream tubes with that
 170         address type. For simplicity, if a CM supports offering a
 171         particular type of tube, it is assumed to support accepting it.</p>
 172
 173         <p>A typical value for a host without IPv6 support:</p>
 174
 175         <pre>
 176           {
 177             Socket_Address_Type_IPv4:
 178               [Socket_Access_Control_Localhost, Socket_Access_Control_Port,
 179                Socket_Access_Control_Netmask],
 180             Socket_Address_Type_Unix:
 181               [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
 182           }
 183         </pre>
 184
 185         <p>Connection Managers MUST support at least IPv4 with the localhost
 186           access control.</p>
 187
 188         <p>When requesting a channel with
 189           <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
 190           this property MUST NOT be included in the request.</p>
 191
 192       </tp:docstring>
 193     </property>
 194
 195   </interface>
 196
 197 </node>
 198 <!-- vim:set sw=2 sts=2 et ft=xml: -->