diff options
author | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2008-09-26 17:43:42 +0100 |
---|---|---|
committer | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2008-09-26 17:47:07 +0100 |
commit | 224a21a88387343c4c7047ced55614594d105785 (patch) | |
tree | 0d2077559180882172f23e4643cc977937bc674b /spec/Channel_Interface_Destroyable.xml | |
parent | 2afdf679d8b6304efacadaab7211a8d2a10fd793 (diff) | |
download | telepathy-glib-224a21a88387343c4c7047ced55614594d105785.tar.gz |
Update spec to 0.17.12 (no code changes) and prepare 0.7.16 releasetelepathy-glib-0.7.16
Diffstat (limited to 'spec/Channel_Interface_Destroyable.xml')
-rw-r--r-- | spec/Channel_Interface_Destroyable.xml | 79 |
1 files changed, 79 insertions, 0 deletions
diff --git a/spec/Channel_Interface_Destroyable.xml b/spec/Channel_Interface_Destroyable.xml new file mode 100644 index 000000000..2f82e6980 --- /dev/null +++ b/spec/Channel_Interface_Destroyable.xml @@ -0,0 +1,79 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Destroyable" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 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.Channel.Interface.Destroyable.DRAFT" + tp:causes-havoc="experimental"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:added version="0.17.UNRELEADED">(draft, not API-stable)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface exists to support channels where + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref> + is insufficiently destructive.</p> + </tp:docstring> + + <method name="Destroy" tp:name-for-bindings="Destroy"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Close the channel abruptly, possibly with loss of data. The + connection manager MUST NOT re-create the channel unless/until + more events occur.</p> + + <tp:rationale> + <p>The main motivating situation for this method is that when a Text + channel with pending messages is closed with Close, it comes back + as an incoming channel (to avoid a race between Close and an + incoming message). If Destroy is called on a Text channel, the CM + should delete all pending messages and close the channel, and + the channel shouldn't be re-created until/unless another message + arrives.</p> + </tp:rationale> + + <p>Most clients SHOULD call + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref> + instead. However, if a client explicitly intends to destroy the + channel with possible loss of data, it SHOULD call this method + if this interface is supported (according to the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Interfaces</tp:dbus-ref> + property), falling back to Close if not.</p> + + <p>In particular, channel dispatchers SHOULD use this method if + available when terminating channels that cannot be handled + correctly (for instance, if no handler has been installed for + a channel type, or if the handler crashes repeatedly).</p> + + <p>Connection managers do not need to implement this interface on + channels where Close and Destroy would be equivalent.</p> + + <tp:rationale> + <p>Callers need to be able to fall back to Close in any case.</p> + </tp:rationale> + </tp:docstring> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |