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.

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.

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.

This interface allows many attributes of many contacts to be obtained in a single D-Bus round trip.

Each contact attribute has an string identifier (Contact_Attribute), which is namespaced by the D-Bus interface which defines it.

A DBus_Interface, followed by a slash '/' character and an identifier for an attribute defined by that interface. The attribute identifier SHOULD be in lower case. These aren't D-Bus core Properties, and we want them to look visibly different.

Some of the attributes of a single contact. The name of the attribute The value of the attribute Mapping returned by GetContactAttributes, representing a collection of Contacts and their requested attributes. A contact Attributes of that contact A list of D-Bus interfaces for which GetContactAttributes is expected to work. This cannot change during the lifetime of the Connection. Return any number of contact attributes for the given handles. An array of handles representing contacts.

A list of strings indicating which D-Bus interfaces the calling process is interested in. All supported attributes from these interfaces, whose values can be obtained without additional network activity, will be in the reply.

Connection managers SHOULD ignore interfaces requested which they do not support (i.e. those not mentioned in the ContactAttributeInterfaces property.)

This simplifies client-side code. Clients which care may distinguish between unsupported interfaces (e.g. this Connection does not support Avatars), and interfaces on which no information is known for these contacts (e.g. we don't know the avatar tokens of any of the contacts, so we omitted them all) by inspecting ContactAttributeInterfaces.

Attributes from the interface org.freedesktop.Telepathy.Connection are always returned, and need not be requested explicitly.

As well as returning cached information immediately, the connection MAY start asynchronous requests to obtain better values for the contact attributes. If better values are later obtained by this process, they will be indicated with the usual signals (such as AliasesChanged).

For instance, an XMPP connection manager could download vCards in response to a request for Aliasing attributes. requesting information for interfaces not mentioned in ContactAttributeInterfaces is no longer an error. Be aware that older connection managers may still consider this an error. If true, all handles in the result have been held on behalf of the calling process, as if by a call to Connection.HoldHandles. For further round-trip avoidance.

A dictionary mapping the contact handles to contact attributes. If any of the requested handles are in fact invalid, they are simply omitted from this mapping. If contact attributes are not immediately known, the behaviour is defined by the interface; the attribute should either be omitted from the result or replaced with a default value.

Each contact's attributes will always include at least the identifier that would be obtained by inspecting the handle (org.freedesktop.Telepathy.Connection/contact-id).