diff options
Diffstat (limited to 'qt4/spec/Channel_Interface_Tube.xml')
| -rw-r--r-- | qt4/spec/Channel_Interface_Tube.xml | 258 |
1 files changed, 258 insertions, 0 deletions
diff --git a/qt4/spec/Channel_Interface_Tube.xml b/qt4/spec/Channel_Interface_Tube.xml new file mode 100644 index 000000000..858a15dd9 --- /dev/null +++ b/qt4/spec/Channel_Interface_Tube.xml @@ -0,0 +1,258 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2008-2009 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.Interface.Tube"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A <i>tube</i> is a mechanism for arbitrary data transfer between + two or more IM users, used to allow applications on the users' + systems to communicate without having to establish network + connections themselves. Currently, two types of tube exist: + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Channel.Type.DBusTube</tp:dbus-ref> and + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Channel.Type.StreamTube</tp:dbus-ref>. This interface contains + the properties, signals and methods common to both types of tube; + you can only create channels of a specific tube type, not of this + 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 <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 + capability representing each Tube type that they support + (<tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.DBusTube</tp:dbus-ref> and/or + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.StreamTube</tp:dbus-ref>) + even if no client has indicated via + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities">UpdateCapabilities</tp:dbus-ref> + 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">Service</tp:dbus-ref> or + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube">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" + access="read" tp:name-for-bindings="Parameters"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <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, 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>For example, a stream tube for <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube">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.Offer</tp:dbus-ref> + or <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">DBusTube.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> + signal.</p> + </tp:docstring> + </property> + + <property name="State" type="u" tp:type="Tube_Channel_State" access="read" + 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 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> + + <tp:enum name="Tube_Channel_State" type="u"> + <tp:enumvalue suffix="Local_Pending" value="0"> + <tp:docstring> + The initiator offered the tube. The tube is waiting to be + accepted/closed locally. If the client accepts the tube, the tube's + state will be Open. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Remote_Pending" value="1"> + <tp:docstring> + The tube is waiting to be accepted/closed remotely. If the + recipient accepts the tube, the tube's state will be Open. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Open" value="2"> + <tp:docstring> + The initiator offered the tube and the recipient accepted it. The + tube is open for traffic. The tube's state stays in this state until + it is closed. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Not_Offered" value="3"> + <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 used to offer the tube + depends on the tube type. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <signal name="TubeChannelStateChanged" + tp:name-for-bindings="Tube_Channel_State_Changed"> + <tp:docstring> + 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. + </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:deprecated version="0.17.25">This has never been implemented. + If you want to share a service to your whole LAN, Telepathy is + not the way to do it.</tp:deprecated> + <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> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |