diff options
author | Guillaume Desmottes <guillaume.desmottes@collabora.co.uk> | 2007-04-20 13:47:44 +0000 |
---|---|---|
committer | Guillaume Desmottes <guillaume.desmottes@collabora.co.uk> | 2007-04-20 13:47:44 +0000 |
commit | 2f1012fa62f639553939c346e04fcb09e5eaf4ff (patch) | |
tree | b3a52bf7c8cff256c785d1f78aa6b7006a9217a8 /spec/Channel_Type_Tubes.xml | |
parent | 74883b61bb5b28764758372a0d834ce4011275b9 (diff) | |
download | telepathy-glib-2f1012fa62f639553939c346e04fcb09e5eaf4ff.tar.gz |
add Tubes spec
20070420134744-7fe3f-05ccec098238f881f943370256b256d738466a03.gz
Diffstat (limited to 'spec/Channel_Type_Tubes.xml')
-rw-r--r-- | spec/Channel_Type_Tubes.xml | 291 |
1 files changed, 291 insertions, 0 deletions
diff --git a/spec/Channel_Type_Tubes.xml b/spec/Channel_Type_Tubes.xml new file mode 100644 index 000000000..ec9795764 --- /dev/null +++ b/spec/Channel_Type_Tubes.xml @@ -0,0 +1,291 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Tubes" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> + Copyright (C) 2007 Collabora Limited + </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 +Library 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Type.Tubes" tp:name-const="CHANNEL_TYPE_TUBES"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:docstring> + A "tube" is a mechanism for arbitrary data transfer. Currently, one kind + of data transfer is specified, namely that of D-Bus messages. Each tube + has a service name, which is a string specifying the kind of + communication that takes place over it, and a dictionary of arbitrary + parameters. Tube parameters are commonly used for bootstrap information + such as usernames and passwords. + + The Tubes channel type may be requested for handles of type + HANDLE_TYPE_CONTACT and HANDLE_TYPE_ROOM. + </tp:docstring> + + <tp:enum name="Tube_Type"> + <tp:enumvalue suffix="DBus" value="0"> + <tp:docstring> + 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 service name of a D-Bus tube should be a + well-known D-Bus service name, of the form com.example.ServiceName. + + 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. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:enum name="Tube_State"> + <tp:enumvalue suffix="Local_Pending" value="0"> + <tp:docstring> + The tube is waiting to be accepted/closed locally. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Remote_Pending" value="1"> + <tp:docstring> + The tube is waiting to be accepted/closed remotely. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Open" value="2"> + <tp:docstring> + The tube is open for traffic. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <method name="GetAvailableTubeTypes"> + <arg direction="out" type="au"> + <tp:docstring> + An array of the available tube types, as defined by the Tube_Type + enum. + </tp:docstring> + </arg> + </method> + + <method name="ListTubes"> + <arg direction="out" type="a(uuusa{sv}u)"> + <tp:docstring> + Return an array of tuples, each representing a tube, with the + following members: + + <ul> + <li>the tube's ID</li> + <li>the tube's initiator</li> + <li>the tube's type</li> + <li>the tube's service</li> + <li>the tube's parameters</li> + <li>the tube's state</li> + </ul> + </tp:docstring> + </arg> + </method> + + <method name="OfferTube"> + <tp:docstring> + Offers a tube providing the service specified, over a tube of the + specified type. + </tp:docstring> + <arg direction="in" name="type" type="u"> + <tp:docstring> + The type of tube wanted, one of the values from + the Tube_Type enum. + </tp:docstring> + </arg> + <arg direction="in" name="service" type="s"> + <tp:docstring> + A string representing the service that will be used over the tube. + </tp:docstring> + </arg> + <arg direction="in" name="parameters" type="a{sv}"> + <tp:docstring> + A dicionary of properties for the new tube. + </tp:docstring> + </arg> + <arg direction="out" type="u"> + <tp:docstring> + The ID of the new tube. + </tp:docstring> + </arg> + </method> + + <signal name="NewTube"> + <tp:docstring> + Emitted when a tube is created. + </tp:docstring> + <arg name="id" type="u"> + <tp:docstring> + The ID of the new tube. + </tp:docstring> + </arg> + <arg name="initiator" type="u"> + <tp:docstring> + The handle of the contact who initiated the tube. + </tp:docstring> + </arg> + <arg name="type" type="u"> + <tp:docstring> + The tube type, as defined by the Tube_Type enum. + </tp:docstring> + </arg> + <arg name="service" type="s"> + <tp:docstring> + A string representing the service that will be used over the tube. + </tp:docstring> + </arg> + <arg name="parameters" type="a{sv}"> + <tp:docstring> + The new tube's properties. + </tp:docstring> + </arg> + <arg name="state" type="u"> + <tp:docstring> + The new tube's state. + </tp:docstring> + </arg> + </signal> + + <method name="AcceptTube"> + <tp:docstring> + Accept a tube that's in the "local pending" state. The tube becomes + open after this method is called. + </tp:docstring> + <arg direction="in" name="id" type="u"> + <tp:docstring> + The ID of the tube to accept. + </tp:docstring> + </arg> + </method> + + <signal name="TubeStateChanged"> + <tp:docstring> + Emitted when the state of a tube changes. + </tp:docstring> + <arg name="id" type="u"> + <tp:docstring> + The ID of the tube that changed state. + </tp:docstring> + </arg> + <arg name="state" type="u"> + <tp:docstring> + The new state of the tube; see the Tube_State enumeration. + </tp:docstring> + </arg> + </signal> + + <method name="CloseTube"> + <tp:docstring> + Close a tube. + </tp:docstring> + <arg direction="in" name="id" type="u"> + <tp:docstring> + The ID of the tube to close. + </tp:docstring> + </arg> + </method> + + <signal name="TubeClosed"> + <tp:docstring> + Emitted when a tube has been closed. The ID of a closed tube is no + longer valid. The ID may later be reused for a new tube. + </tp:docstring> + <arg name="id" type="u"> + <tp:docstring> + The ID of the tube that was closed. + </tp:docstring> + </arg> + </signal> + + <method name="GetDBusServerAddress"> + <tp:docstring> + For a D-Bus tube, return a string describing the address of the + private bus. + </tp:docstring> + <arg direction="in" name="id" type="u"> + <tp:docstring> + The ID of the tube to get an address for. + </tp:docstring> + </arg> + <arg direction="out" type="s"> + <tp:docstring> + The bus address. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + The tube is not a D-Bus tube. + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + This tube is not in the "open" state. + </tp:error> + </tp:possible-errors> + </method> + + <method name="GetDBusNames"> + <tp:docstring> + For a D-Bus tube, obtain a mapping between contact handles and their + unique bus names on this tube. + </tp:docstring> + <arg direction="in" name="id" type="u"> + <tp:docstring> + The ID of the tube to get names for. + </tp:docstring> + </arg> + <arg direction="out" type="a(us)"> + <tp:docstring> + An array of structures, each containing a contact handle and a D-Bus + bus name. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + The tube is not a D-Bus tube. + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + This tube is not in the "open" state. + </tp:error> + </tp:possible-errors> + </method> + + <signal name="DBusNamesChanged"> + <tp:docstring> + Emitted on a D-Bus tube when a participant opens or closes the tube. + </tp:docstring> + <arg name="id" type="u"> + <tp:docstring> + The ID of the tube whose names have changed. + </tp:docstring> + </arg> + <arg name="added" type="a(us)"> + <tp:docstring> + Array of handles and D-Bus names of new participants. + </tp:docstring> + </arg> + <arg name="removed" type="au"> + <tp:docstring> + Array of handles of former participants. + </tp:docstring> + </arg> + </signal> + + </interface> + +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |