[Telepathy-commits] [telepathy-gabble/master] Update Telepathy specification in extensions/ from tubes and caps branches of telepathy-spec. "Initiator" has been removed because o.f.T.Channel already has InitiatorHandle.
Alban Crequy
alban.crequy at collabora.co.uk
Mon Oct 27 10:43:16 PDT 2008
---
extensions/Channel_Interface_Tube.xml | 69 ++++++++++++++++++-------------
extensions/Channel_Type_DBus_Tube.xml | 16 ++++---
extensions/Channel_Type_Stream_Tube.xml | 20 +++++----
3 files changed, 61 insertions(+), 44 deletions(-)
diff --git a/extensions/Channel_Interface_Tube.xml b/extensions/Channel_Interface_Tube.xml
index c2213dc..c2ff044 100644
--- a/extensions/Channel_Interface_Tube.xml
+++ b/extensions/Channel_Interface_Tube.xml
@@ -21,29 +21,27 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
tp:causes-havoc="experimental">
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>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.</p>
+ <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>The Tubes channel type may be requested for handles of type
- HANDLE_TYPE_CONTACT and HANDLE_TYPE_ROOM.</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="Initiator" type="u" tp:type="Contact_Handle" access="read">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Initiator handle.</p>
- <p>When requesting a channel with
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.DRAFT.CreateChannel</tp:dbus-ref>,
- this property MUST NOT be included in the request.</p>
- </tp:docstring>
- </property>
-
<property name="Parameters" type="a{sv}" tp:type="String_Variant_Map"
- access="readwrite">
+ 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 for bootstrap information. The allowable keys,
@@ -51,10 +49,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
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 to the
- other end.</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:
+ <code>{'game name': 'go', 'board size': 19}</code></p>
<p>When requesting a channel with
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.DRAFT.CreateChannel</tp:dbus-ref>,
+ <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
@@ -63,11 +64,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:docstring>
</property>
- <property name="Status" type="u" tp:type="Tube_Channel_State" access="read">
+ <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.DRAFT.CreateChannel</tp:dbus-ref>,
+ <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>
@@ -75,27 +77,36 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<tp:enum name="Tube_Channel_State" type="u">
<tp:enumvalue suffix="Local_Pending" value="0">
<tp:docstring>
- The tube is waiting to be accepted/closed locally.
+ 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.
+ 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 tube is open for traffic.
+ 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 is not yet offered.
+ 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">
+ <signal name="TubeChannelStateChanged"
+ tp:name-for-bindings="Tube_Channel_State_Changed">
<tp:docstring>
Emitted when the state of the tube channel changes.
</tp:docstring>
diff --git a/extensions/Channel_Type_DBus_Tube.xml b/extensions/Channel_Type_DBus_Tube.xml
index 2e5fae6..3846afb 100644
--- a/extensions/Channel_Type_DBus_Tube.xml
+++ b/extensions/Channel_Type_DBus_Tube.xml
@@ -54,7 +54,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:docstring>
- <method name="OfferDBusTube">
+ <method name="OfferDBusTube" tp:name-for-bindings="Offer_DBus_Tube">
<tp:docstring>
Offers a D-Bus tube providing the service specified.
</tp:docstring>
@@ -74,7 +74,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:possible-errors>
</method>
- <method name="AcceptDBusTube">
+ <method name="AcceptDBusTube" tp:name-for-bindings="Accept_DBus_Tube">
<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
@@ -97,7 +97,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:possible-errors>
</method>
- <method name="GetDBusTubeAddress">
+ <method name="GetDBusTubeAddress"
+ tp:name-for-bindings="Get_DBus_Tube_Address">
<tp:docstring>
Return a string describing the address of the private bus.
</tp:docstring>
@@ -120,7 +121,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:possible-errors>
</method>
- <method name="GetDBusNames">
+ <method name="GetDBusNames" tp:name-for-bindings="Get_DBus_Names">
<tp:docstring>
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.
@@ -145,7 +146,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:possible-errors>
</method>
- <signal name="DBusNamesChanged">
+ <signal name="DBusNamesChanged" tp:name-for-bindings="DBus_Names_Changed">
<tp:docstring>
Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a
participant opens or closes the tube.
@@ -162,7 +163,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</arg>
</signal>
- <property name="ServiceName" type="s" access="read">
+ <property name="ServiceName" type="s" access="read"
+ tp:name-for-bindings="Service_Name">
<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
@@ -170,7 +172,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<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.DRAFT.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>
diff --git a/extensions/Channel_Type_Stream_Tube.xml b/extensions/Channel_Type_Stream_Tube.xml
index 390636b..f34f441 100644
--- a/extensions/Channel_Type_Stream_Tube.xml
+++ b/extensions/Channel_Type_Stream_Tube.xml
@@ -33,7 +33,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:docstring>
- <method name="OfferStreamTube">
+ <method name="OfferStreamTube" tp:name-for-bindings="Offer_Stream_Tube">
<tp:docstring>
Offer a stream tube exporting the local socket specified.
</tp:docstring>
@@ -79,7 +79,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:possible-errors>
</method>
- <method name="AcceptStreamTube">
+ <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
@@ -126,7 +126,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:possible-errors>
</method>
- <method name="GetStreamTubeSocketAddress">
+ <method name="GetStreamTubeSocketAddress"
+ tp:name-for-bindings="Get_Stream_Tube_Socket_Address">
<tp:docstring>
For a stream tube, obtain the address of the socket used to
communicate over this tube.
@@ -152,7 +153,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:possible-errors>
</method>
- <signal name="StreamTubeNewConnection">
+ <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.
@@ -164,7 +166,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</arg>
</signal>
- <property name="Service" type="s" access="read">
+ <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
@@ -176,13 +179,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<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.DRAFT.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>
<property name="SupportedSocketTypes" type="a{uau}"
- tp:type="Supported_Socket_Map" access="read">
+ 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)
@@ -203,7 +207,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</pre>
<p>When requesting a channel with
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.DRAFT.CreateChannel</tp:dbus-ref>,
+ <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>
--
1.5.6.5
More information about the Telepathy-commits
mailing list