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

   1 # -*- coding: utf-8 -*-
   2 # Generated from the Telepathy spec
   3 """
   4     Copyright (C) 2005, 2006 Collabora Limited
   5
   6
   7 Copyright (C) 2005, 2006 Nokia Corporation
   8
   9
  10 Copyright (C) 2006 INdT
  11
  12
  13     This library is free software; you can redistribute it and/or
  14 modify it under the terms of the GNU Lesser General Public
  15 License as published by the Free Software Foundation; either
  16 version 2.1 of the License, or (at your option) any later version.
  17
  18 This library is distributed in the hope that it will be useful,
  19 but WITHOUT ANY WARRANTY; without even the implied warranty of
  20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  21 Lesser General Public License for more details.
  22
  23 You should have received a copy of the GNU Lesser General Public
  24 License along with this library; if not, write to the Free Software
  25 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  26
  27 """
  28
  29 import dbus.service
  30
  31
  32 class ConnectionInterfacePresence(dbus.service.Interface):
  33     """\
  34
  35       This interface is for services which have a concept of presence which
  36         can be published for yourself and monitored on your contacts.
  37         Telepathy's definition of presence is based on that used by
  38         the Galago project.
  39
  40     Presence on an individual (yourself or one of your contacts) is modelled as
  41     a last activity time along with a set of zero or more statuses, each of
  42     which may have arbitrary key/value parameters. Valid statuses are defined
  43     per connection, and a list of them can be obtained with the
  44     GetStatuses method.
  45
  46     (The SimplePresence interface which replaces this one restricts
  47       presences to one status per contact, with an optional message, which is
  48       in practice all that was implemented on this interface.)
  49
  50     Each status has an arbitrary string identifier which should have an agreed
  51     meaning between the connection manager and any client which is expected to
  52     make use of it. The well-known values defined by the SimplePresence
  53       interface SHOULD be used where possible
  54
  55     As well as these well-known status identifiers, every status also has a
  56     numerical type value chosen from
  57     Connection_Presence_Type which can be used by the client
  58     to classify even unknown statuses into different fundamental types.
  59
  60     These numerical types exist so that even if a client does not understand
  61     the string identifier being used, and hence cannot present the presence to
  62     the user to set on themselves, it may display an approximation of the
  63     presence if it is set on a contact.
  64
  65     The dictionary of variant types allows the connection manager to exchange
  66     further protocol-specific information with the client. It is recommended
  67     that the string (s) argument 'message' be interpreted as an optional
  68     message which can be associated with a presence status.
  69
  70     If the connection has a 'subscribe' contact list,
  71     PresenceUpdate signals should be emitted to
  72     indicate changes of contacts on this list, and should also be emitted for
  73     changes in your own presence. Depending on the protocol, the signal may
  74     also be emitted for others such as people with whom you are communicating,
  75     and any user interface should be updated accordingly.
  76
  77     On some protocols, RequestPresence may
  78     only succeed on contacts on your 'subscribe' list, and other contacts will
  79     cause a PermissionDenied error.  On protocols where there is no 'subscribe'
  80     list, and RequestPresence succeeds, a client may poll the server
  81     intermittently to update any display of presence information.
  82     """
  83
  84     def __init__(self):
  85         self._interfaces.add('org.freedesktop.Telepathy.Connection.Interface.Presence')
  86
  87     @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='sa{sv}', out_signature='')
  88     def AddStatus(self, Status, Parameters):
  89         """
  90         Request that a single presence status is published for the user, along
  91         with any desired parameters. Changes will be indicated by
  92         PresenceUpdate signals being emitted.
  93
  94         """
  95         raise NotImplementedError
  96
  97     @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='', out_signature='')
  98     def ClearStatus(self):
  99         """
 100         Request that all of a user's presence statuses be removed. Be aware
 101         that this request may simply result in the statuses being replaced by a
 102         default available status. Changes will be indicated by
 103         PresenceUpdate signals being emitted.
 104
 105         """
 106         raise NotImplementedError
 107
 108     @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='au', out_signature='a{u(ua{sa{sv}})}')
 109     def GetPresence(self, Contacts):
 110         """
 111         Get presence previously emitted by
 112         PresenceUpdate for the given contacts.
 113         Data is returned in the same structure as the PresenceUpdate signal.
 114         Using this method in favour of
 115         RequestPresence has the advantage that
 116         it will not wake up each client connected to the PresenceUpdate signal.
 117
 118         """
 119         raise NotImplementedError
 120
 121     @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='', out_signature='a{s(ubba{ss})}')
 122     def GetStatuses(self):
 123         """
 124         Get a dictionary of the valid presence statuses for this connection.
 125         This is only available when online because only some statuses will
 126         be available on some servers.
 127
 128         """
 129         raise NotImplementedError
 130
 131     @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='s', out_signature='')
 132     def RemoveStatus(self, Status):
 133         """
 134         Request that the given presence status is no longer published for the
 135         user. Changes will be indicated by
 136         PresenceUpdate signals being emitted. As
 137         with ClearStatus, removing a status may
 138         actually result in it being replaced by a default available status.
 139
 140         """
 141         raise NotImplementedError
 142
 143     @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='au', out_signature='')
 144     def RequestPresence(self, Contacts):
 145         """
 146         Request the presence for contacts on this connection. A PresenceUpdate
 147         signal will be emitted when they are received. This is not the same as
 148         subscribing to the presence of a contact, which must be done using the
 149         'subscription' ContactList,
 150         and on some protocols presence information may not be available unless
 151         a subscription exists.
 152
 153         """
 154         raise NotImplementedError
 155
 156     @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='u', out_signature='')
 157     def SetLastActivityTime(self, Time):
 158         """
 159         Request that the recorded last activity time for the user be updated on
 160         the server.
 161
 162         """
 163         raise NotImplementedError
 164
 165     @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='a{sa{sv}}', out_signature='')
 166     def SetStatus(self, Statuses):
 167         """
 168         Request that the user's presence be changed to the given statuses
 169           and desired parameters. Changes will be reflected by
 170           PresenceUpdate
 171           signals being emitted.
 172
 173         Statuses whose Connection_Presence_Type
 174           is Offline, Error or Unknown MUST NOT be passed to this
 175           function. Connection managers SHOULD reject these statuses.
 176
 177
 178           The same rationale as for SimplePresence.SetPresence
 179             applies.
 180
 181
 182         On certain protocols, this method may be
 183           called on a newly-created connection which is still in the
 184           DISCONNECTED state, and will sign on with the requested status.
 185           If the requested status is not available after signing on,
 186           NotAvailable will be returned and the connection will remain
 187           offline, or if the protocol does not support signing on with
 188           a certain status, Disconnected will be returned.
 189
 190         """
 191         raise NotImplementedError
 192
 193     @dbus.service.signal('org.freedesktop.Telepathy.Connection.Interface.Presence', signature='a{u(ua{sa{sv}})}')
 194     def PresenceUpdate(self, Presence):
 195         """
 196         This signal should be emitted when your own presence has been changed,
 197         or the presence of the member of any of the connection's channels has
 198         been changed, or when the presence requested by
 199         RequestPresence is available.
 200
 201         """
 202         pass
 203