diff options
| -rw-r--r-- | extensions/Channel_Interface_Tube.xml | 47 | ||||
| -rw-r--r-- | extensions/Channel_Type_DBus_Tube.xml | 114 | ||||
| -rw-r--r-- | extensions/Channel_Type_Stream_Tube.xml | 16 |
3 files changed, 93 insertions, 84 deletions
diff --git a/extensions/Channel_Interface_Tube.xml b/extensions/Channel_Interface_Tube.xml index 8e1ffab3a..8e6eb6514 100644 --- a/extensions/Channel_Interface_Tube.xml +++ b/extensions/Channel_Interface_Tube.xml @@ -1,7 +1,7 @@ <?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:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2008-2009 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 @@ -38,10 +38,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. HANDLE_TYPE_CONTACT (for 1-1 communication) or of type HANDLE_TYPE_ROOM (to communicate with others in the room simultaneously).</p> + + <p>As an exception to the usual handling of capabilities, connection managers + for protocols with capability discovery, such as XMPP, SHOULD advertise the + capability representing each Tube type that they support + (<tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.DBusTube</tp:dbus-ref> and/or + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.StreamTube</tp:dbus-ref>) + even if no client has indicated via + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref> + that such a tube is supported.</p> + + <tp:rationale> + <p>To lower the barrier entry of new tube application, CM SHOULD accept to offer tubes of any + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">Service</tp:dbus-ref> or + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT">ServiceName</tp:dbus-ref> + if the contact announced to support tubes.</p> + </tp:rationale> </tp:docstring> <property name="Parameters" type="a{sv}" tp:type="String_Variant_Map" - access="readwrite" tp:name-for-bindings="Parameters"> + access="read" 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 @@ -58,21 +77,23 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 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 + <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> + this property MUST NOT be included in the request. This property is undefined until the tube is offered + (using <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">OfferStreamTube</tp:dbus-ref> + or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT">OfferDBusTube</tp:dbus-ref>). + Once it has been offered, this property MUST NOT change.</p> + <p>When receiving an incoming tube, this property is immutable and so advertised in the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.NewChannels</tp:dbus-ref> + signal.</p> </tp:docstring> </property> - <property name="Status" type="u" tp:type="Tube_Channel_State" access="read" - tp:name-for-bindings="Status"> + <property name="State" type="u" tp:type="Tube_Channel_State" access="read" + tp:name-for-bindings="State"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Status of the tube in this channel.</p> - <p>When requesting a channel with + <p>State 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> diff --git a/extensions/Channel_Type_DBus_Tube.xml b/extensions/Channel_Type_DBus_Tube.xml index a3b98d7e4..513d77caa 100644 --- a/extensions/Channel_Type_DBus_Tube.xml +++ b/extensions/Channel_Type_DBus_Tube.xml @@ -1,7 +1,7 @@ <?xml version="1.0" ?> <node name="/Channel_Type_DBus_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:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2008-2009 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 @@ -58,6 +58,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:docstring> Offers a D-Bus tube providing the service specified. </tp:docstring> + <arg direction="in" name="parameters" type="a{sv}" + tp:type="String_Variant_Map"> + <tp:docstring> + The dictionary of arbitrary + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT">Parameters</tp:dbus-ref> + to send with the tube offer. + </tp:docstring> + </arg> + <arg direction="out" name="address" type="s"> + <tp:docstring> + The string describing the address of the private bus. 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.NetworkError"/> <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> @@ -66,11 +80,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. capabilities. </tp:docstring> </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The connection manager doesn't support D-Bus tubes. - </tp:docstring> - </tp:error> </tp:possible-errors> </method> @@ -87,71 +96,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 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 given tube ID is invalid or does not refer to a D-Bus - tube. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <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> - <arg direction="out" type="s"> - <tp:docstring> - The bus address. - </tp:docstring> - </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The tube is not a D-Bus tube. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - This tube is not in the "open" state. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <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. - </tp:docstring> - <arg direction="out" type="a(us)" tp:type="DBus_Tube_Member[]"> - <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"> - <tp:docstring> - The tube is not a multi-user D-Bus tube. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - This tube is not in the "open" state. - </tp:docstring> - </tp:error> - </tp:possible-errors> </method> <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. + participant opens or closes the tube. This provides change + notification for the <tp:member-ref>DBusNames</tp:member-ref> property. </tp:docstring> - <arg name="added" type="a(us)" tp:type="DBus_Tube_Member[]"> + <arg name="added" type="a{us}" tp:type="DBus_Tube_Participants"> <tp:docstring> Array of handles and D-Bus names of new participants. </tp:docstring> @@ -171,12 +124,39 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. com.example.ServiceName.</p> <p>When the tube is offered, the service name is transmitted to the other end.</p> - <p>When requesting a channel with + <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="DBusNames" tp:name-for-bindings="DBus_Names" + access="read" type="a{us}" tp:type="DBus_Tube_Participants"> + <tp:docstring> + For a multi-user (i.e. Handle_Type_Room) D-Bus tube, a mapping + between contact handles and their unique bus names on this tube. + For a peer-to-peer (i.e. Handle_Type_Contact) D-Bus tube, the empty + dictionary. Change notification is via + <tp:member-ref>DBusNamesChanged</tp:member-ref>. + </tp:docstring> + </property> + + <tp:mapping name="DBus_Tube_Participants"> + <tp:docstring>Represents the participants in a multi-user D-Bus tube, as + used by the <tp:member-ref>DBusNames</tp:member-ref> property and the + <tp:member-ref>DBusNamesChanged</tp:member-ref> signal.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"> + <tp:docstring> + The handle of a participant in this D-Bus tube. + </tp:docstring> + </tp:member> + <tp:member type="s" tp:type="DBus_Unique_Name" name="Unique_Name"> + <tp:docstring> + That participant's unique name. + </tp:docstring> + </tp:member> + </tp:mapping> + </interface> </node> diff --git a/extensions/Channel_Type_Stream_Tube.xml b/extensions/Channel_Type_Stream_Tube.xml index 4a43a0074..060cd0bb0 100644 --- a/extensions/Channel_Type_Stream_Tube.xml +++ b/extensions/Channel_Type_Stream_Tube.xml @@ -1,7 +1,7 @@ <?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:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2008-2009 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 @@ -66,6 +66,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. specified in the documentation for the Socket_Access_Control enum. </tp:docstring> </arg> + <arg direction="in" name="parameters" type="a{sv}" + tp:type="String_Variant_Map"> + <tp:docstring> + The dictionary of arbitrary + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT">Parameters</tp:dbus-ref> + to send with the tube offer. + </tp:docstring> + </arg> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> @@ -154,7 +162,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. "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 + <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> @@ -185,7 +193,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <p>Connection Managers MUST support at least IPv4 with the localhost access control.</p> - <p>When requesting a channel with + <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> |