From 6fe717a264c5270abe9bd37eec90a6024034c389 Mon Sep 17 00:00:00 2001
From: Alban Crequy
Date: Wed, 24 Sep 2008 15:24:58 +0100
Subject: Add the new tube D-Bus API in extensions.
---
extensions/Channel_Interface_Tube.xml | 125 ++++++++++++++++++
extensions/Channel_Type_DBus_Tube.xml | 183 ++++++++++++++++++++++++++
extensions/Channel_Type_Stream_Tube.xml | 219 ++++++++++++++++++++++++++++++++
extensions/Makefile.am | 3 +
extensions/all.xml | 14 +-
5 files changed, 543 insertions(+), 1 deletion(-)
create mode 100644 extensions/Channel_Interface_Tube.xml
create mode 100644 extensions/Channel_Type_DBus_Tube.xml
create mode 100644 extensions/Channel_Type_Stream_Tube.xml
diff --git a/extensions/Channel_Interface_Tube.xml b/extensions/Channel_Interface_Tube.xml
new file mode 100644
index 00000000..d3c4e661
--- /dev/null
+++ b/extensions/Channel_Interface_Tube.xml
@@ -0,0 +1,125 @@
+
+
+ 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. A tube channel
+ can contain only one tube. This interface contains the properties,
+ signals and methods common to all types of tubes. One cannot create a
+ tube channel of type org.freedesktop.Telepathy.Channel.Interface.Tube
+ but only channels of a specific type tube channel. Only stream and
+ D-Bus tubes exist currently. They have their own interface and their
+ interface can be used to create a tube channel.
+
+ The Tubes channel type may be requested for handles of type
+ HANDLE_TYPE_CONTACT and HANDLE_TYPE_ROOM.
+
+
+
+
+ Initiator handle.
+ When requesting a channel with
+ Connection.Interface.Requests.CreateChannel,
+ this property MUST NOT be included in the request.
+
+
+
+
+
+ Each tube has a dictionary of arbitrary parameters. Parameters are
+ commonly used for bootstrap information. 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 to the
+ other end.
+ Example of valid parameters:
+ {'game name': 'go', 'board size': 19}
+ 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 effect.
+
+
+
+
+
+ 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_DBus_Tube.xml b/extensions/Channel_Type_DBus_Tube.xml
new file mode 100644
index 00000000..3846afbe
--- /dev/null
+++ b/extensions/Channel_Type_DBus_Tube.xml
@@ -0,0 +1,183 @@
+
+
+ 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 D-Bus tube is an ordered reliable transport, for transporting D-Bus
+ traffic.
+
+ For each D-Bus tube, the connection manager listens on a D-Bus
+ server address, as detailed in the D-Bus specification. On this
+ address, it emulates a bus upon which each tube participant appears
+ as an endpoint.
+
+ The objects and interfaces which are expected to exist on the
+ emulated bus depend on the well-known name; typically, either the
+ participant who initiated the tube is expected to export the same
+ objects/interfaces that would be exported by a service of that name
+ on a bus, or all participants are expected to export those
+ objects/interfaces.
+
+ In a multi-user context (Handle_Type_Room) the tube behaves
+ like the D-Bus bus daemon, so participants can send each other
+ private messages, or can send broadcast messages which are
+ received by everyone in the tube (including themselves).
+ Each participant has a D-Bus unique name; connection managers
+ must prevent participants from sending messages with the wrong
+ sender unique name, and should attempt to avoid participants
+ receiving messages not intended for them.
+
+ In a 1-1 context (Handle_Type_Contact) the tube behaves like
+ a peer-to-peer D-Bus connection - arbitrary D-Bus messages with
+ any sender and/or destination can be sent by each participant,
+ and each participant receives all messages sent by the other
+ participant.
+
+
+
+
+
+ Offers a D-Bus tube providing the service specified.
+
+
+
+
+
+ The contact associated with this channel doesn't have tubes
+ capabilities.
+
+
+
+
+ The connection manager doesn't support D-Bus tubes.
+
+
+
+
+
+
+
+ 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 string describing the address of the private bus. The client
+ should not attempt to connect to the address until the tube is open.
+
+
+
+
+
+ The given tube ID is invalid or does not refer to a D-Bus
+ tube.
+
+
+
+
+
+
+
+ Return a string describing the address of the private bus.
+
+
+
+ The bus address.
+
+
+
+
+
+ The tube is not a D-Bus tube.
+
+
+
+
+ This tube is not in the "open" state.
+
+
+
+
+
+
+
+ For a multi-user (i.e. Handle_Type_Room) D-Bus tube, obtain a mapping
+ between contact handles and their unique bus names on this tube.
+
+
+
+ An array of structures, each containing a contact handle and a D-Bus
+ bus name.
+
+
+
+
+
+ The tube is not a multi-user D-Bus tube.
+
+
+
+
+ This tube is not in the "open" state.
+
+
+
+
+
+
+
+ Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a
+ participant opens or closes the tube.
+
+
+
+ Array of handles and D-Bus names of new participants.
+
+
+
+
+ Array of handles of former participants.
+
+
+
+
+
+
+ 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.
+ 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.
+
+
+
+
+
+
+
diff --git a/extensions/Channel_Type_Stream_Tube.xml b/extensions/Channel_Type_Stream_Tube.xml
new file mode 100644
index 00000000..f34f441b
--- /dev/null
+++ b/extensions/Channel_Type_Stream_Tube.xml
@@ -0,0 +1,219 @@
+
+
+ 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 accepting a stream tube, a new listening local socket is
+ created. Each time the client connects to this socket, the
+ connection manager of the initiator of the tube opens a new
+ connection to its local socket. Both sides can then use this pair
+ of sockets to communicate together.
+
+
+
+
+
+ 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 stream tubes, or
+ does not 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 given tube ID is invalid or does not refer to a stream
+ tube.
+
+
+
+
+ The given address type or access-control mechanism is not supported.
+
+
+
+
+
+
+
+ For a stream tube, obtain the address of the socket used to
+ communicate over this tube.
+
+
+
+ The type of the listening address of the socket, as a member of
+ Socket_Address_Type.
+
+
+
+
+ The listening address of the socket, as indicated by the
+ address_type.
+
+
+
+
+
+ This tube is not in the "open" state.
+
+
+
+
+
+
+
+ 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]
+ }
+
+
+ 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 a1f7b816..b3bd24b2 100644
--- a/extensions/Makefile.am
+++ b/extensions/Makefile.am
@@ -2,6 +2,9 @@ tools_dir = $(top_srcdir)/tools
EXTRA_DIST = \
Channel_Type_File_Transfer.xml \
+ Channel_Type_Stream_Tube.xml \
+ Channel_Type_DBus_Tube.xml \
+ Channel_Interface_Tube.xml \
channel.xml \
OLPC_Buddy_Info.xml \
OLPC_Activity_Properties.xml \
diff --git a/extensions/all.xml b/extensions/all.xml
index 8a54e2c2..9e9ad6d5 100644
--- a/extensions/all.xml
+++ b/extensions/all.xml
@@ -25,6 +25,10 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+
+
+
+
@@ -38,9 +42,17 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
from="Telepathy specification"/>
+
+
+
+
+
-
--
cgit v1.2.1