[Pkg-telepathy-commits] [telepathy-glib] 33/111: spec 0.27.3
Simon McVittie
smcv at debian.org
Wed Mar 19 18:07:24 UTC 2014
This is an automated email from the git hooks/post-receive script.
smcv pushed a commit to branch debian
in repository telepathy-glib.
commit 4868017daf708049102ee33618a615f96f4adbc6
Author: Guillaume Desmottes <guillaume.desmottes at collabora.co.uk>
Date: Mon Oct 28 12:05:36 2013 +0100
spec 0.27.3
---
docs/reference/telepathy-glib-sections.txt | 1 +
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 +-
8 files changed, 379 insertions(+), 4 deletions(-)
diff --git a/docs/reference/telepathy-glib-sections.txt b/docs/reference/telepathy-glib-sections.txt
index d8f3a15..ad1fd64 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 0000000..e768b55
--- /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 f50b963..493ac54 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 0000000..864f1fa
--- /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 d08b748..2006118 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 0000000..c303fcb
--- /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 ea7899a..711c07b 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 e1c8647..e94eb06 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"/>
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-telepathy/telepathy-glib.git
More information about the Pkg-telepathy-commits
mailing list