1 # -*- coding: utf-8 -*-
2 # Generated from the Telepathy spec
3 """Copyright (C) 2005-2009 Collabora Limited
4 Copyright (C) 2005-2009 Nokia Corporation
5 Copyright (C) 2006 INdT
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.
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.
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,
27 class Connection(dbus.service.Object):
29 This models a connection to a single user account on a communication
30 service. Its basic capability is to provide the facility to request and
31 receive channels of differing types (such as text channels or streaming
32 media channels) which are used to carry out further communication.
34 In order to allow Connection objects to be discovered by new clients,
35 the object path and well-known bus name MUST be of the form
36 /org/freedesktop/Telepathy/Connection/cmname/proto/account
38 org.freedesktop.Telepathy.Connection.cmname.proto.account
43 Connection_Manager_Name that appears
44 in the connection manager's object path and well-known bus name
45 proto is the Protocol name as seen in
47 but with "-" replaced with "_" to get a valid
49 account is some non-empty sequence of ASCII letters,
50 digits and underscores not starting with a digit
53 account SHOULD be formed such that any valid distinct
54 connection instance on this protocol has a distinct name. This
55 might be formed by including the server name followed by the user
56 name (escaped via some suitable mechanism like telepathy-glib's
57 tp_escape_as_identifier() function to preserve uniqueness); on
58 protocols where connecting multiple times is permissable, a
59 per-connection identifier might be necessary to ensure
62 Clients MAY parse the object path to determine the connection
63 manager name and the protocol, but MUST NOT attempt to parse the
64 account part. Connection managers MAY use any unique string
67 As well as the methods and signatures below, arbitrary interfaces may be
68 provided by the Connection object to represent extra connection-wide
69 functionality, such as the Connection.Interface.SimplePresence for
71 reporting presence information, and Connection.Interface.Aliasing for
72 connections where contacts may set and change an alias for themselves.
73 These interfaces can be discovered using the
76 Contacts, rooms, and server-stored lists (such as subscribed contacts,
77 block lists, or allow lists) on a service are all represented by
78 immutable handles, which are unsigned non-zero integers which are
79 valid only for the lifetime of the connection object, and are used
80 throughout the protocol where these entities are represented, allowing
81 simple testing of equality within clients.
83 Zero as a handle value is sometimes used as a "null" value to mean
84 the absence of a contact, room, etc.
86 Handles have per-type uniqueness, meaning that
87 every (handle type, handle number) tuple is guaranteed to be unique within
88 a connection and that a handle alone (without its type) is meaningless or
89 ambiguous. Connection manager implementations should reference count these
90 handles to determine if they are in use either by any active clients or any
91 open channels, and may deallocate them when this ceases to be true. Clients
92 may request handles of a given type and identifier with the
93 RequestHandles method, inspect the entity
94 identifier with the InspectHandles
95 method, keep handles from being released with
96 HoldHandles, and notify that they are no
97 longer storing handles with
101 @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='', out_signature='')
104 Request that the connection be established. This will be done
105 asynchronously and errors will be returned by emitting
106 StatusChanged signals.
108 Calling this method on a Connection that is already connecting
109 or connected is allowed, and has no effect.
112 raise NotImplementedError
114 @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='', out_signature='')
115 def Disconnect(self):
117 Request that the connection be closed. This closes the connection if
118 it's not already in DISCONNECTED state, and destroys the connection
122 raise NotImplementedError
124 @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='', out_signature='as')
125 def GetInterfaces(self):
127 Get the optional interfaces supported by this connection.
128 Before the connection status changes to CONNECTED, the return
129 from this method may change at any time, but it is guaranteed that
130 interfaces will only be added, not removed. After the connection
131 status changes to CONNECTED, the return from this method cannot
134 There is no explicit change notification; reasonable behaviour
135 for a client would be to retrieve the interfaces list once
136 initially, and once more when it becomes CONNECTED.
139 In some connection managers, certain capabilities of a connection
140 are known to be implemented for all connections (e.g. support
141 for SimplePresence), and some interfaces (like SimplePresence) can
142 even be used before connecting. Other capabilities may
143 or may not exist, depending on server functionality; by the time
144 the connection goes CONNECTED, the connection manager is expected
145 to have evaluated the server's functionality and enabled any extra
146 interfaces for the remainder of the Connection's lifetime.
150 raise NotImplementedError
152 @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='', out_signature='s')
153 def GetProtocol(self):
155 Get the protocol this connection is using.
158 raise NotImplementedError
160 @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='', out_signature='u')
161 def GetSelfHandle(self):
163 Returns the value of the SelfHandle property. Change notification
164 is via the SelfHandleChanged signal.
167 raise NotImplementedError
169 @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='', out_signature='u')
172 Get the current status as defined in the
173 StatusChanged signal.
176 raise NotImplementedError
178 @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='uau', out_signature='')
179 def HoldHandles(self, Handle_Type, Handles):
181 Notify the connection manger that your client is holding a copy
182 of handles which may not be in use in any existing channel or
183 list, and were not obtained by using the
184 RequestHandles method. For
185 example, a handle observed in an emitted signal, or displayed
186 somewhere in the UI that is not associated with a channel. The
187 connection manager must not deallocate a handle where any clients
188 have used this method to indicate it is in use until the
190 method is called, or the clients disappear from the bus.
192 Note that HoldHandles is idempotent - calling it multiple times
193 is equivalent to calling it once. If a handle is "referenced" by
194 several components which share a D-Bus unique name, the client
195 should perform reference counting internally, and only call
196 ReleaseHandles when none of the cooperating components need the
200 raise NotImplementedError
202 @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='uau', out_signature='as')
203 def InspectHandles(self, Handle_Type, Handles):
205 Return a string representation for a number of handles of a given
209 raise NotImplementedError
211 @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='', out_signature='a(osuu)')
212 def ListChannels(self):
214 List all the channels which currently exist on this connection.
217 raise NotImplementedError
219 @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='uau', out_signature='')
220 def ReleaseHandles(self, Handle_Type, Handles):
222 Explicitly notify the connection manager that your client is no
223 longer holding any references to the given handles, and that they
224 may be deallocated if they are not held by any other clients or
225 referenced by any existing channels. See HoldHandles for notes.
228 raise NotImplementedError
230 @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='suub', out_signature='o')
231 def RequestChannel(self, Type, Handle_Type, Handle, Suppress_Handler):
233 Request a channel satisfying the specified type and communicating
234 with the contact, room, list etc. indicated by the given
235 handle_type and handle. The handle_type and handle may both be
236 zero to request the creation of a new, empty channel, which may
237 or may not be possible, depending on the protocol and channel
240 On success, the returned channel will always be of the requested
241 type (i.e. implement the requested channel-type interface).
243 If a new, empty channel is requested, on success the returned
244 channel will always be an "anonymous" channel for which the type
245 and handle are both zero.
247 If a channel to a contact, room etc. is requested, on success, the
248 returned channel may either be a new or existing channel to
249 the requested entity (i.e. its
253 requested handle type and handle), or a newly created "anonymous"
254 channel associated with the requested handle in some
255 implementation-specific way.
257 For example, for a contact handle, the returned channel
258 might be "anonymous", but implement the groups interface and have
259 the requested contact already present among the members.
261 If the request cannot be satisfied, an error is raised and no
265 raise NotImplementedError
267 @dbus.service.method('org.freedesktop.Telepathy.Connection', in_signature='uas', out_signature='au')
268 def RequestHandles(self, Handle_Type, Identifiers):
270 Request several handles from the connection manager which represent a
271 number of contacts, rooms or server-stored lists on the service. The
272 connection manager should record that these handles are in use by the
273 client who invokes this method, and must not deallocate the handles
274 until the client disconnects from the bus or calls the
276 method. Where the identifier refers to an entity that already has a
277 handle in this connection manager, this handle should be returned
278 instead. The handle number 0 must not be returned by the connection
282 raise NotImplementedError
284 @dbus.service.signal('org.freedesktop.Telepathy.Connection', signature='u')
285 def SelfHandleChanged(self, Self_Handle):
287 Emitted whenever the SelfHandle property
288 changes. If the connection
289 is not yet in the CONNECTED state, this signal is not guaranteed
295 @dbus.service.signal('org.freedesktop.Telepathy.Connection', signature='osuub')
296 def NewChannel(self, Object_Path, Channel_Type, Handle_Type, Handle, Suppress_Handler):
298 Emitted when a new Channel object is created, either through user
299 request or incoming information from the service.
304 @dbus.service.signal('org.freedesktop.Telepathy.Connection', signature='sa{sv}')
305 def ConnectionError(self, Error, Details):
307 Emitted when an error occurs that renders this connection unusable.
310 Whenever this signal is emitted, it MUST immediately be followed by
311 a StatusChanged signal with status
312 Connection_Status_Disconnected and an appropriate reason
315 Connection managers SHOULD emit this signal on disconnection, but
316 need not do so. Clients MUST support connection managers that emit
317 StatusChanged(Disconnected, ...) without first emitting
321 This signal provides additional information about the reason
322 for disconnection. The reason for connection is always
323 straightforward - it was requested - so it does not need further
324 explanation. However, on errors, it can be useful to provide
325 additional information.
327 The Connection_Status_Reason is not given
328 here, since it will be signalled in
329 StatusChanged. A reasonable client
330 implementation would be to store the information given by this
331 signal until StatusChanged is received, at which point the
332 information given by this signal can be used to supplement the
333 StatusChanged signal.
339 @dbus.service.signal('org.freedesktop.Telepathy.Connection', signature='uu')
340 def StatusChanged(self, Status, Reason):
342 Emitted when the status of the connection changes. All states and
343 reasons have numerical values, as defined in ConnectionStatus
344 and ConnectionStatusReason.