git.maemo.org Git - theonering/blob - src/tp/_generated/Connection_Interface_Avatars.py

   1 # -*- coding: utf-8 -*-
   2 # Generated from the Telepathy spec
   3 """Copyright (C) 2005-2008 Collabora Limited
   4 Copyright (C) 2005-2008 Nokia Corporation
   5 Copyright (C) 2006 INdT
   6
   7     This library is free software; you can redistribute it and/or
   8 modify it under the terms of the GNU Lesser General Public
   9 License as published by the Free Software Foundation; either
  10 version 2.1 of the License, or (at your option) any later version.
  11
  12 This library is distributed in the hope that it will be useful,
  13 but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 Lesser General Public License for more details.
  16
  17 You should have received a copy of the GNU Lesser General Public
  18 License along with this library; if not, write to the Free Software
  19 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  20
  21 """
  22
  23 import dbus.service
  24
  25
  26 class ConnectionInterfaceAvatars(dbus.service.Interface):
  27     """\
  28       An interface for requesting avatars for contacts on a given connection,
  29     receiving notification when avatars are changed, and publishing your own
  30     avatar.
  31
  32     Avatars are identified by a string, the Avatar_Token,
  33     which represents a particular avatar. Tokens MUST be chosen by the
  34     connection manager in such a way that the triple
  35     (Connection_Manager_Name, Protocol,
  36     Avatar_Token) uniquely identifies an avatar.
  37     An empty token means that an avatar has not been set for this contact, and
  38     a changed token implies the contact's avatar has changed, but the strings
  39     should otherwise be considered opaque by clients.
  40
  41     A client should use GetKnownAvatarTokens
  42     to request the tokens for the
  43     avatars of all the contacts it is interested in when it connects. The
  44     avatars can then be requested using
  45     RequestAvatars for the contacts.  Clients
  46     should bind to the AvatarUpdated signal and
  47     request a new copy of
  48     the avatar when a contacts' avatar token changes. Clients should cache the
  49     token and data of each contact's avatar between connections, to avoid
  50     repeatedly retrieving the same avatar.
  51
  52     To publish an avatar, a client should use
  53     SetAvatar to provide an image which meets
  54     the requirements returned by the
  55     GetAvatarRequirements
  56     function. On some protocols the avatar is stored on the server, so setting
  57     the avatar is persistent, but on others it is transferred via a peer to
  58     peer mechanism, so needs to be set every connection. Hence, on every
  59     connection, clients should inspect the avatar token of the connection's
  60     self handle using GetKnownAvatarTokens; if
  61     the self handle is not in the
  62     returned map, the client should re-set the avatar. If the self handle's
  63     avatar token is known, but the avatar has been changed locally since the
  64     last connection, the client should upload the new avatar; if the avatar has
  65     not changed locally, then the client should download the avatar from the
  66     server if its token differs from the that of the local avatar.
  67
  68     To remove the published avatar on protocols which have persistent avatars,
  69     a client should use the ClearAvatar method.
  70     This method can safely be used even if there is no avatar for this
  71     connection.
  72     """
  73
  74     def __init__(self):
  75         self._interfaces.add('org.freedesktop.Telepathy.Connection.Interface.Avatars')
  76
  77     @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Avatars', in_signature='', out_signature='asqqqqu')
  78     def GetAvatarRequirements(self):
  79         """
  80         Get the required format of avatars on this connection.
  81
  82         """
  83         raise NotImplementedError
  84
  85     @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Avatars', in_signature='au', out_signature='as')
  86     def GetAvatarTokens(self, Contacts):
  87         """
  88         Get the unique tokens for all of the given contacts' avatars.
  89
  90         Using this method in new Telepathy clients is deprecated; use
  91         GetKnownAvatarTokens instead.
  92
  93         """
  94         raise NotImplementedError
  95
  96     @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Avatars', in_signature='au', out_signature='a{us}')
  97     def GetKnownAvatarTokens(self, Contacts):
  98         """
  99         Get the unique tokens for the given contacts' avatars. These tokens
 100         can be persisted across connections, and should be used by the client
 101         to check whether the avatars have been updated.  For handles other than
 102         the self handle, only tokens that are already known are returned; an
 103         empty token means the given contact has no avatar.  However, a CM must
 104         always have the tokens for the self handle if one is set (even if it is
 105         set to no avatar).  On protocols where the avatar does not persist
 106         between connections, a CM should omit the self handle from the returned
 107         map until an avatar is explicitly set or cleared.
 108
 109         """
 110         raise NotImplementedError
 111
 112     @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Avatars', in_signature='u', out_signature='ays')
 113     def RequestAvatar(self, Contact):
 114         """
 115         Request the avatar for a given contact. Using this method in new
 116         Telepathy clients is deprecated; use RequestAvatars instead.
 117
 118         """
 119         raise NotImplementedError
 120
 121     @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Avatars', in_signature='au', out_signature='')
 122     def RequestAvatars(self, Contacts):
 123         """
 124         Request avatars for a number of contacts. The
 125         AvatarRetrieved signal is emitted for
 126         each avatar retrieved. If the handles are valid but retrieving an
 127         avatar fails (for any reason, including the contact not having an
 128         avatar) the AvatarRetrieved signal is not emitted for that contact.
 129
 130         """
 131         raise NotImplementedError
 132
 133     @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Avatars', in_signature='ays', out_signature='s')
 134     def SetAvatar(self, Avatar, MIME_Type):
 135         """
 136         Set a new avatar image for this connection. The avatar image must
 137         respect the requirements obtained by
 138         GetAvatarRequirements.
 139
 140         """
 141         raise NotImplementedError
 142
 143     @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Avatars', in_signature='', out_signature='')
 144     def ClearAvatar(self):
 145         """
 146         Remove the avatar image for this connection.
 147
 148         """
 149         raise NotImplementedError
 150
 151     @dbus.service.signal('org.freedesktop.Telepathy.Connection.Interface.Avatars', signature='us')
 152     def AvatarUpdated(self, Contact, New_Avatar_Token):
 153         """
 154         Emitted when the avatar for a contact has been updated, or first
 155         discovered on this connection. If the token differs from the token
 156         associated with the client's cached avatar for this contact, the new
 157         avatar should be requested with
 158         RequestAvatars.
 159
 160         """
 161         pass
 162
 163     @dbus.service.signal('org.freedesktop.Telepathy.Connection.Interface.Avatars', signature='usays')
 164     def AvatarRetrieved(self, Contact, Token, Avatar, Type):
 165         """
 166         Emitted when the avatar for a contact has been retrieved.
 167
 168         """
 169         pass
 170