diff options
Diffstat (limited to 'qt4/spec/Connection_Interface_Contact_Blocking.xml')
| -rw-r--r-- | qt4/spec/Connection_Interface_Contact_Blocking.xml | 207 |
1 files changed, 207 insertions, 0 deletions
diff --git a/qt4/spec/Connection_Interface_Contact_Blocking.xml b/qt4/spec/Connection_Interface_Contact_Blocking.xml new file mode 100644 index 000000000..756fd4db8 --- /dev/null +++ b/qt4/spec/Connection_Interface_Contact_Blocking.xml @@ -0,0 +1,207 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Contact_Blocking" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009–2011 Collabora Ltd.</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.ContactBlocking"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactList"/> + <tp:added version='0.21.13'>Changes from the draft: + methods and signals now return <tp:type>Handle_Identifier_Map</tp:type> + (<code>a{us}</code>) rather than bare lists of contact handles + (<code>au</code>)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for connections where contacts can be blocked from + communicating with this user and receiving this user's presence. + Clients may retrieve a list of currently-blocked contacts using + <tp:member-ref>RequestBlockedContacts</tp:member-ref>, and listen for + <tp:member-ref>BlockedContactsChanged</tp:member-ref> to be notified + when contacts are blocked and unblocked. The + <tp:member-ref>BlockContacts</tp:member-ref> and + <tp:member-ref>UnblockContacts</tp:member-ref> methods do what they say + on the tin; depending on the value of the + <tp:member-ref>ContactBlockingCapabilities</tp:member-ref> property, + contacts may be reported for spam or other abuse when calling + <tp:member-ref>BlockContacts</tp:member-ref>.</p> + + <p>This interface is intended for protocols where blocking contacts + persists on the server between connections; connection managers for + protocols with no server-side support for blocking contacts MAY choose + to implement this interface using an on-disk file of blocked + contacts or some other means to store blocked contacts between + connections.</p> + + <p>This interface is intended to replace the + <tp:dbus-ref namespace="ofdT.Channel.Type">ContactList</tp:dbus-ref> + channel with <tp:dbus-ref + namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref> + <code>List</code> and <tp:dbus-ref + namespace='ofdT.Channel'>TargetID</tp:dbus-ref> <code>"deny"</code> + (along with the <tp:dbus-ref + namespace='ofdT.Connection.Interface'>ContactList</tp:dbus-ref> and + <tp:dbus-ref + namespace='ofdT.Connection.Interface'>ContactGroups</tp:dbus-ref> + interfaces replacing other channels with <tp:dbus-ref + namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref> + <code>List</code> and <tp:dbus-ref + namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref> + <code>Group</code>, respectively).</p> + </tp:docstring> + + <method name="BlockContacts" tp:name-for-bindings="Block_Contacts"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Direct the server to block some contacts. The precise effect is + protocol-dependent, but SHOULD include ignoring all current and + subsequent communications from the given contacts, avoiding sending + presence to them in future, and if they were already receiving the + local user's presence, behaving as if the local user went + offline.</p> + </tp:docstring> + + <arg name="Contacts" type="au" direction="in" tp:type="Contact_Handle[]"> + <tp:docstring>Some contacts to block. If some of the contacts in this + list are already blocked, the connection manager MUST act as if they + were not specified in this list.</tp:docstring> + </arg> + + <arg name="Report_Abusive" type="b" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>In addition to blocking, report these contacts as abusive to the + server administrators.</p> + + <p>Clients can determine whether this capability is available by + checking the + <tp:member-ref>ContactBlockingCapabilities</tp:member-ref> + property. If this argument is set to <code>True</code> by a client + despite <tp:member-ref>ContactBlockingCapabilities</tp:member-ref> + not containing the <code>Can_Report_Abusive</code> flag, the + connection manager SHOULD act as if it were <code>False</code> and + simply block the supplied contacts.</p> + + <tp:rationale> + <p>A correct user interface shouldn't get this far without knowing + that reporting abusive contacts is not supported. If it does, + then the user has expressed their intention to block these + contacts. Returning an error would leave the UI with three + options:</p> + + <ul> + <li>Ignore the error, leaving the contacts not actually blocked;</li> + <li>Display an error to the user;</li> + <li>Call this method again, passing <code>False</code> for this + argument.</li> + </ul> + + <p>None of these seem preferable to the CM just ignoring this flag + if it doesn't support it: that way, the contacts will be blocked, + as the user requested, and UIs have fewer ways to mess up + entirely.</p> + </tp:rationale> + </tp:docstring> + </arg> + </method> + + <method name="UnblockContacts" tp:name-for-bindings="Unblock_Contacts"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Direct the server to unblock some contacts.</p> + </tp:docstring> + + <arg name="Contacts" type="au" direction="in" tp:type="Contact_Handle[]"> + <tp:docstring>Some contacts to unblock. If some of the contacts in this + list are not currently blocked, the connection manager MUST act as if + they were not specified in this list.</tp:docstring> + </arg> + </method> + + <method name="RequestBlockedContacts" + tp:name-for-bindings="Request_Blocked_Contacts"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>List the contacts that are blocked.</p> + + <p>Clients SHOULD allow a relatively long timeout for calls to this + method, since on some protocols contact blocking is part of the + contact list, which can take a significant time to retrieve.</p> + </tp:docstring> + + <arg name="Contacts" type="a{us}" direction="out" + tp:type="Handle_Identifier_Map"> + <tp:docstring>The blocked contacts’ handles, together with their + identifiers.</tp:docstring> + </arg> + </method> + + <signal name="BlockedContactsChanged" + tp:name-for-bindings="Blocked_Contacts_Changed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when the list of blocked contacts is first retrieved + (before returning from any pending calls to + <tp:member-ref>RequestBlockedContacts</tp:member-ref>), and + whenever the list of blocked contacts subsequently changes.</p> + </tp:docstring> + + <arg name="Blocked_Contacts" type="a{us}" tp:type="Handle_Identifier_Map"> + <tp:docstring>Contacts added to the result of + <tp:member-ref>RequestBlockedContacts</tp:member-ref>.</tp:docstring> + </arg> + + <arg name="Unblocked_Contacts" type="a{us}" + tp:type="Handle_Identifier_Map"> + <tp:docstring>Contacts removed from the result of + <tp:member-ref>RequestBlockedContacts</tp:member-ref>.</tp:docstring> + </arg> + </signal> + + <tp:contact-attribute name="blocked" type="b"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p><code>True</code> if the contact would be in the result of + <tp:member-ref>RequestBlockedContacts</tp:member-ref>; + <code>False</code> or omitted if the contact is not blocked, or if it + is unknown whether the contact is blocked.</p> + </tp:docstring> + </tp:contact-attribute> + + <property name="ContactBlockingCapabilities" + tp:name-for-bindings="Contact_Blocking_Capabilities" + tp:type="Contact_Blocking_Capabilities" type="u" access="read" + tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Additional capabilities for contact blocking; currently, this is + limited to whether contacts may be reported as abusive.</p> + + <p>Note that there is no capability for supporting blocking itself: + the presence of this interface on a <tp:dbus-ref + namespace='ofdT'>Connection</tp:dbus-ref> indicates that blocking + contacts is supported.</p> + </tp:docstring> + </property> + + <tp:flags name="Contact_Blocking_Capabilities" type="u" + value-prefix="Contact_Blocking_Capability"> + <tp:flag suffix="Can_Report_Abusive" value="1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + When calling <tp:member-ref>BlockContacts</tp:member-ref>, the + contacts may be reporting as abusive to the server administrators by + setting <var>Report_Abusive</var> to <code>True</code>. + </tp:docstring> + </tp:flag> + </tp:flags> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |