1 # -*- coding: utf-8 -*-
2 # Generated from the Telepathy spec
4 Copyright (C) 2005, 2006 Collabora Limited
7 Copyright (C) 2005, 2006 Nokia Corporation
10 Copyright (C) 2006 INdT
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.
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.
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.
32 class ConnectionInterfacePresence(dbus.service.Interface):
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
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
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.)
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
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.
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.
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.
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.
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.
85 self._interfaces.add('org.freedesktop.Telepathy.Connection.Interface.Presence')
87 @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='sa{sv}', out_signature='')
88 def AddStatus(self, Status, Parameters):
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.
95 raise NotImplementedError
97 @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='', out_signature='')
98 def ClearStatus(self):
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.
106 raise NotImplementedError
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):
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.
119 raise NotImplementedError
121 @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='', out_signature='a{s(ubba{ss})}')
122 def GetStatuses(self):
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.
129 raise NotImplementedError
131 @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='s', out_signature='')
132 def RemoveStatus(self, Status):
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.
141 raise NotImplementedError
143 @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='au', out_signature='')
144 def RequestPresence(self, Contacts):
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.
154 raise NotImplementedError
156 @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='u', out_signature='')
157 def SetLastActivityTime(self, Time):
159 Request that the recorded last activity time for the user be updated on
163 raise NotImplementedError
165 @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.Presence', in_signature='a{sa{sv}}', out_signature='')
166 def SetStatus(self, Statuses):
168 Request that the user's presence be changed to the given statuses
169 and desired parameters. Changes will be reflected by
171 signals being emitted.
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.
178 The same rationale as for SimplePresence.SetPresence
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.
191 raise NotImplementedError
193 @dbus.service.signal('org.freedesktop.Telepathy.Connection.Interface.Presence', signature='a{u(ua{sa{sv}})}')
194 def PresenceUpdate(self, Presence):
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.