diff options
Diffstat (limited to 'qt4/spec/Client_Approver.xml')
| -rw-r--r-- | qt4/spec/Client_Approver.xml | 201 |
1 files changed, 0 insertions, 201 deletions
diff --git a/qt4/spec/Client_Approver.xml b/qt4/spec/Client_Approver.xml deleted file mode 100644 index 12cbc76ac..000000000 --- a/qt4/spec/Client_Approver.xml +++ /dev/null @@ -1,201 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Client_Approver" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright © 2008-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.Client.Approver"> - <tp:added version="0.17.26">(as a stable interface)</tp:added> - - <tp:requires interface="org.freedesktop.Telepathy.Client"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Approvers are clients that notify the user that new channels have - been created by a contact, and allow the user to accept or reject - those channels. The new channels are represented by a <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref> - object, which is passed to the - <tp:member-ref>AddDispatchOperation</tp:member-ref> method.</p> - - <tp:rationale> - <p>For instance, Empathy's tray icon, or the answer/reject window - seen when a Maemo device receives a VoIP call, should be - Approvers.</p> - </tp:rationale> - - <p>Approvers can also select which channel handler will be used for the - channel, for instance by offering the user a list of possible - handlers rather than just an accept/reject choice. - However, the Channel Dispatcher must be able to prioritize - possible handlers on its own using some reasonable heuristic, - probably based on user configuration.</p> - - <p>It is possible (and useful) to have an approver and - a channel handler in the same process; this is particularly useful - if a channel handler wants to claim responsibility for particular - channels itself.</p> - - <p>All approvers are notified simultaneously. For instance, in a - desktop system, there might be one approver that displays a - notification-area icon, one that is part of a contact list - window and highlights contacts there, and one that is part - of a full-screen media player.</p> - - <p>Any approver can approve the handling of a channel dispatch operation - with a particular channel handler by calling the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">HandleWith</tp:dbus-ref> - method. Approvers can also attempt to <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Claim</tp:dbus-ref> - channels; if this succeeds, the approver may handle the channels - itself (if it is also a Handler), or close the channels in order to - reject them.</p> - - <p>At the D-Bus level, there is no "reject" operation: approvers wishing - to reject channels SHOULD call the Claim method, then (if it succeeds) - close the channels in any way they see fit.</p> - - <p>The first approver to reply gets its decision acted on; any other - approvers that reply at approximately the same time will get a D-Bus - error, indicating that the channel has already been dealt with.</p> - - <p>Approvers should usually prompt the user and ask for - confirmation, rather than dispatching the channel to a handler - straight away.</p> - - <p>Non-interactive approvers can also be implemented as - <tp:dbus-ref namespace="ofdT.Client">Observer</tp:dbus-ref>s as - described in the interface description.</p> - </tp:docstring> - - <property name="ApproverChannelFilter" - tp:name-for-bindings="Approver_Channel_Filter" - type="aa{sv}" access="read" tp:type="Channel_Class[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A specification of the channels in which this approver is - interested. The <tp:member-ref>AddDispatchOperation</tp:member-ref> - method should be called by the channel dispatcher whenever at least - one of the channels in a channel dispatch operation matches this - description.</p> - - <p>This property works in exactly the same way as the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer.ObserverChannelFilter</tp:dbus-ref> - property. In particular, it cannot change while the approver process - continues to own the corresponding Client bus name.</p> - - <p>In the .client file, it is represented in the - same way as ObserverChannelFilter, but the group has the same - name as this interface and the keys start with - ApproverChannelFilter instead of ObserverChannelFilter.</p> - </tp:docstring> - </property> - - <method name="AddDispatchOperation" - tp:name-for-bindings="Add_Dispatch_Operation"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Called by the channel dispatcher when a ChannelDispatchOperation - in which the approver has registered an interest is created, - or when the approver starts up while such channel dispatch - operations already exist.</p> - - <p>The channel dispatcher SHOULD call this method on all approvers - at the same time. If an approver returns an error from this method, - the approver is assumed to be faulty.</p> - - <p>If no approvers return from this method - successfully (including situations where there are no matching - approvers at all), the channel dispatcher SHOULD consider this - to be an error, and recover by dispatching the channel to the - most preferred handler.</p> - - <tp:rationale> - Processes that aren't approvers (or don't at least ensure that there - is some approver) probably shouldn't be making connections - anyway, so there should always be at least one approver running. - </tp:rationale> - </tp:docstring> - - <arg name="Channels" direction="in" - type="a(oa{sv})" tp:type="Channel_Details[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The initial value of the <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.Channels</tp:dbus-ref> - property, containing the <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s - to be dispatched and their properties.</p> - - <tp:rationale> - <p>This can't be signalled to the approver through the Properties - parameter of this method, because Channels is not an immutable - property.</p> - </tp:rationale> - - <p>This argument always contains all of the channels in the channel - dispatch operation, even if not all of them actually match - the <tp:member-ref>ApproverChannelFilter</tp:member-ref>.</p> - - <tp:rationale> - <p>This seems the least bad way to handle such a situation; - see the discussion on - <a href="http://bugs.freedesktop.org/show_bug.cgi?id=21090">bug - #21090</a>.</p> - </tp:rationale> - - <p>The actual channels to be dispatched may reduce as channels are - closed: this is signalled by <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.ChannelLost</tp:dbus-ref>. - </p> - - <p>Approvers SHOULD connect to ChannelLost and <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.Finished</tp:dbus-ref>. - (if desired) before returning from AddDispatchOperation, since - those signals are guaranteed not to be emitted until after all - AddDispatchOperation calls have returned (with success or failure) - or timed out.</p> - </tp:docstring> - </arg> - - <arg name="DispatchOperation" type="o" direction="in"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The - <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref> - to be processed.</p> - </tp:docstring> - </arg> - - <arg name="Properties" type="a{sv}" - tp:type="Qualified_Property_Value_Map" direction="in"> - <tp:docstring> - <p>Properties of the channel dispatch operation. The keys MUST be - fully qualified D-Bus property names. This MUST NOT include - properties that could change, SHOULD include as many properties as - possible given that constraint, and MUST include at least the - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Account</tp:dbus-ref>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Connection</tp:dbus-ref> - and <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">PossibleHandlers</tp:dbus-ref> - properties.</p> - </tp:docstring> - </arg> - </method> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> |