diff options
author | Guillaume Desmottes <guillaume.desmottes@collabora.co.uk> | 2009-05-27 14:26:16 +0100 |
---|---|---|
committer | Guillaume Desmottes <guillaume.desmottes@collabora.co.uk> | 2009-06-26 10:26:48 +0100 |
commit | f7fa63c667ab2aba39ebf757f16cf64379febb38 (patch) | |
tree | 4b23cb726ce561b0642317f00e3ce170c44eb99a /extensions | |
parent | ba8010f3716dc215004f11335c5ceb2f55bd0457 (diff) | |
download | telepathy-salut-f7fa63c667ab2aba39ebf757f16cf64379febb38.tar.gz |
upgrade to latest tube DRAFT
Diffstat (limited to 'extensions')
-rw-r--r-- | extensions/Channel_Interface_Tube.xml | 184 | ||||
-rw-r--r-- | extensions/Channel_Type_DBus_Tube.xml | 43 | ||||
-rw-r--r-- | extensions/Channel_Type_Stream_Tube.xml | 114 |
3 files changed, 279 insertions, 62 deletions
diff --git a/extensions/Channel_Interface_Tube.xml b/extensions/Channel_Interface_Tube.xml index 36addefd..b661e9ff 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"> + <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_DBus_Tube.xml b/extensions/Channel_Type_DBus_Tube.xml index fe2c949b..64cdcf11 100644 --- a/extensions/Channel_Type_DBus_Tube.xml +++ b/extensions/Channel_Type_DBus_Tube.xml @@ -66,10 +66,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. to send with the tube offer. </tp:docstring> </arg> + <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control"> + <tp:docstring> + The access control the connection manager applies to the D-Bus socket. + </tp:docstring> + </arg> <arg direction="out" name="address" type="s"> <tp:docstring> The string describing the address of the private bus. The client - SHOULD not attempt to connect to the address until the tube is open. + SHOULD NOT attempt to connect to the address until the tube is open. </tp:docstring> </arg> <tp:possible-errors> @@ -87,13 +92,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:docstring> Accept a D-Bus 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="access_control" type="u" tp:type="Socket_Access_Control"> + <tp:docstring> + The access control the connection manager applies to the D-Bus socket. + </tp:docstring> + </arg> <arg direction="out" name="address" type="s"> <tp:docstring> The string describing the address of the private bus. The client - SHOULD not attempt to connect to the address until the tube is open. + SHOULD NOT attempt to connect to the address until the tube is open. </tp:docstring> </arg> </method> @@ -104,12 +115,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. participant opens or closes the tube. This provides change notification for the <tp:member-ref>DBusNames</tp:member-ref> property. </tp:docstring> - <arg name="added" type="a{us}" tp:type="DBus_Tube_Participants"> + <arg name="Added" type="a{us}" tp:type="DBus_Tube_Participants"> <tp:docstring> Array of handles and D-Bus names of new participants. </tp:docstring> </arg> - <arg name="removed" type="au" tp:type="Contact_Handle[]"> + <arg name="Removed" type="au" tp:type="Contact_Handle[]"> <tp:docstring> Array of handles of former participants. </tp:docstring> @@ -121,11 +132,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <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 D-Bus service name, of the form - com.example.ServiceName.</p> + <tt>com.example.ServiceName</tt>.</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>, + <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> @@ -157,6 +169,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:member> </tp:mapping> + <property name="SupportedAccessControls" type="au" + tp:type="Socket_Access_Control[]" access="read" + tp:name-for-bindings="Supported_Access_Controls"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of the access control types that are supported with this channel. + Note that only Socket_Access_Control_Localhost and + Socket_Access_Control_Credentials can be used with D-Bus tubes.</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> diff --git a/extensions/Channel_Type_Stream_Tube.xml b/extensions/Channel_Type_Stream_Tube.xml index a655ece8..0cbd6064 100644 --- a/extensions/Channel_Type_Stream_Tube.xml +++ b/extensions/Channel_Type_Stream_Tube.xml @@ -60,12 +60,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 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> @@ -95,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> @@ -104,9 +99,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </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 xmlns="http://www.w3.org/1999/xhtml"> + <p>The type of access control the connection manager should apply to + the socket.</p> + + <p>Note that if you plan to establish more than one connection + through the tube, the Socket_Access_Control_Port access control + can't be used as you can't connect more than once from the same + port.</p> </tp:docstring> </arg> <arg direction="in" name="access_control_param" type="v"> @@ -137,17 +137,89 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:possible-errors> </method> - <signal name="NewConnection" - tp:name-for-bindings="New_Connection"> + <signal name="NewRemoteConnection" + tp:name-for-bindings="New_Remote_Connection"> <tp:docstring> - Emitted on a stream tube when a participant opens a new connection - to its socket. + Emitted each time a participant opens a new connection to its socket. </tp:docstring> - <arg name="handle" type="u" tp:type="Contact_Handle"> + <arg name="Handle" type="u" tp:type="Contact_Handle"> <tp:docstring> The handle of the participant who opened the new connection </tp:docstring> </arg> + <arg name="Connection_Param" type="v"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A parameter which can be used by the listening process to identify + 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 chosen when offering the tube, this + parameter should be ignored.</p> + + <p>In the Socket_Access_Control_Port case, the variant + contains a struct Socket_Address_IPv4 (or Socket_Address_IPv6) + containing the address from which the CM is connected to the client + application.</p> + + <p>In the Socket_Access_Control_Credentials case, the variant + contains the byte (D-Bus signature 'y') that has been sent with + the credentials.</p> + </tp:docstring> + </arg> + <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 + <tp:member-ref>ConnectionClosed</tp:member-ref>. + </tp:docstring> + </arg> + </signal> + + <signal name="NewLocalConnection" + tp:name-for-bindings="New_Local_Connection"> + <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" 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 + <tp:member-ref>ConnectionClosed</tp:member-ref>. + </tp:docstring> + </arg> + </signal> + + <signal name="ConnectionClosed" + tp:name-for-bindings="Connection_Closed" + tp:type="Stream_Tube_Connection_Closed"> + <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" 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> + A debug message. + </tp:docstring> + </arg> </signal> <property name="Service" type="s" access="read" @@ -200,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> |