Methods
Signals
Properties
Contact Attributes
Types
Objects implementing this interface must also implement:
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.
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
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.
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
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
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
(Permalink)
SupportedAvatarMIMETypes — as
Read only
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
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
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.
(Permalink)
MaximumAvatarHeight — u
Read only
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
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
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.
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.