diff options
Diffstat (limited to 'spec/Connection_Interface_Contact_List.xml')
| -rw-r--r-- | spec/Connection_Interface_Contact_List.xml | 865 |
1 files changed, 865 insertions, 0 deletions
diff --git a/spec/Connection_Interface_Contact_List.xml b/spec/Connection_Interface_Contact_List.xml new file mode 100644 index 0000000..9db86aa --- /dev/null +++ b/spec/Connection_Interface_Contact_List.xml @@ -0,0 +1,865 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Contact_List" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009-2010 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.ContactList.DRAFT2" + tp:causes-havoc="experimental"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:added version="0.19.8">(draft 2)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for connections that have any concept of a list of + known contacts (roster, buddy list, friends list etc.)</p> + + <tp:rationale> + <p>On many protocols, there's a server-side roster (as in XMPP), + or a set of server-side lists that can be combined to form a + roster (as in MSN).</p> + + <p>In some protocols (like link-local XMPP), while there might not be + any server or roster, it's possible to list "nearby" contacts.</p> + + <p>In Telepathy 0.18 and older, we represented contact lists as a + collection of <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type" + >ContactList</tp:dbus-ref> channels. This is remarkably difficult to + work with in practice - every client that cares about contact lists + has to take the union of some hard-to-define set of these + channels - and conflicts with the idea that channels that cannot + be dispatched to a handler should be closed.</p> + </tp:rationale> + + <p>The list of contacts is not exposed as a D-Bus property; it can be + fetched using <tp:member-ref>RequestContactList</tp:member-ref>. + </p> + + <tp:rationale> + <p>In some protocols, such as XMPP, the contact list may not be + available immediately. The + <tp:member-ref>RequestContactList</tp:member-ref> method + will wait until the contact list is available before returning. + Using a method also allows extra attributes to be retrieved at + the same time.</p> + </tp:rationale> + </tp:docstring> + + <method name="RequestContactList" + tp:name-for-bindings="Request_Contact_List"> + <tp:changed version="0.19.8">(in draft: renamed from + GetContactListAttributes)</tp:changed> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Return some contact attributes for a list of contacts somehow + associated with the user.</p> + + <p>This definition is deliberately vague: in practice, most user + interfaces should display some subset of this list, by filtering it + by some contact attributes (for instance, displaying all contacts + whose "subscribe" attribute is Yes is expected to be a common case). + This list MAY contain any contacts whatsoever, but MUST contain + at least the following:</p> + + <ul> + <li>all contacts whose "subscribe" attribute is Ask or Yes</li> + <li>all contacts whose "publish" attribute is Ask or Yes</li> + <li>all contacts with a persistently-stored stored alias, if + supported</li> + <li>all contacts in user-defined contact groups, if supported</li> + </ul> + + <p>This list does not need to contain every visible contact: for + instance, contacts seen in XMPP or IRC chatrooms SHOULD NOT appear + here. Blocked contacts SHOULD NOT appear here either, unless they + are still stored in a persistent roster/contact list as well as + being blocked.</p> + + <tp:rationale> + <p>This is basically the union of the historical <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type" + >ContactList</tp:dbus-ref> subscribe, publish and stored + channels.</p> + + <p>For example, XMPP, it's the roster; on link-local XMPP, it's the + set of visible users on the local network; on MSN, it's the union + of the forward and reverse buddy lists.</p> + + <p>An easy way for an application to display a contact list is to + call this method with at least this interface in the Interfaces + argument, then check which subset of contacts should be displayed + (perhaps based on their subscribe attribute, for instance) and display + them. Any additional information required to display the contact + list, like aliases or presence, can be retrieved at the same + time.</p> + + <p>In practice, most user interfaces for the contact list will + usually display a large proportion of this list + (for instance, most contacts on the contact list will usually + have subscribe=Yes in practice, so contact lists that display + subscribe=Yes contacts need to display almost the entire list), + so the overhead of returning information about too many contacts + is small.</p> + </tp:rationale> + + <p>This method SHOULD NOT return before the contact list has been + retrieved, on protocols where this is possible. As a result, + clients SHOULD use a longer-than-default timeout for this method + call, since retrieving the contact list can take a significant + time on some servers.</p> + + <tp:rationale> + <p>This makes it possible for clients to wait for the contact list. + For instance, on XMPP this method shouldn't return until the + roster has been retrieved, which is an asynchronous process. + However, on link-local XMPP you can't know when you have the + complete list, so this method would have to return immediately.</p> + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Interfaces" type="as" + tp:type="DBus_Interface[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of strings indicating which D-Bus interfaces the calling + process is interested in. Equivalent to the corresponding argument + to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts" + >GetContactAttributes</tp:dbus-ref>, + except that if this list does not contain the ContactList + interface itself, it is treated as though that interface was also + requested.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="Hold" type="b"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Whether to hold the handles on behalf of the calling process. + Equivalent to the corresponding argument to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts" + >GetContactAttributes</tp:dbus-ref>.</p> + + <p><em>FIXME: if we do distributed refcounting, we should probably + rename this to 'Reference' and implement handle-refcounting + semantics first? On the other hand, if we make handles persist + for the lifetime of the connection, we can just remove this + parameter.</em></p> + </tp:docstring> + </arg> + + <arg direction="out" type="a{ua{sv}}" name="Attributes" + tp:type="Contact_Attributes_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary mapping the contact handles to contact attributes, + equivalent to the result of <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts" + >GetContactAttributes</tp:dbus-ref>.</p> + + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + </tp:possible-errors> + </method> + + <tp:enum name="Presence_State" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A tristate indicating whether presence subscription is denied, + denied but pending permission, or allowed. The exact semantics + vary according to where this type is used.</p> + </tp:docstring> + + <tp:enumvalue suffix="No" value="0"> + <tp:docstring>Presence information cannot be seen.</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Ask" value="1"> + <tp:docstring>Presence information cannot be seen, but permission + to see presence information has been requested.</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Yes" value="2"> + <tp:docstring>Presence information can be seen.</tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:contact-attribute name="subscribe" + type="u" tp:type="Presence_State"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If this attribute on a contact is Yes, this connection can + expect to receive their presence, along with any other information + that has the same access control.</p> + + <tp:rationale> + <p>This is subscription="from" or subscription="both" in XMPP, + the "forward list" on MSN, or the contact being "added to + the local user's buddy list" in ICQ, for example.</p> + </tp:rationale> + + <p>If this attribute is No or Ask, the local user cannot generally + expect to receive presence from this contact. Their presence status + as returned by <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence">GetPresences</tp:dbus-ref> + is likely to be (Unknown, "unknown", ""), unless the local user + can temporarily see their presence for some other reason (for + instance, on XMPP, contacts seen in chatrooms will temporarily + have available presence).</p> + + <p>If this attribute is Ask, this indicates that the local user has + asked to receive the contact's presence at some time. It is + implementation-dependent whether contacts' subscribe attributes + can remain set to Ask, or are reset to No, when the connection + disconnects.</p> + + <tp:rationale> + <p>Some protocols store the fact that we wishes to see a contact's + presence; on these protocols, this attribute can remain Ask + indefinitely. On other protocols, only contacts who have been + asked during the current session will ever have Ask status.</p> + </tp:rationale> + + <p>This attribute SHOULD be omitted from the + <tp:type>Contact_Attributes_Map</tp:type> returned by + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts" + >GetContactAttributes</tp:dbus-ref> until the initial contact + list has been received, in protocols where this is applicable. + Clients MAY wait for this by calling + <tp:member-ref>RequestContactList</tp:member-ref>.</p> + </tp:docstring> + </tp:contact-attribute> + + <tp:contact-attribute name="publish" + type="u" tp:type="Presence_State"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If this attribute on a contact is Yes, the local user's presence + is published to that contact, along with any other information that + shares an access-control mechanism with presence (depending on + protocol, server configuration and/or user configuration, this may + include avatars, "rich presence" such as location, etc.).</p> + + <tp:rationale> + <p>This is subscription="to" or subscription="both" in XMPP, + the "reverse list" on MSN, or the state of "being added to + the contact's buddy list" in ICQ, for example.</p> + </tp:rationale> + + <p>If this attribute is No or Ask, the + local user's presence is not published to that contact; however, + if it is Ask, the contact has requested that the local user's + presence is made available to them.</p> + + <p>It is implementation-dependent whether contacts' publish + attributes can remain set to Ask, or are reset to No, when the + connection disconnects.</p> + + <tp:rationale> + <p>Some protocols store the fact that a contact wishes to see our + presence; on these protocols, this attribute can remain Ask + indefinitely. On other protocols, only contacts who have asked + during the current session will ever have Ask status.</p> + </tp:rationale> + + <p>This attribute SHOULD be omitted from the + <tp:type>Contact_Attributes_Map</tp:type> returned by + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts" + >GetContactAttributes</tp:dbus-ref> until the initial contact + list has been received, in protocols where this is applicable. + Clients MAY wait for this by calling + <tp:member-ref>RequestContactList</tp:member-ref>.</p> + </tp:docstring> + </tp:contact-attribute> + + <tp:contact-attribute name="publish-request" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If the "publish" attribute is Ask, an optional message that was + sent by the contact asking to receive the local user's presence; + omitted if none was given.</p> + + <tp:rationale> + <p>If the contact asking to receive our presence is also using + Telepathy, this is the message they supplied as the Message + argument to <tp:member-ref>RequestSubscription</tp:member-ref>.</p> + </tp:rationale> + + <p>Otherwise, this SHOULD be omitted.</p> + + <p>This attribute SHOULD be omitted from the + <tp:type>Contact_Attributes_Map</tp:type> returned by + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts" + >GetContactAttributes</tp:dbus-ref> until the initial contact + list has been received. Clients MAY wait for this by calling + <tp:member-ref>RequestContactList</tp:member-ref>.</p> + </tp:docstring> + </tp:contact-attribute> + + <property name="SubscriptionsPersist" + tp:name-for-bindings="Subscriptions_Persist" type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, presence subscriptions (in both directions) on this + connection are stored by the server or other infrastructure.</p> + + <tp:rationale> + <p>XMPP, MSN, ICQ, etc. all behave like this.</p> + </tp:rationale> + + <p>If false, presence subscriptions on this connection are not + stored.</p> + + <tp:rationale> + <p>In SIMPLE (SIP), <em>clients</em> are expected to keep a record + of subscriptions, as described below. In link-local XMPP, + subscriptions are implicit (everyone on the local network receives + presence from everyone else) so nothing is ever stored.</p> + </tp:rationale> + + <p>If <tp:member-ref>CanChangeSubscriptions</tp:member-ref> + is true, Telepathy clients (e.g. user interfaces or address books) + MAY keep a record of permission to publish and requests to subscribe + locally, and attempt to restore it for each Connection. If + SubscriptionsPersist is false, clients MAY do this for all contacts; + if SubscriptionsPersist is true, clients SHOULD NOT change the state + of contacts that were not changed locally.</p> + + <tp:rationale> + <p>In SIMPLE (SIP), SubscriptionsPersist is false, but + CanChangeSubscriptions is true. Presence will not be received + unless clients renew any subscriptions they have for each + connection, in the way described. There is no server-side storage, + so clients have no alternative but to maintain independent contact + lists.</p> + + <p>In protocols like XMPP and MSN, it may be useful for clients to + queue up subscription requests or removals made while offline and + process them next time the connection is online. However, clients + should only replay the changes, rather than resetting the contact + list to match a stored copy, to avoid overwriting changes that + were made on the server.</p> + </tp:rationale> + + <p>Clients that replay requests like this SHOULD do so by calling + AuthorizePublication to pre-approve publication of presence to the + appropriate contacts, followed by RequestSubscription to request the + appropriate contacts' presences.</p> + + <p>This property cannot change after the connection has moved to the + Connected state. Until then, its value is undefined, and it may + change at any time, without notification.</p> + </tp:docstring> + </property> + + <tp:enum name="Contact_Metadata_Storage_Type" type="u"> + <tp:docstring> + Values of this enumeration indicate the extent to which metadata + such as aliases and group memberships can be stored for the contacts + on a particular connection. + </tp:docstring> + + <tp:enumvalue suffix="None" value="0"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This connection cannot store this type of metadata at all, and + attempting to do so will fail with NotImplemented.</p> + + <tp:rationale> + <p>Link-local XMPP can't store aliases or group memberships at + all, and subscription and presence states are implicit (all + contacts on the local network have subscribe = publish = Yes + and no other contacts exist).</p> + + <p>As of April 2010, the XMPP server for Facebook Chat provides a + read-only view of the user's Facebook contacts, so it could also + usefully have this storage type.</p> + </tp:rationale> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Subscribed_Or_Pending" value="1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This type of metadata can only be stored permanently for contacts + whose subscribe attribute is Ask or Yes.</p> + + <tp:rationale> + <p>Contact aliases and groups on MSN have this behaviour.</p> + </tp:rationale> + + <p>If this type of metadata is set on a contact with subscribe=No, + the Connection MUST cache it until disconnected, and return it + if requested. If subscription to the contact's presence is + subsequently requested, making it possible to store this metadata, + the Connection MUST store the cached value at that time.</p> + + <tp:rationale> + <p>This supports the recommended calling pattern for adding a + new contact, in which alias and groups are set (without + necessarily waiting for a reply) before requesting the + contact's presence. Until the subscription request is + processed by the server, the alias and groups will be cached + in memory; when the subscription request has been processed, + the connection manager will store the metadata on the server.</p> + </tp:rationale> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Subscribed" value="2"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This type of metadata can only be stored permanently for contacts + whose subscribe attribute is Yes.</p> + + <tp:rationale> + <p>No service with this behaviour is currently known, but it's a + stricter form of Subscribed_Or_Pending.</p> + </tp:rationale> + + <p>If this type of metadata is set on a contact with subscribe != Yes, + the Connection MUST cache it until disconnected, and return it + if requested. If subscription to the contact's presence is + subsequently allowed, making it possible to store this metadata, + the Connection MUST store the cached value at that time.</p> + + <tp:rationale> + <p>The same rationale applies as for Subscribed_Or_Pending, + except that metadata must be stored until the subscription + request is not only processed by the server, but also allowed + by the remote user.</p> + </tp:rationale> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Anyone" value="3"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The user can set this metadata for any valid contact identifier, + whether or not they have any presence subscription relationship + to it, and it will be stored on their contact list.</p> + + <tp:rationale> + <p>Contact aliases and groups on XMPP have this behaviour; it + is possible to put a contact in a group, or assign an alias + to them, without requesting that presence be shared.</p> + </tp:rationale> + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:struct name="Contact_Subscriptions" array-name=""> + <tp:docstring> + A single contact's subscribe, publish and publish-request attributes. + </tp:docstring> + + <tp:member name="Subscribe" type="u" tp:type="Presence_State"> + <tp:docstring> + The new value of the contact's "subscribe" attribute. + </tp:docstring> + </tp:member> + + <tp:member name="Publish" type="u" tp:type="Presence_State"> + <tp:docstring> + The new value of the contact's "publish" attribute. + </tp:docstring> + </tp:member> + + <tp:member name="Publish_Request" type="s"> + <tp:docstring> + The new value of the contact's "publish-request" attribute, + or the empty string if that attribute would be omitted. + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:mapping name="Contact_Subscription_Map" array-name=""> + <tp:docstring> + A map from contacts to their subscribe, publish and publish-request + attributes. + </tp:docstring> + + <tp:member name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact's handle. + </tp:docstring> + </tp:member> + + <tp:member name="States" type="(uus)" tp:type="Contact_Subscriptions"> + <tp:docstring> + The contact's subscribe, publish and publish-request attributes. + </tp:docstring> + </tp:member> + </tp:mapping> + + <signal name="ContactsChanged" + tp:name-for-bindings="Contacts_Changed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when the contact list becomes available, when contacts' + basic stored properties change, when new contacts are added to the + list that would be returned by + <tp:member-ref>RequestContactList</tp:member-ref>, + or when contacts are removed from that list.</p> + + <tp:rationale> + <p>This provides change notification for that list, and for + contacts' "subscribe", "publish" and + "publish-request" attributes.</p> + </tp:rationale> + </tp:docstring> + + <arg type="a{u(uus)}" name="Changes" tp:type="Contact_Subscription_Map"> + <tp:docstring> + The new subscribe, publish and publish-request attributes of all the + contacts that have been added, and all the contacts for which those + attributes have changed. + </tp:docstring> + </arg> + + <arg name="Removals" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + The contacts that have been removed from the list that would be + returned by + <tp:member-ref>RequestContactList</tp:member-ref>. + This also implies that they have subscribe = No and publish = No; + contacts MUST NOT be listed both here and in Changes. + </tp:docstring> + </arg> + </signal> + + <property name="CanChangeSubscriptions" type="b" access="read" + tp:name-for-bindings="Can_Change_Subscriptions"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, presence subscription and publication can be changed + using the + <tp:member-ref>RequestSubscription</tp:member-ref>, + <tp:member-ref>AuthorizePublication</tp:member-ref> and + <tp:member-ref>RemoveContacts</tp:member-ref> methods.</p> + + <p>If false, all of those methods will always fail; they SHOULD raise + the error org.freedesktop.Telepathy.Error.NotImplemented.</p> + + <tp:rationale> + <p>In XEP-0174 "Serverless Messaging" (link-local XMPP), presence is + implicitly published to everyone in the local subnet, so the user + cannot control their presence publication.</p> + </tp:rationale> + + <p>This property cannot change after the connection has moved to the + Connected state. Until then, its value is undefined, and it may + change at any time, without notification.</p> + </tp:docstring> + </property> + + <method name="RequestSubscription" tp:name-for-bindings="Request_Subscription"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that the given contacts allow the local user to + subscribe to their presence, i.e. that their subscribe attribute + becomes Yes.</p> + + <p>Before calling this method on a connection where <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing" + >GetAliasFlags</tp:dbus-ref> returns the <code>User_Set</code> flag, + user interfaces SHOULD obtain, from the user, an alias to + identify the contact in future, and store it using <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing" + >SetAliases</tp:dbus-ref>. + + The user MAY be + prompted using the contact's current self-assigned nickname, or + something derived from the contact's (presumably self-assigned) + identifier, as a default, but these names chosen by the contact + SHOULD NOT be used without user approval.</p> + + <tp:rationale> + <p>This is a generalization of + <a href="http://xmpp.org/extensions/xep-0165.html" + >XEP-0165 "Best Practices to Discourage JID Mimicking"</a>) + to protocols other than XMPP. A reasonable user interface for + this, as used in many XMPP clients, is to have a text entry + for the alias adjacent to the text entry for the identifier + to add.</p> + </tp:rationale> + + <p>For contacts with subscribe=Yes, this method has no effect. + It MUST return successfully if all contacts are in this state.</p> + + <p>For contacts with subscribe=Ask, this method SHOULD send a new + request, with the given message, if allowed by the underlying + protocol.</p> + + <p>For contacts with subscribe=No, this method SHOULD request that + the contact allows the local user to subscribe to their presence; + in general, this will change their publish attribute from No + to Ask (although it could change directly from No to Yes in some + situations).</p> + + <p>Any state changes that immediately result from this request MUST + be signalled via <tp:member-ref>ContactsChanged</tp:member-ref> + before this method returns.</p> + + <tp:rationale> + <p>This makes it easy for user interfaces to see what practical + effect this method had.</p> + </tp:rationale> + + <p>If the remote contact accepts the request, their subscribe + attribute will later change from Ask to Yes; if they explicitly + reject the request (in protocols that allow this), their subscribe + attribute will later change from Ask to No.</p> + </tp:docstring> + + <arg name="Contacts" direction="in" + type="au" tp:type="Contact_Handle[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>One or more contacts to whom requests are to be sent.</p> + </tp:docstring> + </arg> + + <arg name="Message" type="s" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An optional plain-text message from the user, to send to those + contacts with the subscription request. The + <tp:member-ref>RequestUsesMessage</tp:member-ref> property + indicates whether this message will be used or ignored.</p> + + <p>Clients SHOULD NOT send a non-empty message without first giving + the user an opportunity to edit it.</p> + + <tp:rationale> + <p>These messages are typically presented to the remote contact + as if the user had typed them, so as a minimum, the user should be + allowed to see what the UI will be saying on their behalf.</p> + </tp:rationale> + + <p>Connections where this message is not useful MUST still allow it to + be non-empty.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + It was not possible to perform the requested action, because + <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <property name="RequestUsesMessage" type="b" access="read" + tp:name-for-bindings="Request_Uses_Message"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, the Message parameter to + <tp:member-ref>RequestSubscription</tp:member-ref> is likely to be + significant, and user interfaces SHOULD prompt the user for a + message to send with the request; a message such as "I would like + to add you to my contact list", translated into the local user's + language, might make a suitable default.</p> + + <tp:rationale> + <p>This matches user expectations in XMPP and ICQ, for instance.</p> + </tp:rationale> + + <p>If false, the parameter is ignored; user interfaces SHOULD avoid + prompting the user, and SHOULD pass an empty string to + RequestSubscription.</p> + + <tp:rationale> + <p><em>FIXME: is there any such protocol?</em></p> + </tp:rationale> + </tp:docstring> + </property> + + <method name="AuthorizePublication" + tp:name-for-bindings="Authorize_Publication"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>For each of the given contacts, request that the local user's + presence is sent to that contact, i.e. that their publish attribute + becomes Yes.</p> + + <p>For contacts with publish=Yes, this method has no effect; it + MUST return successfully if all contacts given have this state.</p> + + <p>For contacts with publish=Ask, this method accepts the + contact's request to see the local user's presence, changing + their publish attribute from Ask to Yes.</p> + + <p>For contacts with publish=No, if the protocol allows it, this + method allows the contacts to see the local user's presence even + though they have not requested it, changing their publish attribute + from No to Yes. Otherwise, it merely records the fact that + presence publication to those contacts is allowed; if any of + those contacts ask to receive the local user's presence + later in the lifetime of the connection, the connection SHOULD + immediately allow them to do so, changing their publish + attribute directly from No to Yes.</p> + + <tp:rationale> + <p>This makes it easy to implement the common UI policy that if + the user attempts to subscribe to a contact's presence, requests + for reciprocal subscription are automatically approved.</p> + </tp:rationale> + + <p>Any state changes that immediately result from this request MUST + be signalled via <tp:member-ref>ContactsChanged</tp:member-ref> + before this method returns.</p> + + <tp:rationale> + <p>This makes it easy for user interfaces to see what practical + effect this method had.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Contacts" direction="in" + type="au" tp:type="Contact_Handle[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>One or more contacts to authorize.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + It was not possible to perform the requested action, because + <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="RemoveContacts" tp:name-for-bindings="Remove_Contacts"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Remove the given contacts from the contact list entirely. It is + protocol-dependent whether this works, and under which + circumstances.</p> + + <p>If possible, this method SHOULD set the contacts' subscribe and + publish attributes to No, remove any stored aliases for those + contacts, and remove the contacts from the result of + <tp:member-ref>RequestContactList</tp:member-ref>.</p> + + <p>This method SHOULD succeed even if it was not possible to carry out + the request entirely or for all contacts (for instance, if there is an + outstanding request to subscribe to the contact's presence, and it's + not possible to cancel such requests). However, all signals that + immediately result from this method call MUST be emitted before it + returns, so that clients can interpret the result.</p> + + <tp:rationale> + <p>User interfaces removing a contact from the contact list are + unlikely to want spurious failure notifications resulting from + limitations of a particular protocol. However, emitting the + signals first means that if a client does want to check exactly + what happened, it can wait for the method to return (while + applying change-notification signals to its local cache of the + contact list's state), then consult its local cache of the + contact list's state to see whether the contact is still there.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Contacts" direction="in" + type="au" tp:type="Contact_Handle[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>One or more contacts to remove.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + It was not possible to perform the requested action because + <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Unsubscribe" tp:name-for-bindings="Unsubscribe"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Attempt to set the given contacts' subscribe attribute to No, + i.e. stop receiving their presence.</p> + + <p>For contacts with subscribe=Ask, this attempts to cancel + an earlier request to subscribe to the contact's presence; for + contacts with subscribe=Yes, this attempts to + unsubscribe from the contact's presence.</p> + + <p>As with <tp:member-ref>RemoveContacts</tp:member-ref>, this method + SHOULD succeed even if it was not possible to carry out the request + entirely or for all contacts; however, all signals that + immediately result from this method call MUST be emitted before it + returns.</p> + </tp:docstring> + + <arg name="Contacts" direction="in" + type="au" tp:type="Contact_Handle[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>One or more contacts to remove.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + It was not possible to perform the requested action because + <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Unpublish" tp:name-for-bindings="Unpublish"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Attempt to set the given contacts' publish attribute to No, + i.e. stop sending presence to them.</p> + + <p>For contacts with publish=Ask, this method explicitly rejects the + contact's request to subscribe to the user's presence; for + contacts with publish=Yes, this method attempts to prevent the + user's presence from being received by the contact.</p> + + <p>As with <tp:member-ref>RemoveContacts</tp:member-ref>, this method + SHOULD succeed even if it was not possible to carry out the request + entirely or for all contacts; however, all signals that + immediately result from this method call MUST be emitted before it + returns.</p> + </tp:docstring> + + <arg name="Contacts" direction="in" + type="au" tp:type="Contact_Handle[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>One or more contacts to remove.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + It was not possible to perform the requested action because + <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |