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

   1 # -*- coding: utf-8 -*-
   2 # Generated from the Telepathy spec
   3 """ Copyright (C) 2005-2008 Collabora Limited
   4  Copyright (C) 2005, 2006 Nokia Corporation
   5  Copyright (C) 2006 INdT
   6
   7     This library is free software; you can redistribute it and/or modify it
   8       under the terms of the GNU Lesser General Public License as published by
   9       the Free Software Foundation; either version 2.1 of the License, or (at
  10       your option) any later version.
  11
  12     This library is distributed in the hope that it will be useful, but
  13       WITHOUT ANY WARRANTY; without even the implied warranty of
  14       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser
  15       General Public License for more details.
  16
  17     You should have received a copy of the GNU Lesser General Public License
  18       along with this library; if not, write to the Free Software Foundation,
  19       Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  20
  21 """
  22
  23 import dbus.service
  24
  25
  26 class ConnectionInterfaceSimplePresence(dbus.service.Interface):
  27     """\
  28       This interface is for services which have a concept of presence which
  29         can be published for yourself and monitored on your contacts.
  30
  31       Presence on an individual (yourself or one of your contacts) is
  32         modelled as a status and a status message. Valid statuses are defined
  33         per connection, and a list of those that can be set on youself
  34         can be obtained from the
  35         Statuses
  36         property.
  37
  38       Each status has an arbitrary string identifier which should have an
  39         agreed meaning between the connection manager and any client which is
  40         expected to make use of it. The following well-known values should be
  41         used where possible to allow clients to identify common choices:
  42
  43
  44
  45           status identifier
  46           Connection_Presence_Type
  47           comments
  48
  49
  50           available
  51           Connection_Presence_Type_Available
  52
  53
  54
  55           away
  56           Connection_Presence_Type_Away
  57
  58
  59
  60           brb
  61           Connection_Presence_Type_Away
  62           Be Right Back (a more specific form of Away)
  63
  64
  65           busy
  66           Connection_Presence_Type_Busy
  67
  68
  69         dnd
  70           Connection_Presence_Type_Busy
  71           Do Not Disturb (a more specific form of Busy)
  72
  73
  74           xa
  75           Connection_Presence_Type_Extended_Away
  76           Extended Away
  77
  78
  79           hidden
  80           Connection_Presence_Type_Hidden
  81           Also known as "Invisible" or "Appear Offline"
  82
  83
  84           offline
  85           Connection_Presence_Type_Offline
  86
  87
  88
  89           unknown
  90           Connection_Presence_Type_Unknown
  91           special, see below
  92
  93
  94           error
  95           Connection_Presence_Type_Error
  96           special, see below
  97
  98
  99
 100       As well as these well-known status identifiers, every status also has
 101         a numerical type value chosen from
 102         Connection_Presence_Type which can be
 103         used by the client to classify even unknown statuses into different
 104         fundamental types.
 105
 106       These numerical types exist so that even if a client does not
 107         understand the string identifier being used, and hence cannot present
 108         the presence to the user to set on themselves, it may display an
 109         approximation of the presence if it is set on a contact.
 110
 111       As well as the normal status identifiers, there are two special ones
 112         that may be present: 'unknown' with type Unknown and 'error' with type
 113         Error. 'unknown' indicates that it is impossible to determine the
 114         presence of a contact at this time, for example because it's not on the
 115         'subscribe' list and the protocol only allows one to determine the
 116         presence of contacts you're subscribed to. 'error' indicates that there
 117         was a failure in determining the status of a contact.
 118
 119       If the connection has a 'subscribe' contact list,
 120         PresencesChanged
 121         signals should be emitted to indicate changes of contacts on this list,
 122         and should also be emitted for changes in your own presence. Depending
 123         on the protocol, the signal may also be emitted for others such as
 124         people with whom you are communicating, and any user interface should
 125         be updated accordingly.
 126     """
 127
 128     def __init__(self):
 129         self._interfaces.add('org.freedesktop.Telepathy.Connection.Interface.SimplePresence')
 130
 131     @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.SimplePresence', in_signature='ss', out_signature='')
 132     def SetPresence(self, Status, Status_Message):
 133         """
 134         Request that the presence status and status message are published for
 135           the connection.  Changes will be indicated by
 136           PresencesChanged
 137           signals being emitted.
 138
 139         This method may be called on a newly-created connection while it
 140           is still in the DISCONNECTED state, to request that when the
 141           connection connects, it will do so with the selected status.
 142
 143         In DISCONNECTED state the
 144           Statuses
 145           property will indicate which statuses are allowed to be set
 146           while DISCONNECTED (none, if the Connection Manager doesn't allow
 147           this). This value MUST NOT be cached, as the set of allowed
 148           presences might change upon connecting.
 149
 150         """
 151         raise NotImplementedError
 152
 153     @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.SimplePresence', in_signature='au', out_signature='a{u(uss)}')
 154     def GetPresences(self, Contacts):
 155         """
 156         Get presence previously emitted by
 157         PresencesChanged for the given
 158         contacts. Data is returned in the same structure as the
 159         PresencesChanged signal; no additional network requests are made.
 160
 161         """
 162         raise NotImplementedError
 163
 164     @dbus.service.signal('org.freedesktop.Telepathy.Connection.Interface.SimplePresence', signature='a{u(uss)}')
 165     def PresencesChanged(self, Presence):
 166         """
 167         This signal should be emitted when your own presence has been changed,
 168         or the presence of the member of any of the connection's channels has
 169         been changed.
 170
 171         """
 172         pass
 173