1
# telepathy-python - Base classes defining the interfaces of the Telepathy framework
3
# Copyright (C) 2005, 2006 Collabora Limited
4
# Copyright (C) 2005, 2006 Nokia Corporation
6
# This library is free software; you can redistribute it and/or
7
# modify it under the terms of the GNU Lesser General Public
8
# License as published by the Free Software Foundation; either
9
# version 2.1 of the License, or (at your option) any later version.
11
# This library is distributed in the hope that it will be useful,
12
# but WITHOUT ANY WARRANTY; without even the implied warranty of
13
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14
# Library General Public License for more details.
16
# You should have received a copy of the GNU Lesser General Public
17
# License along with this library; if not, write to the Free Software
18
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
23
from telepathy.errors import NotImplemented
24
from telepathy.interfaces import CONN_MGR_INTERFACE
26
class ConnectionManager(dbus.service.Object):
28
A D-Bus service which allows connections to be created. The manager
29
processes are intended to be started by D-Bus service activation. The
30
names of these services, the protocols they support, and the parameters
31
understood by that protocol are intended to be discovered by reading files
32
on disk which are provided along with the connection manager. These are
35
Once a connection manager service has been activated, the object
36
path of the manager object implementing this interface is always:
37
/org/freedesktop/Telepathy/ConnectionManager/name
38
Where name is the identifier for the connection manager.
40
It is not required that a connection manager be able to support multiple
41
protocols, or even multiple connections. When a connection is made, a
42
service name where the connection object can be found is returned. A
43
manager which can only make one connection may then remove itself from its
44
well-known bus name, causing a new connection manager to be activated when
45
somebody attempts to make a new connection.
47
def __init__(self, name):
49
Initialise the connection manager.
51
bus_name = 'org.freedesktop.Telepathy.ConnectionManager.%s' % name
52
object_path = '/org/freedesktop/Telepathy/ConnectionManager/%s' % name
53
dbus.service.Object.__init__(self, dbus.service.BusName(bus_name), object_path)
55
self._connections = set()
59
print str(self._object_path), "deleted"
60
dbus.service.Object.__del__(self)
62
def connected(self, conn):
64
Add a connection to the list of connections, emit the appropriate
67
self._connections.add(conn)
68
self.NewConnection(conn._name.get_name(), conn._object_path, conn._proto)
70
def disconnected(self, conn):
72
Remove a connection from the list of connections.
74
self._connections.remove(conn)
77
return False # when called in an idle callback
79
@dbus.service.method(CONN_MGR_INTERFACE, in_signature='', out_signature='as')
80
def ListProtocols(self):
82
Get a list of protocol identifiers that are implemented by this
83
connection manager. The following well-known values should be used
85
aim - AOL Instant Messenger
87
groupwise - Novell Groupwise
89
irc - Internet Relay Chat
90
jabber - Jabber (XMPP)
94
sip - Session Initiation Protocol (SIP)
96
yahoo - Yahoo! Messenger
100
an array of string protocol identifiers supported by this manager
102
return self._protos.keys()
104
@dbus.service.method(CONN_MGR_INTERFACE, in_signature='s', out_signature='a(susv)')
105
def GetParameters(self, proto):
107
Get a list of the parameters which must or may be provided to the
108
RequestConnection method when connecting to the given protocol,
109
or registering (the boolean "register" parameter is available, and
112
Parameters may have the following flags:
113
1 - CONN_MGR_PARAM_FLAG_REQUIRED
114
This parameter is required for connecting to the server.
115
2 - CONN_MGR_PARAM_FLAG_REGISTER
116
This parameter is required for registering an account on the
118
4 - CONN_MGR_PARAM_FLAG_HAS_DEFAULT
119
This parameter has a default value, which is returned; not
120
providing this parameter is equivalent to providing the default.
123
an array of structs containing:
124
a string parameter name
125
a bitwise OR of the parameter flags (as defined above)
126
a string D-Bus type signature
127
a variant boxed default value (only relevant if the
128
HAS_DEFAULT flag is present)
131
NotImplemented (the requested protocol is not supported by this manager)
135
@dbus.service.method(CONN_MGR_INTERFACE, in_signature='sa{sv}', out_signature='so')
136
def RequestConnection(self, proto, parameters):
138
Request a Connection object representing a given account on a given
139
protocol with the given parameters. The method returns the bus name
140
and the object path where the new Connection object can be found, which
141
should have the status of CONNECTION_STATUS_DISCONNECTED, to allow
142
signal handlers to be attached before connecting is started with the
145
In order to allow Connection objects to be discovered by new clients,
146
the bus name and object path must be of the form:
147
/org/freedesktop/Telepathy/Connection/manager/proto/account
149
org.freedesktop.Telepathy.Connection.manager.proto.account
150
Where manager and proto are the identifiers for this manager and this
151
protocol, and account is a series of elements formed such that any
152
valid distinct connection instance on this protocol has a distinct
153
name. This might be formed by including the server name followed by the
154
user name, or on protocols where connecting multiple times is
155
permissable, a per-connection identifier is also necessary to ensure
158
The parameters which must and may be provided in the parameters
159
dictionary can be discovered with the GetParameters method. These
160
parameters, their types, and their default values may be cached
161
in files so that all available connection managers do not need to be
162
started to discover which protocols are available.
164
To request values for these parameters from the user, a client must
165
have prior knowledge of the meaning of the parameter names, so the
166
following well-known names and types should be used where appropriate:
168
s:account - the identifier for the user's account on the server.
170
s:server - a fully qualified domain name or numeric IPv4 or IPv6
171
address. Using the fully-qualified domain name form is recommended
172
whenever possible. If this parameter is specified and the account
173
for that protocol also specifies a server, this parameter should
174
override that in the user id.
176
q:port - a TCP or UDP port number. If this parameter is specified
177
and the account for that protocol also specifies a port, this
178
parameter should override that in the account.
180
s:password - a password associated with the account.
182
b:require-encryption - require encryption for this connection. A
183
connection should fail to connect if require-encryption is set
184
and an encrypted connection is not possible.
186
b:register - this account should be created on the server if it
187
does not already exist.
189
s:ident - the local username to report to the server if
190
necessary, such as in IRC.
192
s:fullname - the user's full name if the service requires this
193
when authenticating or registering.
195
Every successful RequestConnection call will cause the emission of a
196
NewConnection signal for the same newly created connection. The
197
requester can use the returned object path and service name
198
independently of the emission of that signal. In that case this signal
199
emission is most useful for, e.g. other processes that are monitoring
200
the creation of new connections.
203
proto - the protocol identifier
204
parameters - a dictionary mapping parameter name to the variant boxed value
207
a D-Bus service name where the new Connection object can be found
208
the D-Bus object path to the Connection on this service
211
NetworkError, NotImplemented (unknown protocol), NotAvailable (the requested connection already appears to exist), InvalidArgument (unrecognised connection parameters)
213
if proto in self._protos:
214
conn = self._protos[proto](self, parameters)
216
return (conn._name.get_name(), conn._object_path)
218
raise NotImplemented('unknown protocol %s' % proto)
220
@dbus.service.signal(CONN_MGR_INTERFACE, signature='sos')
221
def NewConnection(self, bus_name, object_path, proto):
223
Emitted when a new Connection object is created.
226
bus_name - the D-Bus service where the connection object can be found
227
object_path - the object path of the Connection object on this service
228
proto - the identifier for the protocol this connection uses
added
removed
telepathy/server/connmgr.py
