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
44 # This is special in libdbus - the bus daemon will kick us off if we try to
45 # send any message to it :-/
46 LOCAL_PATH
= '/org/freedesktop/DBus/Local'
49 class _ReplyHandler(object):
50 __slots__
= ('_on_error', '_on_reply', '_get_args_options')
51 def __init__(self
, on_reply
, on_error
, **get_args_options
):
52 self
._on
_error
= on_error
53 self
._on
_reply
= on_reply
54 self
._get
_args
_options
= get_args_options
56 def __call__(self
, message
):
57 if isinstance(message
, _dbus_bindings
.MethodReturnMessage
):
58 self
._on
_reply
(*message
.get_args_list(**self
._get
_args
_options
))
59 elif isinstance(message
, _dbus_bindings
.ErrorMessage
):
60 args
= message
.get_args_list()
62 self
._on
_error
(DBusException(args
[0]))
64 self
._on
_error
(DBusException())
66 self
._on
_error
(DBusException('Unexpected reply message type: %s'
70 class _DeferredMethod
:
71 """A proxy method which will only get called once we have its
74 def __init__(self
, proxy_method
, append
, block
):
75 self
._proxy
_method
= proxy_method
76 # the test suite relies on the existence of this property
77 self
._method
_name
= proxy_method
._method
_name
81 def __call__(self
, *args
, **keywords
):
82 if keywords
.has_key('reply_handler'):
83 # defer the async call til introspection finishes
84 self
._append
(self
._proxy
_method
, args
, keywords
)
87 # we're being synchronous, so block
89 return self
._proxy
_method
(*args
, **keywords
)
95 Typically a member of a ProxyObject. Calls to the
96 method produce messages that travel over the Bus and are routed
97 to a specific named Service.
99 def __init__(self
, proxy
, connection
, named_service
, object_path
, method_name
, iface
):
100 if object_path
== LOCAL_PATH
:
101 raise DBusException('Methods may not be called on the reserved '
102 'path %s' % LOCAL_PATH
)
104 # trust that the proxy, and the properties it had, are OK
106 self
._connection
= connection
107 self
._named
_service
= named_service
108 self
._object
_path
= object_path
109 # fail early if the method name is bad
110 _dbus_bindings
.validate_member_name(method_name
)
111 # the test suite relies on the existence of this property
112 self
._method
_name
= method_name
113 # fail early if the interface name is bad
114 _dbus_bindings
.validate_interface_name(iface
)
115 self
._dbus
_interface
= iface
117 def __call__(self
, *args
, **keywords
):
119 if keywords
.has_key('timeout'):
120 timeout
= keywords
['timeout']
123 if keywords
.has_key('reply_handler'):
124 reply_handler
= keywords
['reply_handler']
127 if keywords
.has_key('error_handler'):
128 error_handler
= keywords
['error_handler']
131 if keywords
.has_key('ignore_reply'):
132 ignore_reply
= keywords
['ignore_reply']
134 get_args_options
= {}
135 if keywords
.has_key('utf8_strings'):
136 get_args_options
['utf8_strings'] = keywords
['utf8_strings']
137 if keywords
.has_key('byte_arrays'):
138 get_args_options
['byte_arrays'] = keywords
['byte_arrays']
140 if not(reply_handler
and error_handler
):
142 raise MissingErrorHandlerException()
144 raise MissingReplyHandlerException()
146 dbus_interface
= self
._dbus
_interface
147 if keywords
.has_key('dbus_interface'):
148 dbus_interface
= keywords
['dbus_interface']
152 tmp_iface
= dbus_interface
+ '.'
154 key
= tmp_iface
+ self
._method
_name
156 introspect_sig
= None
157 if self
._proxy
._introspect
_method
_map
.has_key (key
):
158 introspect_sig
= self
._proxy
._introspect
_method
_map
[key
]
160 message
= _dbus_bindings
.MethodCallMessage(destination
=None,
161 path
=self
._object
_path
,
162 interface
=dbus_interface
,
163 method
=self
._method
_name
)
164 message
.set_destination(self
._named
_service
)
166 # Add the arguments to the function
168 message
.append(signature
=introspect_sig
, *args
)
170 _logger
.error('Unable to set arguments %r according to '
171 'introspected signature %r: %s: %s',
172 args
, introspect_sig
, e
.__class
__, e
)
176 self
._connection
.send_message(message
)
179 self
._connection
.send_message_with_reply(message
, _ReplyHandler(reply_handler
, error_handler
, **get_args_options
), timeout
/1000.0, require_main_loop
=1)
182 reply_message
= self
._connection
.send_message_with_reply_and_block(message
, timeout
)
183 args_list
= reply_message
.get_args_list(**get_args_options
)
184 if len(args_list
) == 0:
186 elif len(args_list
) == 1:
189 return tuple(args_list
)
193 """A proxy to the remote Object.
195 A ProxyObject is provided by the Bus. ProxyObjects
196 have member functions, and can be called like normal Python objects.
198 ProxyMethodClass
= _ProxyMethod
199 DeferredMethodClass
= _DeferredMethod
201 INTROSPECT_STATE_DONT_INTROSPECT
= 0
202 INTROSPECT_STATE_INTROSPECT_IN_PROGRESS
= 1
203 INTROSPECT_STATE_INTROSPECT_DONE
= 2
205 def __init__(self
, bus
, named_service
, object_path
, introspect
=True,
206 follow_name_owner_changes
=False):
207 """Initialize the proxy object.
211 The bus on which to find this object
212 `named_service` : str
213 A bus name for the endpoint owning the object (need not
214 actually be a service name)
216 The object path at which the endpoint exports the object
218 If true (default), attempt to introspect the remote
219 object to find out supported methods and their signatures
220 `follow_name_owner_changes` : bool
221 If true (default is false) and the `named_service` is a
222 well-known name, follow ownership changes for that name
224 if follow_name_owner_changes
:
225 bus
._require
_main
_loop
() # we don't get the signals otherwise
229 _dbus_bindings
.validate_bus_name(named_service
)
230 self
._named
_service
= named_service
232 _dbus_bindings
.validate_object_path(object_path
)
233 self
.__dbus
_object
_path
__ = object_path
235 if (named_service
[:1] != ':' and named_service
!= BUS_DAEMON_NAME
236 and not follow_name_owner_changes
):
237 bus_object
= bus
.get_object(BUS_DAEMON_NAME
, BUS_DAEMON_PATH
)
239 self
._named
_service
= bus_object
.GetNameOwner(named_service
,
240 dbus_interface
=BUS_DAEMON_IFACE
)
241 except DBusException
, e
:
242 # FIXME: detect whether it's NameHasNoOwner, but properly
243 #if not str(e).startswith('org.freedesktop.DBus.Error.NameHasNoOwner:'):
245 # it might not exist: try to start it
246 bus_object
.StartServiceByName(named_service
,
247 _dbus_bindings
.UInt32(0))
248 self
._named
_service
= bus_object
.GetNameOwner(named_service
,
249 dbus_interface
=BUS_DAEMON_IFACE
)
251 #PendingCall object for Introspect call
252 self
._pending
_introspect
= None
253 #queue of async calls waiting on the Introspect to return
254 self
._pending
_introspect
_queue
= []
255 #dictionary mapping method names to their input signatures
256 self
._introspect
_method
_map
= {}
258 # must be a recursive lock because block() is called while locked,
259 # and calls the callback which re-takes the lock
260 self
._introspect
_lock
= RLock()
262 if not introspect
or self
.__dbus
_object
_path
__ == LOCAL_PATH
:
263 self
._introspect
_state
= self
.INTROSPECT_STATE_DONT_INTROSPECT
265 self
._introspect
_state
= self
.INTROSPECT_STATE_INTROSPECT_IN_PROGRESS
267 self
._pending
_introspect
= self
._Introspect
()
269 def connect_to_signal(self
, signal_name
, handler_function
, dbus_interface
=None, **keywords
):
270 """Arrange for the given function to be called when the given signal
275 The name of the signal
276 `handler_function` : callable
277 A function to be called when the signal is emitted by
278 the remote object. Its positional arguments will be the
279 arguments of the signal; optionally, it may be given
280 keyword arguments as described below.
281 `dbus_interface` : str
282 Optional interface with which to qualify the signal name.
283 If None (the default) the handler will be called whenever a
284 signal of the given member name is received, whatever
287 `utf8_strings` : bool
288 If True, the handler function will receive any string
289 arguments as dbus.UTF8String objects (a subclass of str
290 guaranteed to be UTF-8). If False (default) it will receive
291 any string arguments as dbus.String objects (a subclass of
294 If True, the handler function will receive any byte-array
295 arguments as dbus.ByteArray objects (a subclass of str).
296 If False (default) it will receive any byte-array
297 arguments as a dbus.Array of dbus.Byte (subclasses of:
299 `sender_keyword` : str
300 If not None (the default), the handler function will receive
301 the unique name of the sending endpoint as a keyword
302 argument with this name
303 `destination_keyword` : str
304 If not None (the default), the handler function will receive
305 the bus name of the destination (or None if the signal is a
306 broadcast, as is usual) as a keyword argument with this name.
307 `interface_keyword` : str
308 If not None (the default), the handler function will receive
309 the signal interface as a keyword argument with this name.
310 `member_keyword` : str
311 If not None (the default), the handler function will receive
312 the signal name as a keyword argument with this name.
314 If not None (the default), the handler function will receive
315 the object-path of the sending object as a keyword argument
317 `message_keyword` : str
318 If not None (the default), the handler function will receive
319 the `dbus.lowlevel.SignalMessage` as a keyword argument with
321 `arg...` : unicode or UTF-8 str
322 If there are additional keyword parameters of the form
323 ``arg``\ *n*, match only signals where the *n*\ th argument
324 is the value given for that keyword parameter. As of this time
325 only string arguments can be matched (in particular,
326 object paths and signatures can't).
329 self
._bus
.add_signal_receiver(handler_function
,
330 signal_name
=signal_name
,
331 dbus_interface
=dbus_interface
,
332 named_service
=self
._named
_service
,
333 path
=self
.__dbus
_object
_path
__,
336 def _Introspect(self
):
337 message
= _dbus_bindings
.MethodCallMessage(None, self
.__dbus
_object
_path
__, 'org.freedesktop.DBus.Introspectable', 'Introspect')
338 message
.set_destination(self
._named
_service
)
340 result
= self
._bus
.get_connection().send_message_with_reply(message
, _ReplyHandler(self
._introspect
_reply
_handler
, self
._introspect
_error
_handler
, utf8_strings
=True), -1)
343 def _introspect_execute_queue(self
):
344 # FIXME: potential to flood the bus
345 # We should make sure mainloops all have idle handlers
346 # and do one message per idle
347 for (proxy_method
, args
, keywords
) in self
._pending
_introspect
_queue
:
348 proxy_method(*args
, **keywords
)
350 def _introspect_reply_handler(self
, data
):
351 self
._introspect
_lock
.acquire()
354 self
._introspect
_method
_map
= process_introspection_data(data
)
355 except IntrospectionParserException
, e
:
356 self
._introspect
_error
_handler
(e
)
359 self
._introspect
_state
= self
.INTROSPECT_STATE_INTROSPECT_DONE
360 self
._pending
_introspect
= None
361 self
._introspect
_execute
_queue
()
363 self
._introspect
_lock
.release()
365 def _introspect_error_handler(self
, error
):
366 self
._introspect
_lock
.acquire()
368 self
._introspect
_state
= self
.INTROSPECT_STATE_DONT_INTROSPECT
369 self
._pending
_introspect
= None
370 self
._introspect
_execute
_queue
()
371 sys
.stderr
.write("Introspect error: " + str(error
) + "\n")
373 self
._introspect
_lock
.release()
375 def _introspect_block(self
):
376 self
._introspect
_lock
.acquire()
378 if self
._pending
_introspect
is not None:
379 self
._pending
_introspect
.block()
380 # else someone still has a _DeferredMethod from before we
381 # finished introspection: no need to do anything special any more
383 self
._introspect
_lock
.release()
385 def _introspect_add_to_queue(self
, callback
, args
, kwargs
):
386 self
._introspect
_lock
.acquire()
388 if self
._introspect
_state
== self
.INTROSPECT_STATE_INTROSPECT_IN_PROGRESS
:
389 self
._pending
_introspect
_queue
.append((callback
, args
, kwargs
))
391 # someone still has a _DeferredMethod from before we
392 # finished introspection
393 callback(*args
, **kwargs
)
395 self
._introspect
_lock
.release()
397 def __getattr__(self
, member
, dbus_interface
=None):
398 if member
== '__call__':
399 return object.__call
__
400 elif member
.startswith('__') and member
.endswith('__'):
401 raise AttributeError(member
)
403 return self
.get_dbus_method(member
, dbus_interface
)
405 def get_dbus_method(self
, member
, dbus_interface
=None):
406 """Return a proxy method representing the given D-Bus method. The
407 returned proxy method can be called in the usual way. For instance, ::
409 proxy.get_dbus_method("Foo", dbus_interface='com.example.Bar')(123)
413 proxy.Foo(123, dbus_interface='com.example.Bar')
417 getattr(proxy, "Foo")(123, dbus_interface='com.example.Bar')
419 However, using `get_dbus_method` is the only way to call D-Bus
420 methods with certain awkward names - if the author of a service
421 implements a method called ``connect_to_signal`` or even
422 ``__getattr__``, you'll need to use `get_dbus_method` to call them.
424 For services which follow the D-Bus convention of CamelCaseMethodNames
425 this won't be a problem.
428 ret
= self
.ProxyMethodClass(self
, self
._bus
.get_connection(),
430 self
.__dbus
_object
_path
__, member
,
433 # this can be done without taking the lock - the worst that can
434 # happen is that we accidentally return a _DeferredMethod just after
435 # finishing introspection, in which case _introspect_add_to_queue and
436 # _introspect_block will do the right thing anyway
437 if self
._introspect
_state
== self
.INTROSPECT_STATE_INTROSPECT_IN_PROGRESS
:
438 ret
= self
.DeferredMethodClass(ret
, self
._introspect
_add
_to
_queue
,
439 self
._introspect
_block
)
444 return '<ProxyObject wrapping %s %s %s at %#x>'%(
445 self
._bus
, self
._named
_service
, self
.__dbus
_object
_path
__, id(self
))