Methods
| GetKnownAvatarTokens | (au: Contacts) | → | a{us}: Tokens | |
| RequestAvatars | (au: Contacts) | → | nothing | |
| SetAvatar | (ay: Avatar, s: MIME_Type) | → | s: Token | |
| ClearAvatar | () | → | nothing |
Signals
| AvatarUpdated | (u: Contact, s: New_Avatar_Token) | |
| AvatarRetrieved | (u: Contact, s: Token, ay: Avatar, s: Type) |
Properties
| SupportedAvatarMIMETypes | as | Read only | ||
| MinimumAvatarHeight | u | Read only | ||
| MinimumAvatarWidth | u | Read only | ||
| RecommendedAvatarHeight | u | Read only | ||
| RecommendedAvatarWidth | u | Read only | ||
| MaximumAvatarHeight | u | Read only | ||
| MaximumAvatarWidth | u | Read only | ||
| MaximumAvatarBytes | u | Read only |
Contact Attributes
| im.telepathy1.Connection.Interface.Avatars1/token | s (Avatar_Token) |
Types
| Avatar_Token | Simple Type | s | |
| Avatar_Token_Map | Mapping | a{us} |
Description
An interface for requesting avatars for contacts on a given connection, receiving notification when avatars are changed, and publishing your own avatar.
Avatars are identified by a string, the Avatar_Token, which represents a particular avatar. Tokens MUST be chosen by the connection manager in such a way that the triple (Connection_Manager_Name, Protocol_Name, Avatar_Token) 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.
A client should use GetKnownAvatarTokens 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 RequestAvatars for the contacts. Clients should bind to the AvatarUpdated 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.
To publish an avatar, a client should use SetAvatar to provide an image which meets the requirements returned by the the properties on the interface. 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 GetKnownAvatarTokens; 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.
To remove the published avatar on protocols which have persistent avatars, a client should use the ClearAvatar method. This method can safely be used even if there is no avatar for this connection.
Methods
GetKnownAvatarTokens (au: Contacts) → a{us}: Tokens
Parameters
- Contacts — au (Contact_Handle_List)
Returns
- Tokens — a{us} (Avatar_Token_Map)
Possible Errors
- Disconnected
- Network Error
- Invalid Argument
- Permission Denied
- Not Available
Rationale:
RequestAvatars (au: Contacts) → nothing
Parameters
- Contacts — au (Contact_Handle_List)
Possible Errors
- Disconnected
- Invalid Handle
Rationale:
SetAvatar (ay: Avatar, s: MIME_Type) → s: Token
Parameters
- Avatar — ay
- MIME_Type — s
Returns
- Token — s (Avatar_Token)
Possible Errors
- Disconnected
- Network Error
- Invalid Argument
- Permission Denied
- Not Available
Rationale:
ClearAvatar () → nothing
Possible Errors
- Disconnected
- Network Error
Rationale:
Signals
AvatarUpdated (u: Contact, s: New_Avatar_Token)
Parameters
- Contact — u (Contact_Handle)
- New_Avatar_Token — s (Avatar_Token)
AvatarRetrieved (u: Contact, s: Token, ay: Avatar, s: Type)
Parameters
- Contact — u (Contact_Handle)
- Token — s (Avatar_Token)
- Avatar — ay
- Type — s
Properties
SupportedAvatarMIMETypes — as
MinimumAvatarHeight — u
MinimumAvatarWidth — u
RecommendedAvatarHeight — u
Rationale:
RecommendedAvatarWidth — u
Rationale:
MaximumAvatarHeight — u
MaximumAvatarWidth — u
MaximumAvatarBytes — u
Contact Attributes
im.telepathy1.Connection.Interface.Avatars1/token — s (Avatar_Token)
The same string that would be returned by GetKnownAvatarTokens (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 GetKnownAvatarTokens 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.
Types
Avatar_Token — s
An opaque token chosen by the connection manager, representing a particular avatar.
Rationale:
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.
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.
Rationale:
This means that clients MAY use the triple (Connection_Manager_Name, Protocol_Name, 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.
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.
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.
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.
Avatar_Token_Map — a{us}
- Handle — u (Contact_Handle)
- Token — s (Avatar_Token)