[telepathy-gabble/master] sync with latest tube DRAFT
Guillaume Desmottes
guillaume.desmottes at collabora.co.uk
Tue May 26 03:18:02 PDT 2009
---
extensions/Channel_Interface_Tube.xml | 182 ++++++++++++++++++++++++------
extensions/Channel_Type_Stream_Tube.xml | 40 ++++++-
2 files changed, 178 insertions(+), 44 deletions(-)
diff --git a/extensions/Channel_Interface_Tube.xml b/extensions/Channel_Interface_Tube.xml
index 7ddfc2b..b661e9f 100644
--- a/extensions/Channel_Interface_Tube.xml
+++ b/extensions/Channel_Interface_Tube.xml
@@ -34,29 +34,30 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
type. A tube channel contains exactly one tube; if you need several
tubes, you have to create several tube channels.</p>
- <p>Tube channels can be requested for handles of type
- HANDLE_TYPE_CONTACT (for 1-1 communication) or of type
- HANDLE_TYPE_ROOM (to communicate with others in the room
- simultaneously).</p>
+ <p>Tube channels can be requested for <tp:type>Handle_Type</tp:type>
+ Contact (for 1-1 communication) or Room (to communicate with others in
+ the room simultaneously).</p>
<p>As an exception to the usual handling of capabilities, connection managers
- for protocols with capability discovery, such as XMPP, SHOULD advertise the
+ for protocols with capability discovery (such as XMPP) SHOULD advertise the
capability representing each Tube type that they support
(<tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.DBusTube.DRAFT</tp:dbus-ref> and/or
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.StreamTube.DRAFT</tp:dbus-ref>)
even if no client has indicated via
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref>
- that such a tube is supported.</p>
-
- <tp:rationale>
- <p>To lower the barrier entry of new tube application, CM SHOULD accept to offer tubes of any
- <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">Service</tp:dbus-ref> or
- <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT">ServiceName</tp:dbus-ref>
- if the contact announced to support tubes.</p>
- </tp:rationale>
+ that such a tube is supported. They SHOULD also allow clients to offer tubes with any
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">Service</tp:dbus-ref> or
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT">ServiceName</tp:dbus-ref>
+ to any contact which supports the corresponding tube capability.</p>
+
+ <tp:rationale>
+ <p>This lowers the barrier to entry for those writing new tube
+ applications, and preserves interoperability with older versions of
+ the Telepathy stack which did not support rich capabilities.</p>
+ </tp:rationale>
</tp:docstring>
<property name="Parameters" type="a{sv}" tp:type="String_Variant_Map"
@@ -65,26 +66,43 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<p>Each tube has a dictionary of arbitrary parameters. Parameters are
commonly used to bootstrap legacy protocols where you can't
negotiate parameters in-band. The allowable keys,
- types and values are defined by the service. Connection managers
- must support the value being a string (D-Bus type 's'), array of bytes
- (D-Bus type 'ay'), unsigned integer (D-Bus type 'u'), integer (D-Bus
- type 'i') and boolean (D-Bus type 'b').</p>
+ types and values are defined by the service, but connection managers
+ must support the value being a string (D-Bus type <tt>'s'</tt>),
+ array of bytes (D-Bus type <tt>'ay'</tt>), unsigned integer (D-Bus
+ type <tt>'u'</tt>), integer (D-Bus type <tt>'i'</tt>) and boolean
+ (D-Bus type <tt>'b'</tt>).</p>
+
<p>When the tube is offered, the parameters are transmitted with the
offer and appear as a property of the incoming tube for other
participants.</p>
- <p>Example of valid parameters for 'smb' Server Message Block over
- TCP/IP (from <a href="http://www.dns-sd.org/ServiceTypes.html">DNS
- SRV (RFC 2782) Service Types
- http://www.dns-sd.org/ServiceTypes.html</a>):
- <code>{'u': 'username', 'p': 'password', 'path': 'path'}</code></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. This property is undefined until the tube is offered
- (using <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">Offer</tp:dbus-ref>
- or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT">Offer</tp:dbus-ref>).
- Once it has been offered, this property MUST NOT change.</p>
+
+ <p>For example, a stream tube for <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">Service</tp:dbus-ref>
+ <tt>"smb"</tt> (<cite>Server Message Block over TCP/IP</cite>) might
+ use the following properties, as defined in <a
+ href="http://www.dns-sd.org/ServiceTypes.html">DNS SRV (RFC 2782)
+ Service Types</a>:</p>
+
+ <pre>
+{ 'u': 'some-username',
+ 'p': 'top-secret-password',
+ 'path': '/etc/passwd',
+}</pre>
+
+ <p>When requesting a tube with
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>,
+ this property MUST NOT be included in the request; instead, it is set
+ when <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamTube.DRAFT.Offer</tp:dbus-ref>
+ or <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">DBusTube.DRAFT.Offer</tp:dbus-ref>
+ (as appropriate) is called. Its value is undefined until the tube is
+ offered; once set, its value MUST NOT change.</p>
+
<p>When receiving an incoming tube, this property is immutable and so advertised in the
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.NewChannels</tp:dbus-ref>
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
signal.</p>
</tp:docstring>
</property>
@@ -93,8 +111,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
tp:name-for-bindings="State">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>State of the tube in this channel.</p>
- <p>When requesting a channel with
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
+
+ <p>When requesting a tube 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>
@@ -124,8 +144,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<tp:docstring>
The tube channel has been requested but the tube is not yet offered.
The client should offer the tube to the recipient and the tube's
- state will be Remote_Pending. The method to offer the tube depend on
- the tube type.
+ state will be Remote_Pending. The method used to offer the tube
+ depends on the tube type.
</tp:docstring>
</tp:enumvalue>
</tp:enum>
@@ -133,15 +153,103 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<signal name="TubeChannelStateChanged"
tp:name-for-bindings="Tube_Channel_State_Changed">
<tp:docstring>
- Emitted when the state of the tube channel changes.
+ Emitted when the state of the tube channel changes. Valid state
+ transitions are documented with <tp:type>Tube_Channel_State</tp:type>.
</tp:docstring>
<arg name="State" type="u" tp:type="Tube_Channel_State">
<tp:docstring>
- The new state of the tube; see the Tube_Channel_State enumeration.
+ The new state of the tube.
</tp:docstring>
</arg>
</signal>
+ <tp:enum name="Socket_Address_Type" type="u">
+ <tp:enumvalue suffix="Unix" value="0">
+ <tp:docstring>
+ A Unix socket. The address variant contains a byte-array, signature 'ay',
+ containing the path of the socket.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Abstract_Unix" value="1">
+ <tp:docstring>
+ An abstract Unix socket. The address variant contains a byte-array,
+ signature 'ay', containing the path of the socket including the
+ leading null byte.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="IPv4" value="2">
+ <tp:docstring>
+ An IPv4 socket. The address variant contains a Socket_Address_IPv4,
+ i.e. a structure with signature (sq)
+ in which the string is an IPv4 dotted-quad address literal
+ (and must not be a DNS name), while the 16-bit unsigned integer is
+ the port number.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="IPv6" value="3">
+ <tp:docstring>
+ An IPv6 socket. The address variant contains a Socket_Address_IPv6,
+ i.e. a structure with signature (sq)
+ in which the string is an IPv6 address literal as specified in
+ RFC2373 (and must not be a DNS name), while the 16-bit unsigned
+ integer is the port number.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ </tp:enum>
+
+ <tp:enum name="Socket_Access_Control" type="u"
+ array-name="Socket_Access_Control_List">
+ <tp:enumvalue suffix="Localhost" value="0">
+ <tp:docstring>
+ The IP or Unix socket can be accessed by any local user (e.g.
+ a Unix socket that accepts all local connections, or an IP socket
+ listening on 127.0.0.1 (or ::1) or rejecting connections not from
+ that address). The associated variant must be ignored.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Port" value="1">
+ <tp:docstring>
+ May only be used on IP sockets. The associated variant must contain
+ a struct Socket_Address_IPv4 (or Socket_Address_IPv6)
+ containing the string form of an IP address of the appropriate
+ version, and a port number. The socket can only be accessed if the
+ connecting process has that address and port number; all other
+ connections will be rejected.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Netmask" value="2">
+ <tp:docstring>
+ May only be used on IP sockets. The associated variant must contain
+ a struct Socket_Netmask_IPv4 (or Socket_Netmask_IPv6) with
+ signature (sy), containing the string form of an
+ IP address of the appropriate version, and a prefix length "n".
+ The socket can only be accessed if the first n bits of the
+ connecting address match the first n bits of the given address.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Credentials" value="3">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>May only be used on UNIX sockets.
+ The connecting process must send a byte when
+ it first connects, which is not considered to be part of the data
+ stream. If the operating system uses sendmsg() with SCM_CREDS or
+ SCM_CREDENTIALS to pass credentials over sockets, the connecting
+ process must do so if possible; if not, it must still send the
+ byte.</p>
+
+ <p>The listening process will disconnect the connection unless it
+ can determine by OS-specific means that the connecting process
+ has the same user ID as the listening process.</p>
+
+ <p>The associated variant must be ignored.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
</interface>
</node>
diff --git a/extensions/Channel_Type_Stream_Tube.xml b/extensions/Channel_Type_Stream_Tube.xml
index eed8faf..0cbd606 100644
--- a/extensions/Channel_Type_Stream_Tube.xml
+++ b/extensions/Channel_Type_Stream_Tube.xml
@@ -89,8 +89,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<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.
+ the "local pending" state until the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT">TubeChannelStateChanged</tp:dbus-ref>
+ signal is emitted.
</tp:docstring>
<arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type">
<tp:docstring>
@@ -152,7 +153,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
the connection. Note that this parameter has a meaningful value
only in the Socket_Access_Control_Port and
Socket_Access_Control_Credentials cases. If a different
- Socket_Access_Control has been choosed when offering the tube, this
+ Socket_Access_Control has been chosen when offering the tube, this
parameter should be ignored.</p>
<p>In the Socket_Access_Control_Port case, the variant
@@ -165,7 +166,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
the credentials.</p>
</tp:docstring>
</arg>
- <arg name="Connection_ID" type="u">
+ <arg name="Connection_ID" type="u" tp:type="Stream_Tube_Connection_ID">
<tp:docstring>
The unique ID associated with this connection. This ID will be used
to identifiy the connection when reporting errors with
@@ -179,7 +180,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Emitted when the tube application connects to CM's socket.</p>
</tp:docstring>
- <arg name="Connection_ID" type="u">
+ <arg name="Connection_ID" type="u" tp:type="Stream_Tube_Connection_ID">
<tp:docstring>
The unique ID associated with this connection. This ID will be used
to identifiy the connection when reporting errors with
@@ -194,14 +195,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Emitted when a connection has been closed.</p>
</tp:docstring>
- <arg name="Connection_ID" type="u">
+ <arg name="Connection_ID" type="u" tp:type="Stream_Tube_Connection_ID">
<tp:docstring>
The ID of the connection.
</tp:docstring>
</arg>
<arg name="Error" type="s" tp:type="DBus_Error_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The name of a D-Bus error describing the error that occurred.</p>
+
+ <p>The following errors can be used:</p>
+ <ul>
+ <li><code>org.freedesktop.Telepathy.Error.Cancelled</code>:
+ user closed the socket or the tube.</li>
+ <li><code>org.freedesktop.Telepathy.Error.ConnectionLost</code>:
+ the bytestream relaying connection's data has been broken.</li>
+ <li><code>org.freedesktop.Telepathy.Error.ConnectionRefused</code>:
+ the tube offer refused the connection.</li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ <arg name="Message" type="s">
<tp:docstring>
- The name of a D-Bus error describing the error that occurred.
+ A debug message.
</tp:docstring>
</arg>
</signal>
@@ -256,6 +272,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:docstring>
</property>
+ <tp:simple-type name="Stream_Tube_Connection_ID" type="u">
+ <tp:docstring>An identifier for a stream tube connection.
+ These are defined with the
+ <tp:member-ref>NewLocalConnection</tp:member-ref> or
+ <tp:member-ref>NewRemoteConnection</tp:member-ref> signals
+ and are used by <tp:member-ref>ConnectionClosed</tp:member-ref>
+ to identify the closed connection.
+ </tp:docstring>
+ </tp:simple-type>
+
</interface>
</node>
--
1.5.6.5
More information about the telepathy-commits
mailing list