Conn.I.Avatars — Telepathy D-Bus Interface Specification

# Interface Connection.Interface.Avatars

Interface Index (Compact) | Summary | Description | Methods | Signals | Properties | Contact Attributes | Types

### Methods

GetAvatarRequirements | () | → | as: MIME_Types, q: Min_Width, q: Min_Height, q: Max_Width, q: Max_Height, u: Max_Bytes | (deprecated)
GetAvatarTokens | (au: Contacts) | → | as: Tokens | (deprecated)
GetKnownAvatarTokens | (au: Contacts) | → | a{us}: Tokens |
RequestAvatar | (u: Contact) | → | ay: Data, s: MIME_Type | (deprecated)
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

org.freedesktop.Telepathy.Connection.Interface.Avatars/token | s (Avatar_Token)

### Types

Avatar_Token | Simple Type | s |
Avatar_Token_Map | Mapping | a{us} |

Objects implementing this interface must also implement:

- org.freedesktop.Telepathy.Connection

### 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, 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 GetAvatarRequirements 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 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

(Permalink)

## GetAvatarRequirements () → as: MIME_Types, q: Min_Width, q: Min_Height, q: Max_Width, q: Max_Height, u: Max_Bytes

Deprecated since 0.17.22. Use GetAll to retrieve the D-Bus properties on this interface, falling back to this method on failure.

### Returns

- MIME_Types — as
An array of supported MIME types (eg image/jpeg)
- Min_Width — q
The minimum image width in pixels
- Min_Height — q
The minimum image height in pixels
- Max_Width — q
The maximum image width in pixels, or 0 if there is no limit
- Max_Height — q
The maximum image height in pixels, or 0 if there is no limit
- Max_Bytes — u
The maximum image size in bytes, or 0 if there is no limit

Get the required format of avatars on this connection.

### Possible Errors

- Disconnected
The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.

##### Rationale:

The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
- Network Error
Raised when there is an error reading from or writing to the network.
- Permission Denied
The user is not permitted to perform the requested operation.
- Not Available
Raised when the requested functionality is temporarily unavailable.

(Permalink)

## GetAvatarTokens (au: Contacts) → as: Tokens

Deprecated since 0.15.5. Use GetKnownAvatarTokens instead.

### Parameters

- Contacts — au (Contact_Handle_List)
An array of handles representing contacts

### Returns

- Tokens — as (Avatar_Token_List)
An array of avatar tokens or empty strings (if no avatar is set) in the same order as the given array of contact handles

Get the unique tokens for all of the given contacts' avatars. Using this method in new Telepathy clients is deprecated; use GetKnownAvatarTokens instead.

### Possible Errors

- Disconnected
The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.

##### Rationale:

The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
- Network Error
Raised when there is an error reading from or writing to the network.
- Invalid Argument
Raised when one of the provided arguments is invalid.
- Permission Denied
The user is not permitted to perform the requested operation.
- Not Available
Raised when the requested functionality is temporarily unavailable.

(Permalink)

## GetKnownAvatarTokens (au: Contacts) → a{us}: Tokens

### Parameters

- Contacts — au (Contact_Handle_List)
An array of handles representing contacts

### Returns

- Tokens — a{us} (Avatar_Token_Map)
A dictionary of handles mapped to avatar tokens, containing only the known avatar tokens.

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.

### Possible Errors

- Disconnected
The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.

##### Rationale:

The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
- Network Error
Raised when there is an error reading from or writing to the network.
- Invalid Argument
Raised when one of the provided arguments is invalid.
- Permission Denied
The user is not permitted to perform the requested operation.
- Not Available
Raised when the requested functionality is temporarily unavailable.

(Permalink)

## RequestAvatar (u: Contact) → ay: Data, s: MIME_Type

Deprecated since 0.15.5. Use RequestAvatars instead.

### Parameters

- Contact — u (Contact_Handle)
An integer handle for the contact to request the avatar for

### Returns

- Data — ay
An array of bytes containing the image data
- MIME_Type — s
A string containing the image MIME type (eg image/jpeg), or empty if unknown

Request the avatar for a given contact. Using this method in new Telepathy clients is deprecated; use RequestAvatars instead.

### Possible Errors

- Disconnected
The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.

##### Rationale:

The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
- Network Error
Raised when there is an error reading from or writing to the network.
- Invalid Handle
The handle specified is unknown on this channel or connection.
- Permission Denied
The user is not permitted to perform the requested operation.
- Not Available
The contact does not currently have an avatar.

(Permalink)

## RequestAvatars (au: Contacts) → nothing

### Parameters

- Contacts — au (Contact_Handle_List)
The contacts to retrieve avatars for

Request avatars for a number of contacts. The AvatarRetrieved 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.

### Possible Errors

- Disconnected
The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.

##### Rationale:

The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
- Invalid Handle
The handle specified is unknown on this channel or connection.

(Permalink)

## SetAvatar (ay: Avatar, s: MIME_Type) → s: Token

### Parameters

- Avatar — ay
An array of bytes representing the avatar image data
- MIME_Type — s
A string representing the image MIME type

### Returns

- Token — s (Avatar_Token)
The string token of the new avatar

Set a new avatar image for this connection. The avatar image must respect the requirements obtained by GetAvatarRequirements.

### Possible Errors

- Disconnected
The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.

##### Rationale:

The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
- Network Error
Raised when there is an error reading from or writing to the network.
- Invalid Argument
Raised when one of the provided arguments is invalid.
- Permission Denied
The user is not permitted to perform the requested operation.
- Not Available
Raised when the requested functionality is temporarily unavailable.

(Permalink)

## ClearAvatar () → nothing

Added in 0.15.0.
Remove the avatar image for this connection.

### Possible Errors

- Disconnected
The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.

##### Rationale:

The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
- Network Error
Raised when there is an error reading from or writing to the network.

# Signals

(Permalink)

## AvatarUpdated (u: Contact, s: New_Avatar_Token)

### Parameters

- Contact — u (Contact_Handle)
An integer handle for the contact whose avatar has changed
- New_Avatar_Token — s (Avatar_Token)
Unique token for their new avatar

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 RequestAvatars.
(Permalink)

## AvatarRetrieved (u: Contact, s: Token, ay: Avatar, s: Type)

### Parameters

- Contact — u (Contact_Handle)
The contact whose avatar has been retrieved
- Token — s (Avatar_Token)
The token corresponding to the avatar
- Avatar — ay
An array of bytes containing the image data
- Type — s
A string containing the image MIME type (eg image/jpeg), or empty if unknown

Emitted when the avatar for a contact has been retrieved.

# Properties

Accessed using the org.freedesktop.DBus.Properties interface.
(Permalink)

## SupportedAvatarMIMETypes — as

Read only
Added in 0.17.22. Fall back to calling GetAvatarRequirements if getting this property fails.
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.
(Permalink)

## MinimumAvatarHeight — u

Read only
Added in 0.17.22. Fall back to calling GetAvatarRequirements if getting this property fails.
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.
(Permalink)

## MinimumAvatarWidth — u

Read only
Added in 0.17.22. Fall back to calling GetAvatarRequirements if getting this property fails.
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.
(Permalink)

## RecommendedAvatarHeight — u

Read only
Added in 0.17.22.
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.

##### 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.
(Permalink)

## RecommendedAvatarWidth — u

Read only
Added in 0.17.22.
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.

##### Rationale:

The rationale is the same as for RecommendedAvatarHeight.
(Permalink)

## MaximumAvatarHeight — u

Read only
Added in 0.17.22. Fall back to calling GetAvatarRequirements if getting this property fails.
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.
(Permalink)

## MaximumAvatarWidth — u

Read only
Added in 0.17.22. Fall back to calling GetAvatarRequirements if getting this property fails.
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.
(Permalink)

## MaximumAvatarBytes — u

Read only
Added in 0.17.22. Fall back to calling GetAvatarRequirements if getting this property fails.
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.

# Contact Attributes

Attributes that a contact can have, accessed with the org.freedesktop.Telepathy.Connection.Interface.Contacts interface.
(Permalink)

## org.freedesktop.Telepathy.Connection.Interface.Avatars/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

Simple Type (Permalink)

## Avatar_Token — s

Changed in 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

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, 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.

Mapping (Permalink)

## Avatar_Token_Map — a{us}

A dictionary whose keys are contact handles and whose values are avatar tokens.

- Handle — u (Contact_Handle)
- Token — s (Avatar_Token)