From 4868017daf708049102ee33618a615f96f4adbc6 Mon Sep 17 00:00:00 2001 From: Guillaume Desmottes Date: Mon, 28 Oct 2013 12:05:36 +0100 Subject: spec 0.27.3 --- spec/Channel_Dispatcher_Interface_Messages1.xml | 175 ++++++++++++++++++++++++ spec/Channel_Type_File_Transfer.xml | 29 ++++ spec/Connection_Interface_IRC_Command1.xml | 55 ++++++++ spec/Connection_Interface_Renaming.xml | 4 +- spec/Connection_Interface_Sidecars1.xml | 110 +++++++++++++++ spec/Makefile.am | 3 + spec/all.xml | 6 +- 7 files changed, 378 insertions(+), 4 deletions(-) create mode 100644 spec/Channel_Dispatcher_Interface_Messages1.xml create mode 100644 spec/Connection_Interface_IRC_Command1.xml create mode 100644 spec/Connection_Interface_Sidecars1.xml (limited to 'spec') 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 @@ + + + + Copyright (C) 2011-2013 Collabora Ltd. + Copyright (C) 2011 Nokia Corporation + +

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.

+ + + + + + +

+ 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. +

+ + +

+ This enables entities other than the main UI to send messages + to contacts. +

+ + + + + + + The Account + through which to communicate. + + + + + The contact to send the message to. + + + + + The parts of the message, the same as for Messages.SendMessage. + + + + + Flags influencing how to send the message, the same as for Messages.SendMessage. + + + + + An opaque token equivalent to the one returned by Messages.SendMessage. + + + +

Submit a message to the server for sending, like the + Messages.SendMessage + method.

+ +

If the Account is connected and a Text channel to the + Target_ID already exists, this method is equivalent to + sending the same message via that channel.

+ +

Otherwise, this method creates a channel (connecting the + Account if appropriate), sends the desired message, and + closes the channel as if via Channel.Close, without + acknowledging any messages received on that channel + during that time.

+ +

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 Handler for text + channels. In particular, this deals with the situation where + a successful or failed delivery report is received + before the channel is closed.

+ + +

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.

+ + +

The ChannelDispatcher SHOULD support this method for any + connection manager that would accept channel requests of this + form:

+ + 
  {
+    …Channel.ChannelType:
+        …Channel.Type.Text,
+    …Channel.TargetHandleType:
+        Contact,
+    …Channel.TargetID:
+    Target_ID
+  }
+ +

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.

+ +

This method may raise any error that would be raised by the + Requests.EnsureChannel + or Messages.SendMessage + methods, or signalled by the Failed + signal.

+ + + + + + + + The connection manager does not implement Text channels + that communicate with a named contact. + + + + + The Target_ID was not syntactically valid for the + Account's protocol. + + + + + The requested message is malformed and cannot be sent. + + + + + The requested channel cannot be created because the target is + offline. + + + + + The requested channel cannot be created, but in + principle, a similar request might succeed in future. + + + + + + + + + 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. + + + +

The collection of files to which this channel belongs, + or the empty string if this channel does not belong to + a collection of files.

+ +

A channel's FileCollection property can never change.

+ +

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.

+ +

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.

+ +

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.

+ + + 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 @@ + + + Copyright (C) 2013 Collabora Limited + +

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.

+ + + + + + + + + The command followed by its arguments. + + + +

Send an arbitrary IRC command to the server.

+

For example, an IRC client receiving /bip blreset from + the user might call this method with BIP blreset as + argument which will send BIP blreset to the server.

+

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.

+ + + + + + + The connection manager MAY raise this error for commands that + have a more appropriate D-Bus API. + + + + + + An interface to send arbitrary IRC commands to the server. + + + + 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.

License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

- + + (as stable API) 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 @@ + + + Copyright © 2009-2013 Collabora Limited + Copyright © 2009 Nokia Corporation + +

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.

+ + + + + + + (as stable API) + + + + 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 com.example.PrivacyLists. + + + + + The object path of the sidecar, exported by the same bus + name as the Connection to which it is attached. + + + Immutable properties of the sidecar. + + + +

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.

+ +

This method may be called at any point during the lifetime of a + connection, even before its Connection_Status + 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).

+ + +

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 + Channel + instead.

+ + + + + + 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.) + + + + + + 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. + + + + + + The connection was disconnected while the sidecar was being set up. + + + + + + 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"> Telepathy D-Bus Interface Specification -0.27.2 +0.27.3 Copyright © 2005-2012 Collabora Limited Copyright © 2005-2011 Nokia Corporation @@ -48,7 +48,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - @@ -108,6 +107,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + @@ -300,6 +301,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + -- cgit v1.2.1