From 3a9f3eaf06428d65c33a52a3371284e575472acd Mon Sep 17 00:00:00 2001 From: Sjoerd Simons Date: Fri, 9 Jan 2009 16:13:22 +0000 Subject: Add new StreamTube spec Signed-off-by: Sjoerd Simons svn path=/trunk/; revision=2150 --- extensions/Channel_Interface_Tube.xml | 127 ++++++++++++++++++++ extensions/Channel_Type_Stream_Tube.xml | 198 ++++++++++++++++++++++++++++++++ extensions/Makefile.am | 5 +- extensions/all.xml | 2 + extensions/generic-types.xml | 100 ++++++++++++++++ extensions/misc.xml | 2 + 6 files changed, 433 insertions(+), 1 deletion(-) create mode 100644 extensions/Channel_Interface_Tube.xml create mode 100644 extensions/Channel_Type_Stream_Tube.xml create mode 100644 extensions/generic-types.xml diff --git a/extensions/Channel_Interface_Tube.xml b/extensions/Channel_Interface_Tube.xml new file mode 100644 index 000000000..8e1ffab3a --- /dev/null +++ b/extensions/Channel_Interface_Tube.xml @@ -0,0 +1,127 @@ + + + Copyright (C) 2008 Collabora Limited + Copyright (C) 2008 Nokia Corporation + + 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. + + + + +

A tube 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: + Channel.Type.DBusTube and + Channel.Type.StreamTube. 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.

+ +

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).

+ + + + +

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').

+

When the tube is offered, the parameters are transmitted with the + offer and appear as a property of the incoming tube for other + participants.

+

Example of valid parameters for 'smb' Server Message Block over + TCP/IP (from DNS + SRV (RFC 2782) Service Types + http://www.dns-sd.org/ServiceTypes.html): + {'u': 'username', 'p': 'password', 'path': 'path'}

+

When requesting a channel with + Connection.Interface.Requests.CreateChannel, + this property MAY be included in the request. If it is not included in + the request, the connection manager MUST consider the property to be + empty. This property MAY be changed after the channel creation when + the tube is in the state Not_Offered. If the tube is in another + state, changing this property MUST fail without side effects.

+ + + + + +

Status of the tube in this channel.

+

When requesting a channel with + Connection.Interface.Requests.CreateChannel, + this property MUST NOT be included in the request.

+ + + + + + + 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. + + + + + The tube is waiting to be accepted/closed remotely. If the + recipient accepts the tube, the tube's state will be Open. + + + + + 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. + + + + + 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. + + + + + + + Emitted when the state of the tube channel changes. + + + + The new state of the tube; see the Tube_Channel_State enumeration. + + + + + + + + diff --git a/extensions/Channel_Type_Stream_Tube.xml b/extensions/Channel_Type_Stream_Tube.xml new file mode 100644 index 000000000..4a43a0074 --- /dev/null +++ b/extensions/Channel_Type_Stream_Tube.xml @@ -0,0 +1,198 @@ + + + Copyright (C) 2008 Collabora Limited + Copyright (C) 2008 Nokia Corporation + + 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. + + + + + +

A stream tube is a transport for ordered, reliable data transfer, + similar to SOCK_STREAM sockets.

+ +

When offering a stream tube, the initiating client creates a local + listening socket and offers it to the recipient client using the + OfferStreamTube method. When a + recipient accepts a stream tube using the + AcceptStreamTube 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.

+ + + + + + Offer a stream tube exporting the local socket specified. + + + + The type of the listening address of the local service, as a member of + Socket_Address_Type. + + + + + The listening address of the local service, as indicated by the + address_type. + + + + + The access control the local service applies to the local socket, + specified so the connection manager can behave appropriately + when it connects. + + + + + A parameter for the access control type, to be interpreted as + specified in the documentation for the Socket_Access_Control enum. + + + + + + + The contact associated with this channel doesn't have tube + capabilities. + + + + + The connection manager doesn't support the given address type + or access-control type. + + + + + + + + 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 type of address the connection manager should listen on. + + + + + The type of access control the connection manager should apply to + the socket. + + + + + A parameter for the access control type, to be interpreted as + specified in the documentation for the Socket_Access_Control enum. + + + + + 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. + + + + + + + The access_control_param is invalid with the given access_control. + + + + + The given address type or access-control mechanism is not supported. + + + + + + + + Emitted on a stream tube when a participant opens a new connection + to its socket. + + + + The handle of the participant who opened the new connection + + + + + + +

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 + + http://www.iana.org/assignments/port-numbers or + + http://www.dns-sd.org/ServiceTypes.html, for instance + "rsync" or "daap".

+

When the tube is offered, the service name is transmitted to the + other end.

+

When requesting a channel with + Connection.Interface.Requests.CreateChannel, + this property MUST be included in the request.

+ + + + + +

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.

+ +

A typical value for a host without IPv6 support:

+ + 
+          {
+            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]
+          }
+
+ +

Connection Managers MUST support at least IPv4 with the localhost + access control.

+ +

When requesting a channel with + Connection.Interface.Requests.CreateChannel, + this property MUST NOT be included in the request.

+ + + + + + + + diff --git a/extensions/Makefile.am b/extensions/Makefile.am index 5cf70620e..974fe0b6f 100644 --- a/extensions/Makefile.am +++ b/extensions/Makefile.am @@ -8,11 +8,14 @@ AM_CFLAGS = \ EXTRA_DIST = \ all.xml \ + generic-types.xml \ misc.xml \ Channel_Handler.xml \ Stream_Engine.xml \ Tube_Handler.xml \ - Channel_Type_File_Transfer.xml + Channel_Type_File_Transfer.xml \ + Channel_Interface_Tube.xml \ + Channel_Type_Stream_Tube.xml noinst_LTLIBRARIES = libemp-extensions.la diff --git a/extensions/all.xml b/extensions/all.xml index 5e6ecce27..c9f4c0bd7 100644 --- a/extensions/all.xml +++ b/extensions/all.xml @@ -5,6 +5,7 @@ Extensions for empathy + + diff --git a/extensions/generic-types.xml b/extensions/generic-types.xml new file mode 100644 index 000000000..227fde148 --- /dev/null +++ b/extensions/generic-types.xml @@ -0,0 +1,100 @@ + + + + An unsigned 32-bit integer representing time as the number + of seconds elapsed since the Unix epoch + (1970-01-01T00:00:00Z) + + + + An unsigned 64-bit integer representing time as the number + of seconds elapsed since the Unix epoch + (1970-01-01T00:00:00Z) + + The Text interface is the only user of Unix_Timestamp so + far, and we'd like to be Y2038 compatible in future + interfaces. + + + + A string representing a D-Bus bus name - either a well-known + name like "org.freedesktop.Telepathy.MissionControl" or a unique name + like ":1.123" + + + + A string representing a D-Bus well-known + name like "org.freedesktop.Telepathy.MissionControl". + + + + A string representing a D-Bus unique name, such as + ":1.123" + + + + An ASCII string representing a D-Bus interface - two or more + elements separated by dots, where each element is a non-empty + string of ASCII letters, digits and underscores, not starting with + a digit. The maximum total length is 255 characters. For example, + "org.freedesktop.DBus.Peer". + + + + An ASCII string representing a D-Bus error. This is + syntactically the same as a DBus_Interface, but the + meaning is different. + + + + A string representing a D-Bus signature + (the 'g' type isn't used because of poor interoperability, particularly + with dbus-glib) + + + + An ASCII string representing a D-Bus method, signal + or property name - a non-empty string of ASCII letters, digits and + underscores, not starting with a digit, with a maximum length of 255 + characters. For example, "Ping". + + + + A string representing the full name of a D-Bus method, + signal or property, consisting of a DBus_Interface, followed by + a dot, followed by a DBus_Member. For example, + "org.freedesktop.DBus.Peer.Ping". + + + + A mapping from strings representing D-Bus + properties (by their namespaced names) to their values. + + + A D-Bus interface name, followed by a dot and a D-Bus property name. + + + + + The value of the property. + + + + + + A mapping from strings to variants representing extra + key-value pairs. + + + + + + A mapping from strings to strings representing extra + key-value pairs. + + + + + diff --git a/extensions/misc.xml b/extensions/misc.xml index 3182d4f13..84dd57fc9 100644 --- a/extensions/misc.xml +++ b/extensions/misc.xml @@ -8,5 +8,7 @@ + + -- cgit v1.2.3