1 # Copyright (C) 2003, 2004, 2005, 2006, 2007 Red Hat Inc. <http://www.redhat.com/>
2 # Copyright (C) 2003 David Zeuthen
3 # Copyright (C) 2004 Rob Taylor
4 # Copyright (C) 2005, 2006, 2007 Collabora Ltd. <http://www.collabora.co.uk/>
6 # Licensed under the Academic Free License version 2.1
8 # This program is free software; you can redistribute it and/or modify
9 # it under the terms of the GNU General Public License as published by
10 # the Free Software Foundation; either version 2 of the License, or
11 # (at your option) any later version.
13 # This program is distributed in the hope that it will be useful,
14 # but WITHOUT ANY WARRANTY; without even the implied warranty of
15 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 # GNU General Public License for more details.
18 # You should have received a copy of the GNU General Public License
19 # along with this program; if not, write to the Free Software
20 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
26 from threading
import RLock
28 from dummy_threading
import RLock
31 from dbus
._expat
_introspect
_parser
import process_introspection_data
32 from dbus
.exceptions
import MissingReplyHandlerException
, MissingErrorHandlerException
, IntrospectionParserException
, DBusException
34 __docformat__
= 'restructuredtext'
37 _logger
= logging
.getLogger('dbus.proxies')
40 BUS_DAEMON_NAME
= 'org.freedesktop.DBus'
41 BUS_DAEMON_PATH
= '/org/freedesktop/DBus'
42 BUS_DAEMON_IFACE
= BUS_DAEMON_NAME
45 class _ReplyHandler(object):
46 __slots__
= ('_on_error', '_on_reply', '_get_args_options')
47 def __init__(self
, on_reply
, on_error
, **get_args_options
):
48 self
._on
_error
= on_error
49 self
._on
_reply
= on_reply
50 self
._get
_args
_options
= get_args_options
52 def __call__(self
, message
):
53 if isinstance(message
, _dbus_bindings
.MethodReturnMessage
):
54 self
._on
_reply
(*message
.get_args_list(**self
._get
_args
_options
))
55 elif isinstance(message
, _dbus_bindings
.ErrorMessage
):
56 args
= message
.get_args_list()
58 self
._on
_error
(DBusException(args
[0]))
60 self
._on
_error
(DBusException())
62 self
._on
_error
(DBusException('Unexpected reply message type: %s'
66 class _DeferredMethod
:
67 """A proxy method which will only get called once we have its
70 def __init__(self
, proxy_method
, append
, block
):
71 self
._proxy
_method
= proxy_method
72 # the test suite relies on the existence of this property
73 self
._method
_name
= proxy_method
._method
_name
77 def __call__(self
, *args
, **keywords
):
78 if keywords
.has_key('reply_handler'):
79 # defer the async call til introspection finishes
80 self
._append
(self
._proxy
_method
, args
, keywords
)
83 # we're being synchronous, so block
85 return self
._proxy
_method
(*args
, **keywords
)
91 Typically a member of a ProxyObject. Calls to the
92 method produce messages that travel over the Bus and are routed
93 to a specific named Service.
95 def __init__(self
, proxy
, connection
, named_service
, object_path
, method_name
, iface
):
97 self
._connection
= connection
98 self
._named
_service
= named_service
99 self
._object
_path
= object_path
100 # the test suite relies on the existence of this property
101 self
._method
_name
= method_name
102 self
._dbus
_interface
= iface
104 def __call__(self
, *args
, **keywords
):
106 if keywords
.has_key('timeout'):
107 timeout
= keywords
['timeout']
110 if keywords
.has_key('reply_handler'):
111 reply_handler
= keywords
['reply_handler']
114 if keywords
.has_key('error_handler'):
115 error_handler
= keywords
['error_handler']
118 if keywords
.has_key('ignore_reply'):
119 ignore_reply
= keywords
['ignore_reply']
121 get_args_options
= {}
122 if keywords
.has_key('utf8_strings'):
123 get_args_options
['utf8_strings'] = keywords
['utf8_strings']
124 if keywords
.has_key('byte_arrays'):
125 get_args_options
['byte_arrays'] = keywords
['byte_arrays']
127 if not(reply_handler
and error_handler
):
129 raise MissingErrorHandlerException()
131 raise MissingReplyHandlerException()
133 dbus_interface
= self
._dbus
_interface
134 if keywords
.has_key('dbus_interface'):
135 dbus_interface
= keywords
['dbus_interface']
139 tmp_iface
= dbus_interface
+ '.'
141 key
= tmp_iface
+ self
._method
_name
143 introspect_sig
= None
144 if self
._proxy
._introspect
_method
_map
.has_key (key
):
145 introspect_sig
= self
._proxy
._introspect
_method
_map
[key
]
147 message
= _dbus_bindings
.MethodCallMessage(destination
=None,
148 path
=self
._object
_path
,
149 interface
=dbus_interface
,
150 method
=self
._method
_name
)
151 message
.set_destination(self
._named
_service
)
153 # Add the arguments to the function
155 message
.append(signature
=introspect_sig
, *args
)
157 _logger
.error('Unable to set arguments %r according to '
158 'introspected signature %r: %s: %s',
159 args
, introspect_sig
, e
.__class
__, e
)
163 self
._connection
.send_message(message
)
166 self
._connection
.send_message_with_reply(message
, _ReplyHandler(reply_handler
, error_handler
, **get_args_options
), timeout
/1000.0, require_main_loop
=1)
169 reply_message
= self
._connection
.send_message_with_reply_and_block(message
, timeout
)
170 args_list
= reply_message
.get_args_list(**get_args_options
)
171 if len(args_list
) == 0:
173 elif len(args_list
) == 1:
176 return tuple(args_list
)
180 """A proxy to the remote Object.
182 A ProxyObject is provided by the Bus. ProxyObjects
183 have member functions, and can be called like normal Python objects.
185 ProxyMethodClass
= _ProxyMethod
186 DeferredMethodClass
= _DeferredMethod
188 INTROSPECT_STATE_DONT_INTROSPECT
= 0
189 INTROSPECT_STATE_INTROSPECT_IN_PROGRESS
= 1
190 INTROSPECT_STATE_INTROSPECT_DONE
= 2
192 def __init__(self
, bus
, named_service
, object_path
, introspect
=True,
193 follow_name_owner_changes
=False):
194 """Initialize the proxy object.
198 The bus on which to find this object
199 `named_service` : str
200 A bus name for the endpoint owning the object (need not
201 actually be a service name)
203 The object path at which the endpoint exports the object
205 If true (default), attempt to introspect the remote
206 object to find out supported methods and their signatures
207 `follow_name_owner_changes` : bool
208 If true (default is false) and the `named_service` is a
209 well-known name, follow ownership changes for that name
211 if follow_name_owner_changes
:
212 bus
._require
_main
_loop
() # we don't get the signals otherwise
215 self
._named
_service
= named_service
216 self
.__dbus
_object
_path
__ = object_path
218 if (named_service
[:1] != ':' and named_service
!= BUS_DAEMON_NAME
219 and not follow_name_owner_changes
):
220 bus_object
= bus
.get_object(BUS_DAEMON_NAME
, BUS_DAEMON_PATH
)
222 self
._named
_service
= bus_object
.GetNameOwner(named_service
,
223 dbus_interface
=BUS_DAEMON_IFACE
)
224 except DBusException
, e
:
225 # FIXME: detect whether it's NameHasNoOwner, but properly
226 #if not str(e).startswith('org.freedesktop.DBus.Error.NameHasNoOwner:'):
228 # it might not exist: try to start it
229 bus_object
.StartServiceByName(named_service
,
230 _dbus_bindings
.UInt32(0))
231 self
._named
_service
= bus_object
.GetNameOwner(named_service
,
232 dbus_interface
=BUS_DAEMON_IFACE
)
234 #PendingCall object for Introspect call
235 self
._pending
_introspect
= None
236 #queue of async calls waiting on the Introspect to return
237 self
._pending
_introspect
_queue
= []
238 #dictionary mapping method names to their input signatures
239 self
._introspect
_method
_map
= {}
241 # must be a recursive lock because block() is called while locked,
242 # and calls the callback which re-takes the lock
243 self
._introspect
_lock
= RLock()
246 self
._introspect
_state
= self
.INTROSPECT_STATE_DONT_INTROSPECT
248 self
._introspect
_state
= self
.INTROSPECT_STATE_INTROSPECT_IN_PROGRESS
250 self
._pending
_introspect
= self
._Introspect
()
252 def connect_to_signal(self
, signal_name
, handler_function
, dbus_interface
=None, **keywords
):
253 """Arrange for the given function to be called when the given signal
258 The name of the signal
259 `handler_function` : callable
260 A function to be called when the signal is emitted by
261 the remote object. Its positional arguments will be the
262 arguments of the signal; optionally, it may be given
263 keyword arguments as described below.
264 `dbus_interface` : str
265 Optional interface with which to qualify the signal name.
266 If None (the default) the handler will be called whenever a
267 signal of the given member name is received, whatever
270 `utf8_strings` : bool
271 If True, the handler function will receive any string
272 arguments as dbus.UTF8String objects (a subclass of str
273 guaranteed to be UTF-8). If False (default) it will receive
274 any string arguments as dbus.String objects (a subclass of
277 If True, the handler function will receive any byte-array
278 arguments as dbus.ByteArray objects (a subclass of str).
279 If False (default) it will receive any byte-array
280 arguments as a dbus.Array of dbus.Byte (subclasses of:
282 `sender_keyword` : str
283 If not None (the default), the handler function will receive
284 the unique name of the sending endpoint as a keyword
285 argument with this name
286 `destination_keyword` : str
287 If not None (the default), the handler function will receive
288 the bus name of the destination (or None if the signal is a
289 broadcast, as is usual) as a keyword argument with this name.
290 `interface_keyword` : str
291 If not None (the default), the handler function will receive
292 the signal interface as a keyword argument with this name.
293 `member_keyword` : str
294 If not None (the default), the handler function will receive
295 the signal name as a keyword argument with this name.
297 If not None (the default), the handler function will receive
298 the object-path of the sending object as a keyword argument
300 `message_keyword` : str
301 If not None (the default), the handler function will receive
302 the `dbus.lowlevel.SignalMessage` as a keyword argument with
304 `arg...` : unicode or UTF-8 str
305 If there are additional keyword parameters of the form
306 ``arg``\ *n*, match only signals where the *n*\ th argument
307 is the value given for that keyword parameter. As of this time
308 only string arguments can be matched (in particular,
309 object paths and signatures can't).
312 self
._bus
.add_signal_receiver(handler_function
,
313 signal_name
=signal_name
,
314 dbus_interface
=dbus_interface
,
315 named_service
=self
._named
_service
,
316 path
=self
.__dbus
_object
_path
__,
319 def _Introspect(self
):
320 message
= _dbus_bindings
.MethodCallMessage(None, self
.__dbus
_object
_path
__, 'org.freedesktop.DBus.Introspectable', 'Introspect')
321 message
.set_destination(self
._named
_service
)
323 result
= self
._bus
.get_connection().send_message_with_reply(message
, _ReplyHandler(self
._introspect
_reply
_handler
, self
._introspect
_error
_handler
, utf8_strings
=True), -1)
326 def _introspect_execute_queue(self
):
327 # FIXME: potential to flood the bus
328 # We should make sure mainloops all have idle handlers
329 # and do one message per idle
330 for (proxy_method
, args
, keywords
) in self
._pending
_introspect
_queue
:
331 proxy_method(*args
, **keywords
)
333 def _introspect_reply_handler(self
, data
):
334 self
._introspect
_lock
.acquire()
337 self
._introspect
_method
_map
= process_introspection_data(data
)
338 except IntrospectionParserException
, e
:
339 self
._introspect
_error
_handler
(e
)
342 self
._introspect
_state
= self
.INTROSPECT_STATE_INTROSPECT_DONE
343 self
._pending
_introspect
= None
344 self
._introspect
_execute
_queue
()
346 self
._introspect
_lock
.release()
348 def _introspect_error_handler(self
, error
):
349 self
._introspect
_lock
.acquire()
351 self
._introspect
_state
= self
.INTROSPECT_STATE_DONT_INTROSPECT
352 self
._pending
_introspect
= None
353 self
._introspect
_execute
_queue
()
354 sys
.stderr
.write("Introspect error: " + str(error
) + "\n")
356 self
._introspect
_lock
.release()
358 def _introspect_block(self
):
359 self
._introspect
_lock
.acquire()
361 if self
._pending
_introspect
is not None:
362 self
._pending
_introspect
.block()
363 # else someone still has a _DeferredMethod from before we
364 # finished introspection: no need to do anything special any more
366 self
._introspect
_lock
.release()
368 def _introspect_add_to_queue(self
, callback
, args
, kwargs
):
369 self
._introspect
_lock
.acquire()
371 if self
._introspect
_state
== self
.INTROSPECT_STATE_INTROSPECT_IN_PROGRESS
:
372 self
._pending
_introspect
_queue
.append((callback
, args
, kwargs
))
374 # someone still has a _DeferredMethod from before we
375 # finished introspection
376 callback(*args
, **kwargs
)
378 self
._introspect
_lock
.release()
380 def __getattr__(self
, member
, dbus_interface
=None):
381 if member
== '__call__':
382 return object.__call
__
383 elif member
.startswith('__') and member
.endswith('__'):
384 raise AttributeError(member
)
386 return self
.get_dbus_method(member
, dbus_interface
)
388 def get_dbus_method(self
, member
, dbus_interface
=None):
389 """Return a proxy method representing the given D-Bus method. The
390 returned proxy method can be called in the usual way. For instance, ::
392 proxy.get_dbus_method("Foo", dbus_interface='com.example.Bar')(123)
396 proxy.Foo(123, dbus_interface='com.example.Bar')
400 getattr(proxy, "Foo")(123, dbus_interface='com.example.Bar')
402 However, using `get_dbus_method` is the only way to call D-Bus
403 methods with certain awkward names - if the author of a service
404 implements a method called ``connect_to_signal`` or even
405 ``__getattr__``, you'll need to use `get_dbus_method` to call them.
407 For services which follow the D-Bus convention of CamelCaseMethodNames
408 this won't be a problem.
411 ret
= self
.ProxyMethodClass(self
, self
._bus
.get_connection(),
413 self
.__dbus
_object
_path
__, member
,
416 # this can be done without taking the lock - the worst that can
417 # happen is that we accidentally return a _DeferredMethod just after
418 # finishing introspection, in which case _introspect_add_to_queue and
419 # _introspect_block will do the right thing anyway
420 if self
._introspect
_state
== self
.INTROSPECT_STATE_INTROSPECT_IN_PROGRESS
:
421 ret
= self
.DeferredMethodClass(ret
, self
._introspect
_add
_to
_queue
,
422 self
._introspect
_block
)
427 return '<ProxyObject wrapping %s %s %s at %#x>'%(
428 self
._bus
, self
._named
_service
, self
.__dbus
_object
_path
__, id(self
))