empathy r2150 - trunk/extensions
- From: xclaesse svn gnome org
- To: svn-commits-list gnome org
- Subject: empathy r2150 - trunk/extensions
- Date: Fri, 9 Jan 2009 16:13:22 +0000 (UTC)
Author: xclaesse
Date: Fri Jan 9 16:13:22 2009
New Revision: 2150
URL: http://svn.gnome.org/viewvc/empathy?rev=2150&view=rev
Log:
Add new StreamTube spec
Signed-off-by: Sjoerd Simons <sjoerd simons collabora co uk>
Added:
trunk/extensions/Channel_Interface_Tube.xml
trunk/extensions/Channel_Type_Stream_Tube.xml
trunk/extensions/generic-types.xml
Modified:
trunk/extensions/Makefile.am
trunk/extensions/all.xml
trunk/extensions/misc.xml
Added: trunk/extensions/Channel_Interface_Tube.xml
==============================================================================
--- (empty file)
+++ trunk/extensions/Channel_Interface_Tube.xml Fri Jan 9 16:13:22 2009
@@ -0,0 +1,127 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0";>
+ <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright (C) 2008 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.DRAFT"
+ tp:causes-havoc="experimental">
+ <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 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>
+ </tp:docstring>
+
+ <property name="Parameters" type="a{sv}" tp:type="String_Variant_Map"
+ access="readwrite" 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. 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>
+ <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 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.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="Status" type="u" tp:type="Tube_Channel_State" access="read"
+ tp:name-for-bindings="Status">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml";>
+ <p>Status 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>,
+ 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 to offer the tube depend 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.
+ </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.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ </interface>
+
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
Added: trunk/extensions/Channel_Type_Stream_Tube.xml
==============================================================================
--- (empty file)
+++ trunk/extensions/Channel_Type_Stream_Tube.xml Fri Jan 9 16:13:22 2009
@@ -0,0 +1,198 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Type_Stream_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0";>
+ <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright (C) 2008 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.Type.StreamTube.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml";>
+ <p>A stream tube is a transport for ordered, reliable data transfer,
+ similar to SOCK_STREAM sockets.</p>
+
+ <p>When offering a stream tube, the initiating client creates a local
+ listening socket and offers it to the recipient client using the
+ <tp:member-ref>OfferStreamTube</tp:member-ref> method. When a
+ recipient accepts a stream tube using the
+ <tp:member-ref>AcceptStreamTube</tp:member-ref> 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.</p>
+
+ </tp:docstring>
+
+ <method name="OfferStreamTube" tp:name-for-bindings="Offer_Stream_Tube">
+ <tp:docstring>
+ Offer a stream tube exporting the local socket specified.
+ </tp:docstring>
+ <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type">
+ <tp:docstring>
+ The type of the listening address of the local service, as a member of
+ Socket_Address_Type.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="address" type="v">
+ <tp:docstring>
+ The listening address of the local service, as indicated by the
+ address_type.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
+ <tp:docstring>
+ The access control the local service applies to the local socket,
+ specified so the connection manager can behave appropriately
+ 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>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The contact associated with this channel doesn't have tube
+ capabilities.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The connection manager doesn't support the given address type
+ or access-control type.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="AcceptStreamTube" tp:name-for-bindings="Accept_Stream_Tube">
+ <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.
+ </tp:docstring>
+ <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type">
+ <tp:docstring>
+ The type of address the connection manager should listen on.
+ </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>
+ </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="out" name="address" type="v">
+ <tp:docstring>
+ 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.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The access_control_param is invalid with the given access_control.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The given address type or access-control mechanism is not supported.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="StreamTubeNewConnection"
+ tp:name-for-bindings="Stream_Tube_New_Connection">
+ <tp:docstring>
+ Emitted on a stream tube when a participant opens a new connection
+ to its socket.
+ </tp:docstring>
+ <arg name="handle" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The handle of the participant who opened the new connection
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="Service" type="s" access="read"
+ tp:name-for-bindings="Service">
+ <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 TCP service name as defined by
+ <a href="http://www.iana.org/assignments/port-numbers";>
+ http://www.iana.org/assignments/port-numbers</a> or
+ <a href="http://www.dns-sd.org/ServiceTypes.html";>
+ http://www.dns-sd.org/ServiceTypes.html</a>, for instance
+ "rsync" or "daap".</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>,
+ this property MUST be included in the request.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="SupportedSocketTypes" type="a{uau}"
+ tp:type="Supported_Socket_Map" access="read"
+ tp:name-for-bindings="Supported_Socket_Types">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml";>
+ <p>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.</p>
+
+ <p>A typical value for a host without IPv6 support:</p>
+
+ <pre>
+ {
+ 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]
+ }
+ </pre>
+
+ <p>Connection Managers MUST support at least IPv4 with the localhost
+ access control.</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>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
Modified: trunk/extensions/Makefile.am
==============================================================================
--- trunk/extensions/Makefile.am (original)
+++ trunk/extensions/Makefile.am Fri Jan 9 16:13:22 2009
@@ -8,11 +8,14 @@
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
Modified: trunk/extensions/all.xml
==============================================================================
--- trunk/extensions/all.xml (original)
+++ trunk/extensions/all.xml Fri Jan 9 16:13:22 2009
@@ -5,6 +5,7 @@
<tp:title>Extensions for empathy</tp:title>
<xi:include href="misc.xml"/>
+<xi:include href="generic-types.xml"/>
<tp:generic-types>
<tp:external-type name="Contact_Handle" type="u"
@@ -29,4 +30,5 @@
from="Telepathy specification"/>
</tp:generic-types>
+
</tp:spec>
Added: trunk/extensions/generic-types.xml
==============================================================================
--- (empty file)
+++ trunk/extensions/generic-types.xml Fri Jan 9 16:13:22 2009
@@ -0,0 +1,100 @@
+<tp:generic-types
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0";>
+
+ <tp:simple-type name="Unix_Timestamp" type="u">
+ <tp:docstring>An unsigned 32-bit integer representing time as the number
+ of seconds elapsed since the Unix epoch
+ (1970-01-01T00:00:00Z)</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="Unix_Timestamp64" type="t">
+ <tp:docstring>An unsigned 64-bit integer representing time as the number
+ of seconds elapsed since the Unix epoch
+ (1970-01-01T00:00:00Z)</tp:docstring>
+
+ <tp:rationale>The Text interface is the only user of Unix_Timestamp so
+ far, and we'd like to be Y2038 compatible in future
+ interfaces.</tp:rationale>
+ </tp:simple-type>
+
+ <tp:simple-type name="DBus_Bus_Name" type="s">
+ <tp:docstring>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"</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="DBus_Well_Known_Name" type="s">
+ <tp:docstring>A string representing a D-Bus well-known
+ name like "org.freedesktop.Telepathy.MissionControl".</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="DBus_Unique_Name" type="s">
+ <tp:docstring>A string representing a D-Bus unique name, such as
+ ":1.123"</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="DBus_Interface" type="s">
+ <tp:docstring>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".</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="DBus_Error_Name" type="s">
+ <tp:docstring>An ASCII string representing a D-Bus error. This is
+ syntactically the same as a <tp:type>DBus_Interface</tp:type>, but the
+ meaning is different.</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="DBus_Signature" type="s">
+ <tp:docstring>A string representing a D-Bus signature
+ (the 'g' type isn't used because of poor interoperability, particularly
+ with dbus-glib)</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="DBus_Member" type="s">
+ <tp:docstring>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".</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="DBus_Qualified_Member" type="s">
+ <tp:docstring>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".</tp:docstring>
+ </tp:simple-type>
+
+ <tp:mapping name="Qualified_Property_Value_Map"
+ array-name="Qualified_Property_Value_Map_List">
+ <tp:docstring>A mapping from strings representing D-Bus
+ properties (by their namespaced names) to their values.</tp:docstring>
+ <tp:member type="s" name="Key" tp:type="DBus_Qualified_Member">
+ <tp:docstring>
+ A D-Bus interface name, followed by a dot and a D-Bus property name.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="v" name="Value">
+ <tp:docstring>
+ The value of the property.
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <tp:mapping name="String_Variant_Map" array-name="String_Variant_Map_List">
+ <tp:docstring>A mapping from strings to variants representing extra
+ key-value pairs.</tp:docstring>
+ <tp:member type="s" name="Key"/>
+ <tp:member type="v" name="Value"/>
+ </tp:mapping>
+
+ <tp:mapping name="String_String_Map">
+ <tp:docstring>A mapping from strings to strings representing extra
+ key-value pairs.</tp:docstring>
+ <tp:member type="s" name="Key"/>
+ <tp:member type="s" name="Value"/>
+ </tp:mapping>
+
+</tp:generic-types>
Modified: trunk/extensions/misc.xml
==============================================================================
--- trunk/extensions/misc.xml (original)
+++ trunk/extensions/misc.xml Fri Jan 9 16:13:22 2009
@@ -8,5 +8,7 @@
<xi:include href="Channel_Handler.xml"/>
<xi:include href="Tube_Handler.xml"/>
<xi:include href="Channel_Type_File_Transfer.xml"/>
+<xi:include href="Channel_Interface_Tube.xml" />
+<xi:include href="Channel_Type_Stream_Tube.xml" />
</tp:spec>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
