diff options
author | Guillaume Desmottes <guillaume.desmottes@collabora.co.uk> | 2013-10-28 12:05:36 +0100 |
---|---|---|
committer | Guillaume Desmottes <guillaume.desmottes@collabora.co.uk> | 2013-10-28 12:53:35 +0100 |
commit | 4868017daf708049102ee33618a615f96f4adbc6 (patch) | |
tree | dba2f7190b44ac13512dd45f6e4839f4ca8511f3 | |
parent | c38e41c0ae63ca6082381981bb7c71a14a7e8f94 (diff) | |
download | telepathy-glib-4868017daf708049102ee33618a615f96f4adbc6.tar.gz |
spec 0.27.3
-rw-r--r-- | docs/reference/telepathy-glib-sections.txt | 1 | ||||
-rw-r--r-- | spec/Channel_Dispatcher_Interface_Messages1.xml | 175 | ||||
-rw-r--r-- | spec/Channel_Type_File_Transfer.xml | 29 | ||||
-rw-r--r-- | spec/Connection_Interface_IRC_Command1.xml | 55 | ||||
-rw-r--r-- | spec/Connection_Interface_Renaming.xml | 4 | ||||
-rw-r--r-- | spec/Connection_Interface_Sidecars1.xml | 110 | ||||
-rw-r--r-- | spec/Makefile.am | 3 | ||||
-rw-r--r-- | spec/all.xml | 6 |
8 files changed, 379 insertions, 4 deletions
diff --git a/docs/reference/telepathy-glib-sections.txt b/docs/reference/telepathy-glib-sections.txt index d8f3a1503..ad1fd64ed 100644 --- a/docs/reference/telepathy-glib-sections.txt +++ b/docs/reference/telepathy-glib-sections.txt @@ -3448,6 +3448,7 @@ TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_CONTENT_TYPE TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_DATE TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_DESCRIPTION TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_FILENAME +TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_FILE_COLLECTION TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_INITIAL_OFFSET TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_SIZE TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_STATE diff --git a/spec/Channel_Dispatcher_Interface_Messages1.xml b/spec/Channel_Dispatcher_Interface_Messages1.xml new file mode 100644 index 000000000..e768b5549 --- /dev/null +++ b/spec/Channel_Dispatcher_Interface_Messages1.xml @@ -0,0 +1,175 @@ +<?xml version="1.0" ?> +<node name="/Channel_Dispatcher_Interface_Messages1" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright (C) 2011-2013 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2011 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>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.</p> + + <p>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.</p> + + <p>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.</p> + </tp:license> + + <interface + name="org.freedesktop.Telepathy.ChannelDispatcher.Interface.Messages1"> + <tp:requires interface="org.freedesktop.Telepathy.ChannelDispatcher"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + This interface allows DBus clients to use the ChannelDispatcher to + send one-off text messages to a contact, identified by account and + target ID, without requiring the caller to handle channels or be + the primary message UI. + </p> + + <tp:rationale> + <p> + This enables entities other than the main UI to send messages + to contacts. + </p> + </tp:rationale> + </tp:docstring> + + <method name="SendMessage" tp:name-for-bindings="Send_Message"> + <arg direction="in" name="Account" type="o"> + <tp:docstring> + The <tp:dbus-ref namespace="ofdT">Account</tp:dbus-ref> + through which to communicate. + </tp:docstring> + </arg> + <arg direction="in" name="Target_ID" type="s"> + <tp:docstring> + The contact to send the message to. + </tp:docstring> + </arg> + <arg direction="in" name="Message" type="aa{sv}" + tp:type="Message_Part[]"> + <tp:docstring> + The parts of the message, the same as for <tp:dbus-ref + namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref>. + </tp:docstring> + </arg> + <arg direction="in" name="Flags" type="u"> + <tp:docstring> + Flags influencing how to send the message, the same as for <tp:dbus-ref + namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref>. + </tp:docstring> + </arg> + <arg direction="out" name="Token" type="s"> + <tp:docstring> + An opaque token equivalent to the one returned by <tp:dbus-ref + namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref>. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Submit a message to the server for sending, like the + <tp:dbus-ref namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref> + method.</p> + + <p>If the <var>Account</var> is connected and a Text channel to the + <var>Target_ID</var> already exists, this method is equivalent to + sending the same message via that channel.</p> + + <p>Otherwise, this method creates a channel (connecting the + Account if appropriate), sends the desired message, and + closes the channel as if via <tp:dbus-ref + namespace="ofdT">Channel.Close</tp:dbus-ref>, without + acknowledging any messages received on that channel + during that time.</p> + + <p>If any messages are received on that channel before it is + closed, a correct connection manager implementation will reopen + the channel when it is closed, resulting in those "rescued" messages + being processed by the system's normal <tp:dbus-ref + namespace="ofdT.Client">Handler</tp:dbus-ref> for text + channels. In particular, this deals with the situation where + a successful or failed delivery report is received + before the channel is closed.</p> + + <tp:rationale> + <p>Expecting a trivial client (perhaps a send-only IRC bot, + or a simple SMS-sending API) to go through all those steps to + send a message seems somewhat unreasonable. Having this as a + method in the ChannelDispatcher lets it take some short-cuts if + required, and centralizes the implementation to reduce the risk of + mistakes that cause message loss.</p> + </tp:rationale> + + <p>The ChannelDispatcher SHOULD support this method for any + connection manager that would accept channel requests of this + form:</p> + + <pre> { + …<tp:dbus-ref namespace="ofdT">Channel.ChannelType</tp:dbus-ref>: + …<tp:dbus-ref namespace="ofdT">Channel.Type.Text</tp:dbus-ref>, + …<tp:dbus-ref namespace="ofdT">Channel.TargetHandleType</tp:dbus-ref>: + <tp:value-ref type="Handle_Type">Contact</tp:value-ref>, + …<tp:dbus-ref namespace="ofdT">Channel.TargetID</tp:dbus-ref>: + <var>Target_ID</var> + }</pre> + + <p>However, if the connection manager provides additional APIs + (such as a way to open "send-only" channels), the + ChannelDispatcher MAY use those: it is not required to use + those exact request parameters.</p> + + <p>This method may raise any error that would be raised by the + <tp:dbus-ref + namespace="ofdT.Connection.Interface">Requests.EnsureChannel</tp:dbus-ref> + or <tp:dbus-ref + namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref> + methods, or signalled by the <tp:dbus-ref + namespace="ofdT.ChannelRequest">Failed</tp:dbus-ref> + signal.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The connection manager does not implement Text channels + that communicate with a named contact. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The <var>Target_ID</var> was not syntactically valid for the + <var>Account</var>'s protocol. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + <tp:docstring> + The requested message is malformed and cannot be sent. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.Offline"> + <tp:docstring> + The requested channel cannot be created because the target is + offline. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The requested channel cannot be created, but in + principle, a similar request might succeed in future. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + + </interface> +</node> + diff --git a/spec/Channel_Type_File_Transfer.xml b/spec/Channel_Type_File_Transfer.xml index f50b96344..493ac54f4 100644 --- a/spec/Channel_Type_File_Transfer.xml +++ b/spec/Channel_Type_File_Transfer.xml @@ -579,6 +579,35 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </arg> </signal> + <property name="FileCollection" tp:name-for-bindings="File_Collection" + type="s" access="read"> + <tp:added version="0.27.3"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The collection of files to which this channel belongs, + or the empty string if this channel does not belong to + a collection of files.</p> + + <p>A channel's FileCollection property can never change.</p> + + <p>At least on GTalk and apparently also on iChat the user can + send a set of files to a contact and that contact can then + pick and choose which files to actually receive.</p> + + <p> The CM should emit all new FT channels belonging to one collection + at the same time. UIs supporting this feature can then + bundle all these channels together in some way, and show a + nice UI. UIs not supporting it will treat them as separate + transfers, which is not great but a reasonable fallback.</p> + + <p>No mechanism is currently defined to indicate whether the UI + should expect any more files in the same collection. UIs + SHOULD assume that more file transfers may be added to a + collection. It is possible that a "no more channels in this + collection" indication will be added in a future version of + this specification.</p> + </tp:docstring> + </property> + </interface> </node> diff --git a/spec/Connection_Interface_IRC_Command1.xml b/spec/Connection_Interface_IRC_Command1.xml new file mode 100644 index 000000000..864f1fa8e --- /dev/null +++ b/spec/Connection_Interface_IRC_Command1.xml @@ -0,0 +1,55 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_IRC_Command1" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2013 Collabora Limited </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>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.</p> + +<p>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.</p> + +<p>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.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.IRCCommand1" + tp:causes-havoc='not well-tested'> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:added version="0.27.3"/> + + <method name="Send" tp:name-for-bindings="Send"> + <arg direction="in" name="Command" type="s"> + <tp:docstring> + The command followed by its arguments. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Send an arbitrary IRC command to the server.</p> + <p>For example, an IRC client receiving <code>/bip blreset</code> from + the user might call this method with <code>BIP blreset</code> as + argument which will send <code>BIP blreset</code> to the server.</p> + <p>The command is supplied in UTF-8 (because strings on D-Bus are + always UTF-8). It is transcoded into the connection's configured + character set, if different, before sending to the server.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The connection manager MAY raise this error for commands that + have a more appropriate D-Bus API. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + <tp:docstring> + An interface to send arbitrary IRC commands to the server. + </tp:docstring> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Renaming.xml b/spec/Connection_Interface_Renaming.xml index d08b748d9..200611850 100644 --- a/spec/Connection_Interface_Renaming.xml +++ b/spec/Connection_Interface_Renaming.xml @@ -18,8 +18,8 @@ Lesser General Public License for more details.</p> License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Connection.Interface.Renaming" - tp:causes-havoc='not well-tested'> + <interface name="org.freedesktop.Telepathy.Connection.Interface.Renaming"> + <tp:added version="0.27.3">(as stable API)</tp:added> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> <signal name="Renamed" tp:name-for-bindings="Renamed"> <arg name="Original" type="u" tp:type="Contact_Handle"> diff --git a/spec/Connection_Interface_Sidecars1.xml b/spec/Connection_Interface_Sidecars1.xml new file mode 100644 index 000000000..c303fcbe8 --- /dev/null +++ b/spec/Connection_Interface_Sidecars1.xml @@ -0,0 +1,110 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Sidecars1" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" + > + <tp:copyright>Copyright © 2009-2013 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> +<p>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.</p> + +<p>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.</p> + +<p>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.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Connection.Interface.Sidecars1"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:added version="0.27.3"/> + + <method name="EnsureSidecar" tp:name-for-bindings="Ensure_Sidecar"> + <tp:added version="0.27.3">(as stable API)</tp:added> + + <arg direction="in" name="Main_Interface" type="s" + tp:type="DBus_Interface"> + <tp:docstring> + The "primary" interface implemented by an object attached + to a connection. For example, a Gabble plugin implementing + fine-grained control of XEP-0016 privacy lists might expose an object + implementing <tt>com.example.PrivacyLists</tt>. + </tp:docstring> + </arg> + + <arg direction="out" name="Path" type="o"> + <tp:docstring>The object path of the sidecar, exported by the same bus + name as the Connection to which it is attached.</tp:docstring> + </arg> + <arg direction="out" name="Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring>Immutable properties of the sidecar.</tp:docstring> + </arg> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request an object with a particular interface providing additional + connection-specific functionality, together with its immutable + properties. These will often be implemented by plug-ins to the + connection managers; for example, support for an XMPP XEP for which + no generic Telepathy interface exists might be implemented by a + Gabble plugin exposing a sidecar with a particular interface.</p> + + <p>This method may be called at any point during the lifetime of a + connection, even before its <tp:type>Connection_Status</tp:type> + changes to Connected. It MAY take a long time to + return—perhaps it needs to wait for a connection to be established + and for all the services supported by the server to be discovered + before determining whether necessary server-side support is + available—so callers SHOULD override the default method timeout (25 + seconds) with a much higher value (perhaps even MAX_INT32, meaning + “no timeout” in recent versions of libdbus).</p> + + <tp:rationale> + <p>There is an implicit assumption that any connection + manager plugin will only want to export one “primary” object per + feature it implements, since there is a one-to-one mapping between + interface and object. This is reasonable since Sidecars are + (intended to be) analogous to extra interfaces on the connection, + providing once-per-connection shared functionality; it also makes + client code straightforward (look up the interface you care about + in a dictionary, build a proxy object from the value). More + “plural” plugins are likely to want to implement new types of + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref> + instead.</p> + </tp:rationale> + </tp:docstring> + + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The requested sidecar is not implemented by this connection manager, + or a necessary server-side component does not exist. (FIXME: split + these two errors out? Then again, once we list the guaranteed and + possible sidecars on a Protocol object, clients can tell the + difference themselves, because they shouldn't be calling this in the + first case.) + </tp:docstring> + </tp:error> + + <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy"> + <tp:docstring> + A server-side component needed by the requested sidecar reported it + is currently too busy, or did not respond for some + implementation-defined time. The caller may wish to try again later. + </tp:docstring> + </tp:error> + + <tp:error name="org.freedesktop.Telepathy.Error.Cancelled"> + <tp:docstring> + The connection was disconnected while the sidecar was being set up. + </tp:docstring> + </tp:error> + </method> + + </interface> +</node> diff --git a/spec/Makefile.am b/spec/Makefile.am index ea7899a07..711c07bb8 100644 --- a/spec/Makefile.am +++ b/spec/Makefile.am @@ -24,6 +24,7 @@ EXTRA_DIST = \ Channel.xml \ Channel_Dispatch_Operation.xml \ Channel_Dispatcher.xml \ + Channel_Dispatcher_Interface_Messages1.xml \ Channel_Dispatcher_Interface_Operation_List.xml \ Channel_Future.xml \ Channel_Handler.xml \ @@ -92,6 +93,7 @@ EXTRA_DIST = \ Connection_Interface_Contact_List.xml \ Connection_Interface_Contacts.xml \ Connection_Interface_Forwarding.xml \ + Connection_Interface_IRC_Command1.xml \ Connection_Interface_Keepalive.xml \ Connection_Interface_Location.xml \ Connection_Interface_Mail_Notification.xml \ @@ -102,6 +104,7 @@ EXTRA_DIST = \ Connection_Interface_Requests.xml \ Connection_Interface_Resources.xml \ Connection_Interface_Service_Point.xml \ + Connection_Interface_Sidecars1.xml \ Connection_Interface_Simple_Presence.xml \ Connection_Manager.xml \ Connection_Manager_Interface_Account_Storage.xml \ diff --git a/spec/all.xml b/spec/all.xml index e1c8647eb..e94eb0677 100644 --- a/spec/all.xml +++ b/spec/all.xml @@ -3,7 +3,7 @@ xmlns:xi="http://www.w3.org/2001/XInclude"> <tp:title>Telepathy D-Bus Interface Specification</tp:title> -<tp:version>0.27.2</tp:version> +<tp:version>0.27.3</tp:version> <tp:copyright>Copyright © 2005-2012 Collabora Limited</tp:copyright> <tp:copyright>Copyright © 2005-2011 Nokia Corporation</tp:copyright> @@ -48,7 +48,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </p> </tp:docstring> <xi:include href="Connection.xml"/> - <xi:include href="Connection_Future.xml"/> <xi:include href="Connection_Interface_Contacts.xml"/> <xi:include href="Connection_Interface_Requests.xml"/> @@ -108,6 +107,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Connection_Interface_Mail_Notification.xml"/> <xi:include href="Connection_Interface_Power_Saving.xml"/> <xi:include href="Connection_Interface_Service_Point.xml"/> + <xi:include href="Connection_Interface_Sidecars1.xml"/> + <xi:include href="Connection_Interface_IRC_Command1.xml"/> </tp:section> </tp:section> @@ -300,6 +301,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </p> </tp:docstring> <xi:include href="Channel_Dispatcher.xml"/> + <xi:include href="Channel_Dispatcher_Interface_Messages1.xml"/> <xi:include href="Channel_Dispatcher_Interface_Operation_List.xml"/> <xi:include href="Channel_Dispatch_Operation.xml"/> <xi:include href="Channel_Request.xml"/> |