diff options
Diffstat (limited to 'qt4/spec/Connection_Interface_Avatars.xml')
| -rw-r--r-- | qt4/spec/Connection_Interface_Avatars.xml | 516 |
1 files changed, 516 insertions, 0 deletions
diff --git a/qt4/spec/Connection_Interface_Avatars.xml b/qt4/spec/Connection_Interface_Avatars.xml new file mode 100644 index 000000000..3b9290e1d --- /dev/null +++ b/qt4/spec/Connection_Interface_Avatars.xml @@ -0,0 +1,516 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Avatars" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright> + <tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright (C) 2006 INdT</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.Avatars"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + + <tp:simple-type name="Avatar_Token" type="s" + array-name="Avatar_Token_List"> + <tp:changed version="0.17.16">strengthened uniqueness requirements + so (CM name, protocol, token) is unique; previously only + (our Account, remote contact identifier, token) was required to be + unique</tp:changed> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An opaque token chosen by the connection manager, representing + a particular avatar.</p> + + <tp:rationale> + <p>Because avatars can be relatively large images, most protocols + provide a way to detect whether an old avatar is still valid, + or whether an avatar has changed, without pushing the actual + avatar data to all clients.</p> + </tp:rationale> + + <p>The connection manager MUST choose these tokens in a way that + makes it highly unlikely that two different avatars with the same + connection manager and protocol will have the same token.</p> + + <tp:rationale> + <p>This means that clients MAY use the triple + (<tp:type>Connection_Manager_Name</tp:type>, + <tp:type>Protocol</tp:type>, avatar token) as a key for + their avatar cache. For instance, an avatar for a + telepathy-gabble Jabber contact might be stored in a file + .../gabble/jabber/4e199b4a1c40b497a95fcd1cd896351733849949.png.</p> + </tp:rationale> + + <p>For instance, some protocols (like XMPP) identify avatars by a + hash of the avatar data; in this case, the hash can be used as the + avatar token.</p> + + <p>Some protocols identify avatars by the timestamp of the last + change to the avatar; in these protocols it would be necessary for + the connection manager to encode both the timestamp and the + contact's identifier into the avatar token in order to ensure + uniqueness.</p> + + <p>This token SHOULD be kept short and reasonably suitable for use + in a filename, but MAY contain any UTF-8 character (so clients using + avatar tokens in filenames MUST be prepared to escape characters + that are not valid in filenames). Connection managers for protocols + where tokens would otherwise become inconveniently large or contain + many unsuitable characters SHOULD hash the identifying data to + generate the token.</p> + </tp:docstring> + </tp:simple-type> + + <tp:mapping name="Avatar_Token_Map"> + <tp:docstring>A dictionary whose keys are contact handles and whose + values are avatar tokens.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> + <tp:member type="s" tp:type="Avatar_Token" name="Token"/> + </tp:mapping> + + <signal name="AvatarUpdated" tp:name-for-bindings="Avatar_Updated"> + <arg name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + An integer handle for the contact whose avatar has changed + </tp:docstring> + </arg> + <arg name="New_Avatar_Token" tp:type="Avatar_Token" type="s"> + <tp:docstring> + Unique token for their new avatar + </tp:docstring> + </arg> + <tp:docstring> + Emitted when the avatar for a contact has been updated, or first + discovered on this connection. If the token differs from the token + associated with the client's cached avatar for this contact, the new + avatar should be requested with + <tp:member-ref>RequestAvatars</tp:member-ref>. + </tp:docstring> + </signal> + + <signal name="AvatarRetrieved" tp:name-for-bindings="Avatar_Retrieved"> + <arg name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact whose avatar has been retrieved + </tp:docstring> + </arg> + <arg name="Token" tp:type="Avatar_Token" type="s"> + <tp:docstring> + The token corresponding to the avatar + </tp:docstring> + </arg> + <arg name="Avatar" type="ay"> + <tp:docstring> + An array of bytes containing the image data + </tp:docstring> + </arg> + <arg name="Type" type="s"> + <tp:docstring> + A string containing the image MIME type (eg image/jpeg), or empty if + unknown + </tp:docstring> + </arg> + <tp:docstring> + Emitted when the avatar for a contact has been retrieved. + </tp:docstring> + </signal> + + <property name="SupportedAvatarMIMETypes" + tp:name-for-bindings="Supported_Avatar_MIME_Types" + type="as" access="read"> + <tp:added version="0.17.22">Fall back to calling + <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this + property fails.</tp:added> + <tp:docstring> + An array of supported MIME types (e.g. "image/jpeg"). + Clients MAY assume that the first type in this array is preferred. + This property cannot change after the Connection goes to the Connected + state. + </tp:docstring> + </property> + + <property name="MinimumAvatarHeight" + tp:name-for-bindings="Minimum_Avatar_Height" + type="u" access="read"> + <tp:added version="0.17.22">Fall back to calling + <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this + property fails.</tp:added> + <tp:docstring> + The minimum height in pixels of an avatar on this protocol, which MAY + be 0. + This property cannot change after the Connection goes to the Connected + state. + </tp:docstring> + </property> + + <property name="MinimumAvatarWidth" + tp:name-for-bindings="Minimum_Avatar_Width" + type="u" access="read"> + <tp:added version="0.17.22">Fall back to calling + <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this + property fails.</tp:added> + <tp:docstring> + The minimum width in pixels of an avatar on this protocol, which MAY + be 0. + This property cannot change after the Connection goes to the Connected + state. + </tp:docstring> + </property> + + <property name="RecommendedAvatarHeight" + tp:name-for-bindings="Recommended_Avatar_Height" + type="u" access="read"> + <tp:added version="0.17.22"/> + <tp:docstring> + The recommended height in pixels of an avatar on this protocol, or 0 if + there is no preferred height. + This property cannot change after the Connection goes to the Connected + state. + + <tp:rationale> + In XMPP a recommended width is given by the protocol specification; + in proprietary protocols, using the same avatar size as the + proprietary client is likely to lead to the best display to other + users. + </tp:rationale> + </tp:docstring> + </property> + + <property name="RecommendedAvatarWidth" + tp:name-for-bindings="Recommended_Avatar_Width" + type="u" access="read"> + <tp:added version="0.17.22"/> + <tp:docstring> + The recommended width in pixels of an avatar on this protocol, or 0 if + there is no preferred width. + This property cannot change after the Connection goes to the Connected + state. + + <tp:rationale> + The rationale is the same as for + <tp:member-ref>RecommendedAvatarHeight</tp:member-ref>. + </tp:rationale> + </tp:docstring> + </property> + + <property name="MaximumAvatarHeight" + tp:name-for-bindings="Maximum_Avatar_Height" + type="u" access="read"> + <tp:added version="0.17.22">Fall back to calling + <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this + property fails.</tp:added> + <tp:docstring> + The maximum height in pixels of an avatar on this protocol, or 0 if + there is no limit. + This property cannot change after the Connection goes to the Connected + state. + </tp:docstring> + </property> + + <property name="MaximumAvatarWidth" + tp:name-for-bindings="Maximum_Avatar_Width" + type="u" access="read"> + <tp:added version="0.17.22">Fall back to calling + <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this + property fails.</tp:added> + <tp:docstring> + The maximum width in pixels of an avatar on this protocol, or 0 if + there is no limit. + This property cannot change after the Connection goes to the Connected + state. + </tp:docstring> + </property> + + <property name="MaximumAvatarBytes" + tp:name-for-bindings="Maximum_Avatar_Bytes" + type="u" access="read"> + <tp:added version="0.17.22">Fall back to calling + <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this + property fails.</tp:added> + <tp:docstring> + The maximum size in bytes of an avatar on this protocol, or 0 if + there is no limit. + This property cannot change after the Connection goes to the Connected + state. + </tp:docstring> + </property> + + <method name="GetAvatarRequirements" + tp:name-for-bindings="Get_Avatar_Requirements"> + <tp:deprecated version="0.17.22">Use GetAll to retrieve the + D-Bus properties on this interface, falling back to this method + on failure.</tp:deprecated> + <arg direction="out" type="as" name="MIME_Types"> + <tp:docstring> + An array of supported MIME types (eg image/jpeg) + </tp:docstring> + </arg> + <arg direction="out" type="q" name="Min_Width"> + <tp:docstring> + The minimum image width in pixels + </tp:docstring> + </arg> + <arg direction="out" type="q" name="Min_Height"> + <tp:docstring> + The minimum image height in pixels + </tp:docstring> + </arg> + <arg direction="out" type="q" name="Max_Width"> + <tp:docstring> + The maximum image width in pixels, or 0 if there is no limit + </tp:docstring> + </arg> + <arg direction="out" type="q" name="Max_Height"> + <tp:docstring> + The maximum image height in pixels, or 0 if there is no limit + </tp:docstring> + </arg> + <arg direction="out" type="u" name="Max_Bytes"> + <tp:docstring> + The maximum image size in bytes, or 0 if there is no limit + </tp:docstring> + </arg> + <tp:docstring> + Get the required format of avatars on this connection. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> + </method> + + <method name="GetAvatarTokens" tp:name-for-bindings="Get_Avatar_Tokens"> + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + An array of handles representing contacts + </tp:docstring> + </arg> + <arg direction="out" type="as" name="Tokens" tp:type="Avatar_Token[]"> + <tp:docstring> + An array of avatar tokens or empty strings (if no avatar is set) in the + same order as the given array of contact handles + </tp:docstring> + </arg> + <tp:deprecated version="0.15.5">Use GetKnownAvatarTokens + instead.</tp:deprecated> + <tp:docstring> + Get the unique tokens for all of the given contacts' avatars. + + Using this method in new Telepathy clients is deprecated; use + <tp:member-ref>GetKnownAvatarTokens</tp:member-ref> instead. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> + </method> + + <method name="GetKnownAvatarTokens" + tp:name-for-bindings="Get_Known_Avatar_Tokens"> + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + An array of handles representing contacts + </tp:docstring> + </arg> + <arg direction="out" type="a{us}" name="Tokens" tp:type="Avatar_Token_Map"> + <tp:docstring> + A dictionary of handles mapped to avatar tokens, containing only + the known avatar tokens. + </tp:docstring> + </arg> + <tp:docstring> + Get the unique tokens for the given contacts' avatars. These tokens + can be persisted across connections, and should be used by the client + to check whether the avatars have been updated. For handles other than + the self handle, only tokens that are already known are returned; an + empty token means the given contact has no avatar. However, a CM must + always have the tokens for the self handle if one is set (even if it is + set to no avatar). On protocols where the avatar does not persist + between connections, a CM should omit the self handle from the returned + map until an avatar is explicitly set or cleared. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> + </method> + + <method name="RequestAvatar" tp:name-for-bindings="Request_Avatar"> + <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + An integer handle for the contact to request the avatar for + </tp:docstring> + </arg> + <arg direction="out" type="ay" name="Data"> + <tp:docstring> + An array of bytes containing the image data + </tp:docstring> + </arg> + <arg direction="out" type="s" name="MIME_Type"> + <tp:docstring> + A string containing the image MIME type (eg image/jpeg), or empty if + unknown + </tp:docstring> + </arg> + <tp:deprecated version="0.15.5">Use RequestAvatars + instead.</tp:deprecated> + <tp:docstring> + Request the avatar for a given contact. Using this method in new + Telepathy clients is deprecated; use RequestAvatars instead. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The contact does not currently have an avatar. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="RequestAvatars" tp:name-for-bindings="Request_Avatars"> + <arg direction="in" name="Contacts" type="au" + tp:type="Contact_Handle[]"> + <tp:docstring> + The contacts to retrieve avatars for + </tp:docstring> + </arg> + <tp:docstring> + Request avatars for a number of contacts. The + <tp:member-ref>AvatarRetrieved</tp:member-ref> signal is emitted for + each avatar retrieved. If the handles are valid but retrieving an + avatar fails (for any reason, including the contact not having an + avatar) the AvatarRetrieved signal is not emitted for that contact. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + </tp:possible-errors> + </method> + + <method name="SetAvatar" tp:name-for-bindings="Set_Avatar"> + <arg direction="in" name="Avatar" type="ay"> + <tp:docstring> + An array of bytes representing the avatar image data + </tp:docstring> + </arg> + <arg direction="in" name="MIME_Type" type="s"> + <tp:docstring> + A string representing the image MIME type + </tp:docstring> + </arg> + <arg direction="out" type="s" name="Token" tp:type="Avatar_Token"> + <tp:docstring> + The string token of the new avatar + </tp:docstring> + </arg> + <tp:docstring> + Set a new avatar image for this connection. The avatar image must + respect the requirements obtained by + <tp:member-ref>GetAvatarRequirements</tp:member-ref>. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> + </method> + + <method name="ClearAvatar" tp:name-for-bindings="Clear_Avatar"> + <tp:added version="0.15.0" /> + <tp:docstring> + Remove the avatar image for this connection. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <tp:contact-attribute name="token" type="s" tp:type="Avatar_Token"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same string that would be returned by + <tp:member-ref>GetKnownAvatarTokens</tp:member-ref> + (omitted from the result if the contact's avatar token is not known, + present as an empty string if the contact is known not to have + an avatar). Unlike in the + <tp:member-ref>GetKnownAvatarTokens</tp:member-ref> + method, the avatar tokens for the self handle aren't required to be + present. This attribute should not be used to determine whether or + not the Avatar needs to be set. + </p> + </tp:docstring> + </tp:contact-attribute> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for requesting avatars for contacts on a given connection, + receiving notification when avatars are changed, and publishing your own + avatar.</p> + + <p>Avatars are identified by a string, the <tp:type>Avatar_Token</tp:type>, + which represents a particular avatar. Tokens MUST be chosen by the + connection manager in such a way that the triple + (<tp:type>Connection_Manager_Name</tp:type>, <tp:type>Protocol</tp:type>, + <tp:type>Avatar_Token</tp:type>) uniquely identifies an avatar. + An empty token means that an avatar has not been set for this contact, and + a changed token implies the contact's avatar has changed, but the strings + should otherwise be considered opaque by clients.</p> + + <p>A client should use <tp:member-ref>GetKnownAvatarTokens</tp:member-ref> + to request the tokens for the + avatars of all the contacts it is interested in when it connects. The + avatars can then be requested using + <tp:member-ref>RequestAvatars</tp:member-ref> for the contacts. Clients + should bind to the <tp:member-ref>AvatarUpdated</tp:member-ref> signal and + request a new copy of + the avatar when a contacts' avatar token changes. Clients should cache the + token and data of each contact's avatar between connections, to avoid + repeatedly retrieving the same avatar.</p> + + <p>To publish an avatar, a client should use + <tp:member-ref>SetAvatar</tp:member-ref> to provide an image which meets + the requirements returned by the + <tp:member-ref>GetAvatarRequirements</tp:member-ref> + function. On some protocols the avatar is stored on the server, so setting + the avatar is persistent, but on others it is transferred via a peer to + peer mechanism, so needs to be set every connection. Hence, on every + connection, clients should inspect the avatar token of the connection's + self handle using <tp:member-ref>GetKnownAvatarTokens</tp:member-ref>; if + the self handle is not in the + returned map, the client should re-set the avatar. If the self handle's + avatar token is known, but the avatar has been changed locally since the + last connection, the client should upload the new avatar; if the avatar has + not changed locally, then the client should download the avatar from the + server if its token differs from the that of the local avatar.</p> + + <p>To remove the published avatar on protocols which have persistent avatars, + a client should use the <tp:member-ref>ClearAvatar</tp:member-ref> method. + This method can safely be used even if there is no avatar for this + connection.</p> + </tp:docstring> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |