summaryrefslogtreecommitdiff
path: root/extensions/Channel_Type_Stream_Tube.xml
blob: 1c721d07554a1fc8a9a924b3000807dc811030a6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
<?xml version="1.0" ?>
<node name="/Channel_Type_Stream_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright>
  <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
  <tp:license>
    This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  </tp:license>
  <interface name="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT"
      tp:causes-havoc="experimental">
    <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
    <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT"/>
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>A stream tube is a transport for ordered, reliable data transfer,
        similar to SOCK_STREAM sockets.</p>

      <p>When offering a stream tube, the initiating client creates a local
        listening socket and offers it to the recipient client using the
        <tp:member-ref>OfferStreamTube</tp:member-ref> method.  When a
        recipient accepts a stream tube using the
        <tp:member-ref>AcceptStreamTube</tp:member-ref> method, the
        recipient's connection manager creates a new local listening socket.
        Each time the recipient's client connects to this socket, the
        initiator's connection manager proxies this connection to the
        originally offered socket.</p>

    </tp:docstring>

    <method name="OfferStreamTube" tp:name-for-bindings="Offer_Stream_Tube">
      <tp:docstring>
        Offer a stream tube exporting the local socket specified.
      </tp:docstring>
      <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type">
        <tp:docstring>
          The type of the listening address of the local service, as a member of
          Socket_Address_Type.
        </tp:docstring>
      </arg>
      <arg direction="in" name="address" type="v">
        <tp:docstring>
          The listening address of the local service, as indicated by the
          address_type.
        </tp:docstring>
      </arg>
      <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
        <tp:docstring>
          The access control the local service applies to the local socket,
          specified so the connection manager can behave appropriately
          when it connects.
        </tp:docstring>
      </arg>
      <arg direction="in" name="access_control_param" type="v">
        <tp:docstring>
          A parameter for the access control type, to be interpreted as
          specified in the documentation for the Socket_Access_Control enum.
        </tp:docstring>
      </arg>
      <arg direction="in" name="parameters" type="a{sv}"
        tp:type="String_Variant_Map">
        <tp:docstring>
          The dictionary of arbitrary
          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT">Parameters</tp:dbus-ref>
          to send with the tube offer.
        </tp:docstring>
      </arg>
      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
          <tp:docstring>
            The contact associated with this channel doesn't have tube
            capabilities.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
          <tp:docstring>
            The connection manager doesn't support the given address type
            or access-control type.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <method name="AcceptStreamTube" tp:name-for-bindings="Accept_Stream_Tube">
      <tp:docstring>
        Accept a stream tube that's in the "local pending" state. The
        connection manager will attempt to open the tube. The tube remains in
        the "local pending" state until the TubeStateChanged signal is
        emitted.
      </tp:docstring>
      <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type">
        <tp:docstring>
          The type of address the connection manager should listen on.
        </tp:docstring>
      </arg>
      <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
        <tp:docstring>
          The type of access control the connection manager should apply to
          the socket.
        </tp:docstring>
      </arg>
      <arg direction="in" name="access_control_param" type="v">
        <tp:docstring>
          A parameter for the access control type, to be interpreted as
          specified in the documentation for the Socket_Access_Control enum.
        </tp:docstring>
      </arg>
      <arg direction="out" name="address" type="v">
        <tp:docstring>
          The address on which the connection manager will listen for
          connections to this tube. The client should not attempt to connect
          to the address until the tube is open.
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
          <tp:docstring>
            The access_control_param is invalid with the given access_control.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
          <tp:docstring>
            The given address type or access-control mechanism is not supported.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <signal name="StreamTubeNewConnection"
            tp:name-for-bindings="Stream_Tube_New_Connection">
      <tp:docstring>
        Emitted on a stream tube when a participant opens a new connection
        to its socket.
      </tp:docstring>
      <arg name="handle" type="u" tp:type="Contact_Handle">
        <tp:docstring>
          The handle of the participant who opened the new connection
        </tp:docstring>
      </arg>
    </signal>

    <property name="Service" type="s" access="read"
              tp:name-for-bindings="Service">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p> A string representing the service name that will be used over the
          tube.  It should be a well-known TCP service name as defined by
          <a href="http://www.iana.org/assignments/port-numbers">
            http://www.iana.org/assignments/port-numbers</a> or
          <a href="http://www.dns-sd.org/ServiceTypes.html">
            http://www.dns-sd.org/ServiceTypes.html</a>, for instance
          "rsync" or "daap".</p>
        <p>When the tube is offered, the service name is transmitted to the
          other end.</p>
        <p>When requesting a channel with
          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
          this property MUST be included in the request.</p>
      </tp:docstring>
    </property>

    <property name="SupportedSocketTypes" type="a{uau}"
              tp:type="Supported_Socket_Map" access="read"
              tp:name-for-bindings="Supported_Socket_Types">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>A mapping from address types (members of Socket_Address_Type) to
        arrays of access-control type (members of Socket_Access_Control)
        that the connection manager supports for stream tubes with that
        address type. For simplicity, if a CM supports offering a
        particular type of tube, it is assumed to support accepting it.</p>

        <p>A typical value for a host without IPv6 support:</p>

        <pre>
          {
            Socket_Address_Type_IPv4:
              [Socket_Access_Control_Localhost, Socket_Access_Control_Port,
               Socket_Access_Control_Netmask],
            Socket_Address_Type_Unix:
              [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
          }
        </pre>

        <p>Connection Managers MUST support at least IPv4 with the localhost
          access control.</p>

        <p>When requesting a channel with
          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
          this property MUST NOT be included in the request.</p>

      </tp:docstring>
    </property>

  </interface>

</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->