diff options
Diffstat (limited to 'qt4/spec/Connection_Interface_Contact_List.xml')
| -rw-r--r-- | qt4/spec/Connection_Interface_Contact_List.xml | 1085 |
1 files changed, 0 insertions, 1085 deletions
diff --git a/qt4/spec/Connection_Interface_Contact_List.xml b/qt4/spec/Connection_Interface_Contact_List.xml deleted file mode 100644 index 033c64d1d..000000000 --- a/qt4/spec/Connection_Interface_Contact_List.xml +++ /dev/null @@ -1,1085 +0,0 @@ -<?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"> - <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <tp:added version="0.21.0">(as stable API)</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.20 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>GetContactListAttributes</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>GetContactListAttributes</tp:member-ref> method - will fail until the contact list is available. - Using a method also allows extra attributes to be retrieved at - the same time.</p> - </tp:rationale> - </tp:docstring> - - <tp:enum name="Contact_List_State" type="u"> - <tp:docstring> - The progress made in retrieving the contact list. - </tp:docstring> - - <tp:enumvalue suffix="None" value="0"> - <tp:docstring>The connection has not started to retrieve the contact - list. If <tp:member-ref>GetContactListAttributes</tp:member-ref> is - called in this state, it will raise NotYet.</tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Waiting" value="1"> - <tp:docstring>The connection has started to retrieve the contact - list, but has not yet succeeded or failed. - If <tp:member-ref>GetContactListAttributes</tp:member-ref> is called - in this state, it will raise NotYet.</tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Failure" value="2"> - <tp:docstring> - <p>The connection has tried and failed to retrieve the contact - list. If <tp:member-ref>GetContactListAttributes</tp:member-ref> - is called in this state, it will immediately raise an error - indicating the reason for failure.</p> - - <p>The connection manager SHOULD try again to obtain the contact - list, if appropriate for the protocol. If it succeeds later, - the <tp:member-ref>ContactListState</tp:member-ref> MUST advance - to Success.</p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Success" value="3"> - <tp:docstring>The connection has successfully retrieved the contact - list. If <tp:member-ref>GetContactListAttributes</tp:member-ref> - is called in this state, it will return successfully.</tp:docstring> - </tp:enumvalue> - </tp:enum> - - <property name="ContactListState" tp:name-for-bindings="Contact_List_State" - type="u" tp:type="Contact_List_State" access="read"> - <tp:docstring> - The progress made in retrieving the contact list. - Change notification is via - <tp:member-ref>ContactListStateChanged</tp:member-ref>. - </tp:docstring> - </property> - - <signal name="ContactListStateChanged" - tp:name-for-bindings="Contact_List_State_Changed"> - <tp:docstring> - Emitted when <tp:member-ref>ContactListState</tp:member-ref> - changes. - </tp:docstring> - - <arg name="Contact_List_State" type="u" tp:type="Contact_List_State"> - <tp:docstring> - The new value of <tp:member-ref>ContactListState</tp:member-ref>. - </tp:docstring> - </arg> - </signal> - - <method name="GetContactListAttributes" - tp:name-for-bindings="Get_Contact_List_Attributes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Return some contact attributes for a list of contacts - associated with the user. This list MUST include at least:</p> - - <ul> - <li>all contacts whose <tp:token-ref>subscribe</tp:token-ref> - attribute is not No</li> - <li>all contacts whose <tp:token-ref>publish</tp:token-ref> - attribute is not No</li> - </ul> - - <p>but MAY contain other contacts.</p> - - <tp:rationale> - <p>For instance, on XMPP, all contacts on the roster would appear - here even if they have subscription="none", unless there's - reason to believe the user does not want to see them (such as - having been blocked).</p> - </tp:rationale> - - <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, unless they still - have a non-<tt>No</tt> <tp:token-ref>subscribe</tp:token-ref> or - <tp:token-ref>publish</tp:token-ref> attribute - for some reason.</p> - - <tp:rationale> - <p>It's reasonable to assume that blocked contacts should not be - visible to the user unless they specifically go looking for them, - at least in protocols like XMPP where blocking a contact - suppresses presence.</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>If true, all handles that appear as keys in the result have been - held on behalf of the calling process, as if by a call to - <tp:dbus-ref namespace="ofdT">Connection.HoldHandles</tp:dbus-ref>. - (If <tp:dbus-ref namespace="ofdT.Connection" - >HasImmortalHandles</tp:dbus-ref> is true, which SHOULD be the - case in all new connection managers, this has no effect.)</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.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> - <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotYet"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The <tp:member-ref>ContactListState</tp:member-ref> is - None or Waiting. In particular, this error is raised if the - <tp:dbus-ref namespace="ofdT.Connection">Status</tp:dbus-ref> - is not yet Connection_Status_Connected.</p> - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <tp:enum name="Subscription_State" type="u"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An enumeration indicating whether presence subscription is denied, - denied but pending permission, or allowed. The exact semantics - vary according to where this type is used: see the - <tp:token-ref>subscribe</tp:token-ref> and - <tp:token-ref>publish</tp:token-ref> contact attributes for - details.</p> - </tp:docstring> - - <tp:enumvalue suffix="Unknown" value="0"> - <tp:docstring>The presence subscription state is - unknown.</tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="No" value="1"> - <tp:docstring>Presence information cannot be seen, and either the - subscription state Removed_Remotely does not apply, or it is - not known whether that state applies. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Removed_Remotely" value="2"> - <tp:docstring>Presence information cannot be seen because the - remote contact took action: either the local user's request to - see the remote contact's presence was denied, or the remote - contact requested to see the local user's presence but then - cancelled their request.</tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Ask" value="3"> - <tp:docstring>Presence information cannot be seen. Permission - to see presence information has been requested, and the request - has not yet been declined or accepted.</tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Yes" value="4"> - <tp:docstring>Presence information can be seen.</tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:contact-attribute name="subscribe" - type="u" tp:type="Subscription_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 not Yes, 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>If this attribute is Removed_Remotely, this indicates that the - local user has asked to receive the contact's presence at some time, - but the remote contact has rejected that request, and a local - user interface has not yet acknowledged this. It is - implementation-dependent whether contacts' subscribe attributes can - remain set to Removed_Remotely, or are reset to No, when the - connection disconnects.</p> - - <p>After notifying the user, user interfaces MAY acknowledge a change - to <tt>subscribe</tt>=Removed_Remotely by calling either - <tp:member-ref>Unsubscribe</tp:member-ref> or - <tp:member-ref>RemoveContacts</tp:member-ref>, which will set - <tt>subscribe</tt> to No (and perhaps remove the contact). This - allows user interfaces to detect that the user has been notified - about the rejected request.</p> - - <p>This attribute's value will be Unknown or omitted until the - <tp:member-ref>ContactListState</tp:member-ref> has changed to - Success.</p> - </tp:docstring> - </tp:contact-attribute> - - <tp:contact-attribute name="publish" - type="u" tp:type="Subscription_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 not Yes, 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' <tt>publish</tt> - 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>If this attribute is Removed_Remotely, this indicates that the - remote contact has asked to receive the user's presence at some time, - but has then cancelled that request before a response was given by - the local user. User interfaces MAY reset <tt>publish</tt> from - Removed_Remotely to No, by calling either - <tp:member-ref>Unpublish</tp:member-ref> or - <tp:member-ref>RemoveContacts</tp:member-ref>.</p> - - <p>If multiple factors affect whether a contact can receive the local - user's presence, this attribute SHOULD reflect the overall - result. For instance, an XMPP contact with subscription="to" or - subscription="both", but who has been blocked via - <a href="http://xmpp.org/extensions/xep-0016.html">XEP-0016 Privacy - Lists</a>, SHOULD have publish=No.</p> - - <p>This attribute's value will be Unknown or omitted until the - <tp:member-ref>ContactListState</tp:member-ref> has changed to - Success.</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 <tp:token-ref>publish</tp:token-ref> 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 will also be omitted until the - <tp:member-ref>ContactListState</tp:member-ref> has changed to - Success.</p> - </tp:docstring> - </tp:contact-attribute> - - <property name="ContactListPersists" - tp:name-for-bindings="Contact_List_Persists" 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>CanChangeContactList</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 - ContactListPersists is false, clients MAY do this for all contacts; - if ContactListPersists is true, clients SHOULD NOT change the state - of contacts that were not changed locally.</p> - - <tp:rationale> - <p>In SIMPLE (SIP), ContactListPersists is false, but - CanChangeContactList 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 xmlns="http://www.w3.org/1999/xhtml"> - <p>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.</p> - - <p>On some protocols, certain metadata (for instance, contact aliases) - can only be stored for contacts on the contact list, or contacts - with a particular contact list state.</p> - - <p>To make it easier to deal with such protocols, if clients set - metadata on a contact who is not in the required state, the - Connection MUST cache the metadata for the duration of the session. - If clients request the attributes of that contact after the - appropriate "set" method has returned successfully, the Connection - MUST return the new (cached) value.</p> - - <p>If the contact is later placed in the required state to store - metadata (for instance, if subscription to the contact's presence - is requested, on a protocol like MSN where the alias has storage type - Subscribed_Or_Pending), the connection MUST store the cached - metadata at that time.</p> - - <tp:rationale> - <p>If the Connection didn't cache changes in this way, a client - intending to change the alias on MSN would have to wait until - the server acknowledged the subscription request; in the meantime, - other clients would still display the old alias.</p> - </tp:rationale> - - <p>The only exception to that general rule is that if the Connection - cannot store particular metadata at all (i.e. the - storage type is None), it MUST reject attempts to set it.</p> - - <tp:rationale> - <p>If the implementation knows that metadata can't be stored at - all, it's useful to report that, which can be done - synchronously. In general, user interfaces should detect - storage type None and not display editing controls at all.</p> - </tp:rationale> - </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> - </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> - </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="Subscription_State"> - <tp:docstring> - The new value of the contact's "subscribe" attribute. - </tp:docstring> - </tp:member> - - <tp:member name="Publish" type="u" tp:type="Subscription_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="ContactsChangedWithID" - tp:name-for-bindings="Contacts_Changed_With_ID"> - <tp:added version="0.21.8"/> - <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>GetContactListAttributes</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' <tp:token-ref>subscribe</tp:token-ref>, - <tp:token-ref>publish</tp:token-ref> and - <tp:token-ref>publish-request</tp:token-ref> attributes.</p> - </tp:rationale> - - <p>Connection managers SHOULD also emit this signal when a contact - requests that the user's presence is published to them, even if - that contact's <tp:token>publish</tp:token> attribute is already - Ask and the <tp:token>publish-request</tp:token> has not changed.</p> - - <tp:rationale> - <p>If the same contact sends 10 identical requests, 10 identical - signals should be emitted.</p> - </tp:rationale> - </tp:docstring> - - <arg type="a{u(uus)}" name="Changes" tp:type="Contact_Subscription_Map"> - <tp:docstring> - The new <tp:token-ref>subscribe</tp:token-ref>, - <tp:token-ref>publish</tp:token-ref> and - <tp:token-ref>publish-request</tp:token-ref> attributes of all the - contacts that have been added, and all the contacts for which those - attributes have changed. - </tp:docstring> - </arg> - - <arg name="Identifiers" type="a{us}" tp:type="Handle_Identifier_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The identifiers of the contacts in the <var>Changes</var> map. - </tp:docstring> - </arg> - - <arg name="Removals" type="a{us}" tp:type="Handle_Identifier_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The contacts that have been removed from the list that would be - returned by - <tp:member-ref>GetContactListAttributes</tp:member-ref>. - This also implies that they have subscribe = No and publish = No; - contacts MUST NOT be listed both here and in <var>Changes</var>. - </tp:docstring> - </arg> - </signal> - - <signal name="ContactsChanged" - tp:name-for-bindings="Contacts_Changed"> - <tp:deprecated version="0.21.8">Connection managers MUST still - emit this signal, but clients SHOULD listen for the - <tp:member-ref>ContactsChangedWithID</tp:member-ref> signal in - addition, and ignore this signal after ContactsChangedWithID has been - emitted at least once. - </tp:deprecated> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted immediately after - <tp:member-ref>ContactsChangedWithID</tp:member-ref>, under the same - circumstances.</p> - - <p>If clients receive this signal without first receiving a - corresponding <tp:member-ref>ContactsChangedWithID</tp:member-ref>, - they MUST assume that only this signal will be emitted.</p> - </tp:docstring> - - <arg type="a{u(uus)}" name="Changes" tp:type="Contact_Subscription_Map"> - <tp:docstring> - The same as the corresponding argument to - <tp:member-ref>ContactsChangedWithID</tp:member-ref>. - </tp:docstring> - </arg> - - <arg name="Removals" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - The same as the corresponding argument to - <tp:member-ref>ContactsChangedWithID</tp:member-ref>, except that it - only includes handles and not identifiers. - </tp:docstring> - </arg> - </signal> - - <property name="CanChangeContactList" type="b" access="read" - tp:name-for-bindings="Can_Change_Contact_List"> - <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>Connection managers SHOULD NOT attempt to enforce a - mutual-subscription policy (i.e. when this method is called, they - should not automatically allow the contacts to see the local user's - presence). User interfaces that require mutual subscription - MAY call <tp:member-ref>AuthorizePublication</tp:member-ref> - at the same time as this method.</p> - - <tp:rationale> - <p>Whether to enforce mutual subscription is a matter of policy, - so it is left to the user interface and/or the server.</p> - </tp:rationale> - - <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>.</p> - - <p>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 or subscribe=Rejected, this method - SHOULD request that the contact allows the local user to subscribe - to their presence; in general, this will change their publish - attribute to Ask (although it could change directly 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.</p> - - <p>If the remote contact explicitly rejects the request (in protocols - that allow this), their subscribe attribute will later change from - Ask to Rejected.</p> - - <p>If the subscription request is cancelled by the local user, the - contact's subscribe attribute will change from Ask to No.</p> - - <p>This method SHOULD NOT be called until the - <tp:member-ref>ContactListState</tp:member-ref> changes to Success. - If the <tp:member-ref>ContactListState</tp:member-ref> changes to - Failure, this method SHOULD raise the same error as - <tp:member-ref>GetContactListAttributes</tp:member-ref>.</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.NotYet"> - <tp:docstring> - The <tp:member-ref>ContactListState</tp:member-ref> is None - or Waiting. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - It was not possible to perform the requested action, because - <tp:member-ref>CanChangeContactList</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>Connection managers SHOULD NOT attempt to enforce a - mutual-subscription policy (i.e. when this method is called, they - should not automatically request that the contacts allow the user to - subscribe to their presence). User interfaces that require mutual - subscription MAY call - <tp:member-ref>RequestSubscription</tp:member-ref> at the same time - as this method.</p> - - <tp:rationale> - <p>Whether to enforce mutual subscription is a matter of policy, - so it is left to the user interface and/or the server.</p> - </tp:rationale> - - <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> - - <p>This method SHOULD NOT be called until the - <tp:member-ref>ContactListState</tp:member-ref> changes to Success. - If the <tp:member-ref>ContactListState</tp:member-ref> changes to - Failure, this method SHOULD raise the same error as - <tp:member-ref>GetContactListAttributes</tp:member-ref>.</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 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>CanChangeContactList</tp:member-ref> is false. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotYet"> - <tp:docstring> - The <tp:member-ref>ContactListState</tp:member-ref> is None - or Waiting. - </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>GetContactListAttributes</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> - - <p>This method SHOULD NOT be called until the - <tp:member-ref>ContactListState</tp:member-ref> changes to Success. - If the <tp:member-ref>ContactListState</tp:member-ref> changes to - Failure, this method SHOULD raise the same error as - <tp:member-ref>GetContactListAttributes</tp:member-ref>.</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>CanChangeContactList</tp:member-ref> is false. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotYet"> - <tp:docstring> - The <tp:member-ref>ContactListState</tp:member-ref> is None - or Waiting. - </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> - - <p>This method SHOULD NOT be called until the - <tp:member-ref>ContactListState</tp:member-ref> changes to Success. - If the <tp:member-ref>ContactListState</tp:member-ref> changes to - Failure, this method SHOULD raise the same error as - <tp:member-ref>GetContactListAttributes</tp:member-ref>.</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>CanChangeContactList</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> - - <p>This method SHOULD NOT be called until the - <tp:member-ref>ContactListState</tp:member-ref> changes to Success. - If the <tp:member-ref>ContactListState</tp:member-ref> changes to - Failure, this method SHOULD raise the same error as - <tp:member-ref>GetContactListAttributes</tp:member-ref>.</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>CanChangeContactList</tp:member-ref> is false. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotYet"> - <tp:docstring> - The <tp:member-ref>ContactListState</tp:member-ref> is None - or Waiting. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> |