dbus/service.py

   1 # Copyright (C) 2003, 2004, 2005, 2006 Red Hat Inc. <http://www.redhat.com/>
   2 # Copyright (C) 2003 David Zeuthen
   3 # Copyright (C) 2004 Rob Taylor
   4 # Copyright (C) 2005, 2006 Collabora Ltd. <http://www.collabora.co.uk/>
   5 #
   6 # Licensed under the Academic Free License version 2.1
   7 #
   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.
  12 #
  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.
  17 #
  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
  21
  22 __all__ = ('BusName', 'Object', 'method', 'signal')
  23 __docformat__ = 'restructuredtext'
  24
  25 import sys
  26 import logging
  27 import operator
  28 import traceback
  29 try:
  30     import thread
  31 except ImportError:
  32     import dummy_thread as thread
  33
  34 import _dbus_bindings
  35 from dbus import SessionBus, Signature, Struct, validate_bus_name, \
  36                  validate_object_path, INTROSPECTABLE_IFACE, ObjectPath
  37 from dbus.decorators import method, signal
  38 from dbus.exceptions import DBusException, \
  39                             NameExistsException, \
  40                             UnknownMethodException
  41 from dbus.lowlevel import ErrorMessage, MethodReturnMessage
  42 from dbus.proxies import LOCAL_PATH
  43
  44
  45 _logger = logging.getLogger('dbus.service')
  46
  47
  48 class _VariantSignature(object):
  49     """A fake method signature which, when iterated, yields an endless stream
  50     of 'v' characters representing variants (handy with zip()).
  51
  52     It has no string representation.
  53     """
  54     def __iter__(self):
  55         """Return self."""
  56         return self
  57
  58     def next(self):
  59         """Return 'v' whenever called."""
  60         return 'v'
  61
  62 class BusName(object):
  63     """A base class for exporting your own Named Services across the Bus.
  64
  65     When instantiated, objects of this class attempt to claim the given
  66     well-known name on the given bus for the current process. The name is
  67     released when the BusName object becomes unreferenced.
  68
  69     If a well-known name is requested multiple times, multiple references
  70     to the same BusName object will be returned.
  71
  72     Caveats
  73     -------
  74     - Assumes that named services are only ever requested using this class -
  75       if you request names from the bus directly, confusion may occur.
  76     - Does not handle queueing.
  77     """
  78     def __new__(cls, name, bus=None, allow_replacement=False , replace_existing=False, do_not_queue=False):
  79         """Constructor, which may either return an existing cached object
  80         or a new object.
  81
  82         :Parameters:
  83             `name` : str
  84                 The well-known name to be advertised
  85             `bus` : dbus.Bus
  86                 A Bus on which this service will be advertised.
  87
  88                 Omitting this parameter or setting it to None has been
  89                 deprecated since version 0.82.1. For backwards compatibility,
  90                 if this is done, the global shared connection to the session
  91                 bus will be used.
  92
  93             `allow_replacement` : bool
  94                 If True, other processes trying to claim the same well-known
  95                 name will take precedence over this one.
  96             `replace_existing` : bool
  97                 If True, this process can take over the well-known name
  98                 from other processes already holding it.
  99             `do_not_queue` : bool
 100                 If True, this service will not be placed in the queue of
 101                 services waiting for the requested name if another service
 102                 already holds it.
 103         """
 104         validate_bus_name(name, allow_well_known=True, allow_unique=False)
 105
 106         # if necessary, get default bus (deprecated)
 107         if bus is None:
 108             import warnings
 109             warnings.warn('Omitting the "bus" parameter to '
 110                           'dbus.service.BusName.__init__ is deprecated',
 111                           DeprecationWarning, stacklevel=2)
 112             bus = SessionBus()
 113
 114         # see if this name is already defined, return it if so
 115         # FIXME: accessing internals of Bus
 116         if name in bus._bus_names:
 117             return bus._bus_names[name]
 118
 119         # otherwise register the name
 120         name_flags = (
 121             (allow_replacement and _dbus_bindings.NAME_FLAG_ALLOW_REPLACEMENT or 0) |
 122             (replace_existing and _dbus_bindings.NAME_FLAG_REPLACE_EXISTING or 0) |
 123             (do_not_queue and _dbus_bindings.NAME_FLAG_DO_NOT_QUEUE or 0))
 124
 125         retval = bus.request_name(name, name_flags)
 126
 127         # TODO: more intelligent tracking of bus name states?
 128         if retval == _dbus_bindings.REQUEST_NAME_REPLY_PRIMARY_OWNER:
 129             pass
 130         elif retval == _dbus_bindings.REQUEST_NAME_REPLY_IN_QUEUE:
 131             # queueing can happen by default, maybe we should
 132             # track this better or let the user know if they're
 133             # queued or not?
 134             pass
 135         elif retval == _dbus_bindings.REQUEST_NAME_REPLY_EXISTS:
 136             raise NameExistsException(name)
 137         elif retval == _dbus_bindings.REQUEST_NAME_REPLY_ALREADY_OWNER:
 138             # if this is a shared bus which is being used by someone
 139             # else in this process, this can happen legitimately
 140             pass
 141         else:
 142             raise RuntimeError('requesting bus name %s returned unexpected value %s' % (name, retval))
 143
 144         # and create the object
 145         bus_name = object.__new__(cls)
 146         bus_name._bus = bus
 147         bus_name._name = name
 148
 149         # cache instance (weak ref only)
 150         # FIXME: accessing Bus internals again
 151         bus._bus_names[name] = bus_name
 152
 153         return bus_name
 154
 155     # do nothing because this is called whether or not the bus name
 156     # object was retrieved from the cache or created new
 157     def __init__(self, *args, **keywords):
 158         pass
 159
 160     # we can delete the low-level name here because these objects
 161     # are guaranteed to exist only once for each bus name
 162     def __del__(self):
 163         self._bus.release_name(self._name)
 164         pass
 165
 166     def get_bus(self):
 167         """Get the Bus this Service is on"""
 168         return self._bus
 169
 170     def get_name(self):
 171         """Get the name of this service"""
 172         return self._name
 173
 174     def __repr__(self):
 175         return '<dbus.service.BusName %s on %r at %#x>' % (self._name, self._bus, id(self))
 176     __str__ = __repr__
 177
 178
 179 def _method_lookup(self, method_name, dbus_interface):
 180     """Walks the Python MRO of the given class to find the method to invoke.
 181
 182     Returns two methods, the one to call, and the one it inherits from which
 183     defines its D-Bus interface name, signature, and attributes.
 184     """
 185     parent_method = None
 186     candidate_class = None
 187     successful = False
 188
 189     # split up the cases when we do and don't have an interface because the
 190     # latter is much simpler
 191     if dbus_interface:
 192         # search through the class hierarchy in python MRO order
 193         for cls in self.__class__.__mro__:
 194             # if we haven't got a candidate class yet, and we find a class with a
 195             # suitably named member, save this as a candidate class
 196             if (not candidate_class and method_name in cls.__dict__):
 197                 if ("_dbus_is_method" in cls.__dict__[method_name].__dict__
 198                     and "_dbus_interface" in cls.__dict__[method_name].__dict__):
 199                     # however if it is annotated for a different interface
 200                     # than we are looking for, it cannot be a candidate
 201                     if cls.__dict__[method_name]._dbus_interface == dbus_interface:
 202                         candidate_class = cls
 203                         parent_method = cls.__dict__[method_name]
 204                         successful = True
 205                         break
 206                     else:
 207                         pass
 208                 else:
 209                     candidate_class = cls
 210
 211             # if we have a candidate class, carry on checking this and all
 212             # superclasses for a method annoated as a dbus method
 213             # on the correct interface
 214             if (candidate_class and method_name in cls.__dict__
 215                 and "_dbus_is_method" in cls.__dict__[method_name].__dict__
 216                 and "_dbus_interface" in cls.__dict__[method_name].__dict__
 217                 and cls.__dict__[method_name]._dbus_interface == dbus_interface):
 218                 # the candidate class has a dbus method on the correct interface,
 219                 # or overrides a method that is, success!
 220                 parent_method = cls.__dict__[method_name]
 221                 successful = True
 222                 break
 223
 224     else:
 225         # simpler version of above
 226         for cls in self.__class__.__mro__:
 227             if (not candidate_class and method_name in cls.__dict__):
 228                 candidate_class = cls
 229
 230             if (candidate_class and method_name in cls.__dict__
 231                 and "_dbus_is_method" in cls.__dict__[method_name].__dict__):
 232                 parent_method = cls.__dict__[method_name]
 233                 successful = True
 234                 break
 235
 236     if successful:
 237         return (candidate_class.__dict__[method_name], parent_method)
 238     else:
 239         if dbus_interface:
 240             raise UnknownMethodException('%s is not a valid method of interface %s' % (method_name, dbus_interface))
 241         else:
 242             raise UnknownMethodException('%s is not a valid method' % method_name)
 243
 244
 245 def _method_reply_return(connection, message, method_name, signature, *retval):
 246     reply = MethodReturnMessage(message)
 247     try:
 248         reply.append(signature=signature, *retval)
 249     except Exception, e:
 250         logging.basicConfig()
 251         if signature is None:
 252             try:
 253                 signature = reply.guess_signature(retval) + ' (guessed)'
 254             except Exception, e:
 255                 _logger.error('Unable to guess signature for arguments %r: '
 256                               '%s: %s', retval, e.__class__, e)
 257                 raise
 258         _logger.error('Unable to append %r to message with signature %s: '
 259                       '%s: %s', retval, signature, e.__class__, e)
 260         raise
 261
 262     connection.send_message(reply)
 263
 264
 265 def _method_reply_error(connection, message, exception):
 266     name = getattr(exception, '_dbus_error_name', None)
 267
 268     if name is not None:
 269         pass
 270     elif getattr(exception, '__module__', '') in ('', '__main__'):
 271         name = 'org.freedesktop.DBus.Python.%s' % exception.__class__.__name__
 272     else:
 273         name = 'org.freedesktop.DBus.Python.%s.%s' % (exception.__module__, exception.__class__.__name__)
 274
 275     et, ev, etb = sys.exc_info()
 276     if ev is exception:
 277         # The exception was actually thrown, so we can get a traceback
 278         contents = ''.join(traceback.format_exception(et, ev, etb))
 279     else:
 280         # We don't have any traceback for it, e.g.
 281         #   async_err_cb(MyException('Failed to badger the mushroom'))
 282         # see also https://bugs.freedesktop.org/show_bug.cgi?id=12403
 283         contents = ''.join(traceback.format_exception_only(exception.__class__,
 284             exception))
 285     reply = ErrorMessage(message, name, contents)
 286
 287     connection.send_message(reply)
 288
 289
 290 class InterfaceType(type):
 291     def __init__(cls, name, bases, dct):
 292         # these attributes are shared between all instances of the Interface
 293         # object, so this has to be a dictionary that maps class names to
 294         # the per-class introspection/interface data
 295         class_table = getattr(cls, '_dbus_class_table', {})
 296         cls._dbus_class_table = class_table
 297         interface_table = class_table[cls.__module__ + '.' + name] = {}
 298
 299         # merge all the name -> method tables for all the interfaces
 300         # implemented by our base classes into our own
 301         for b in bases:
 302             base_name = b.__module__ + '.' + b.__name__
 303             if getattr(b, '_dbus_class_table', False):
 304                 for (interface, method_table) in class_table[base_name].iteritems():
 305                     our_method_table = interface_table.setdefault(interface, {})
 306                     our_method_table.update(method_table)
 307
 308         # add in all the name -> method entries for our own methods/signals
 309         for func in dct.values():
 310             if getattr(func, '_dbus_interface', False):
 311                 method_table = interface_table.setdefault(func._dbus_interface, {})
 312                 method_table[func.__name__] = func
 313
 314         super(InterfaceType, cls).__init__(name, bases, dct)
 315
 316     # methods are different to signals, so we have two functions... :)
 317     def _reflect_on_method(cls, func):
 318         args = func._dbus_args
 319
 320         if func._dbus_in_signature:
 321             # convert signature into a tuple so length refers to number of
 322             # types, not number of characters. the length is checked by
 323             # the decorator to make sure it matches the length of args.
 324             in_sig = tuple(Signature(func._dbus_in_signature))
 325         else:
 326             # magic iterator which returns as many v's as we need
 327             in_sig = _VariantSignature()
 328
 329         if func._dbus_out_signature:
 330             out_sig = Signature(func._dbus_out_signature)
 331         else:
 332             # its tempting to default to Signature('v'), but
 333             # for methods that return nothing, providing incorrect
 334             # introspection data is worse than providing none at all
 335             out_sig = []
 336
 337         reflection_data = '    <method name="%s">\n' % (func.__name__)
 338         for pair in zip(in_sig, args):
 339             reflection_data += '      <arg direction="in"  type="%s" name="%s" />\n' % pair
 340         for type in out_sig:
 341             reflection_data += '      <arg direction="out" type="%s" />\n' % type
 342         reflection_data += '    </method>\n'
 343
 344         return reflection_data
 345
 346     def _reflect_on_signal(cls, func):
 347         args = func._dbus_args
 348
 349         if func._dbus_signature:
 350             # convert signature into a tuple so length refers to number of
 351             # types, not number of characters
 352             sig = tuple(Signature(func._dbus_signature))
 353         else:
 354             # magic iterator which returns as many v's as we need
 355             sig = _VariantSignature()
 356
 357         reflection_data = '    <signal name="%s">\n' % (func.__name__)
 358         for pair in zip(sig, args):
 359             reflection_data = reflection_data + '      <arg type="%s" name="%s" />\n' % pair
 360         reflection_data = reflection_data + '    </signal>\n'
 361
 362         return reflection_data
 363
 364 class Interface(object):
 365     __metaclass__ = InterfaceType
 366
 367 #: A unique object used as the value of Object._object_path and
 368 #: Object._connection if it's actually in more than one place
 369 _MANY = object()
 370
 371 class Object(Interface):
 372     r"""A base class for exporting your own Objects across the Bus.
 373
 374     Just inherit from Object and mark exported methods with the
 375     @\ `dbus.service.method` or @\ `dbus.service.signal` decorator.
 376
 377     Example::
 378
 379         class Example(dbus.service.object):
 380             def __init__(self, object_path):
 381                 dbus.service.Object.__init__(self, dbus.SessionBus(), path)
 382                 self._last_input = None
 383
 384             @dbus.service.method(interface='com.example.Sample',
 385                                  in_signature='v', out_signature='s')
 386             def StringifyVariant(self, var):
 387                 self.LastInputChanged(var)      # emits the signal
 388                 return str(var)
 389
 390             @dbus.service.signal(interface='com.example.Sample',
 391                                  signature='v')
 392             def LastInputChanged(self, var):
 393                 # run just before the signal is actually emitted
 394                 # just put "pass" if nothing should happen
 395                 self._last_input = var
 396
 397             @dbus.service.method(interface='com.example.Sample',
 398                                  in_signature='', out_signature='v')
 399             def GetLastInput(self):
 400                 return self._last_input
 401     """
 402
 403     #: If True, this object can be made available at more than one object path.
 404     #: If True but `SUPPORTS_MULTIPLE_CONNECTIONS` is False, the object may
 405     #: handle more than one object path, but they must all be on the same
 406     #: connection.
 407     SUPPORTS_MULTIPLE_OBJECT_PATHS = False
 408
 409     #: If True, this object can be made available on more than one connection.
 410     #: If True but `SUPPORTS_MULTIPLE_OBJECT_PATHS` is False, the object must
 411     #: have the same object path on all its connections.
 412     SUPPORTS_MULTIPLE_CONNECTIONS = False
 413
 414     def __init__(self, conn=None, object_path=None, bus_name=None):
 415         """Constructor. Either conn or bus_name is required; object_path
 416         is also required.
 417
 418         :Parameters:
 419             `conn` : dbus.connection.Connection or None
 420                 The connection on which to export this object.
 421
 422                 If None, use the Bus associated with the given ``bus_name``.
 423                 If there is no ``bus_name`` either, the object is not
 424                 initially available on any Connection.
 425
 426                 For backwards compatibility, if an instance of
 427                 dbus.service.BusName is passed as the first parameter,
 428                 this is equivalent to passing its associated Bus as
 429                 ``conn``, and passing the BusName itself as ``bus_name``.
 430
 431             `object_path` : str or None
 432                 A D-Bus object path at which to make this Object available
 433                 immediately. If this is not None, a `conn` or `bus_name` must
 434                 also be provided.
 435
 436             `bus_name` : dbus.service.BusName or None
 437                 Represents a well-known name claimed by this process. A
 438                 reference to the BusName object will be held by this
 439                 Object, preventing the name from being released during this
 440                 Object's lifetime (unless it's released manually).
 441         """
 442         if object_path is not None:
 443             validate_object_path(object_path)
 444
 445         if isinstance(conn, BusName):
 446             # someone's using the old API; don't gratuitously break them
 447             bus_name = conn
 448             conn = bus_name.get_bus()
 449         elif conn is None:
 450             if bus_name is not None:
 451                 # someone's using the old API but naming arguments, probably
 452                 conn = bus_name.get_bus()
 453
 454         #: Either an object path, None or _MANY
 455         self._object_path = None
 456         #: Either a dbus.connection.Connection, None or _MANY
 457         self._connection = None
 458         #: A list of tuples (Connection, object path, False) where the False
 459         #: is for future expansion (to support fallback paths)
 460         self._locations = []
 461         #: Lock protecting `_locations`, `_connection` and `_object_path`
 462         self._locations_lock = thread.allocate_lock()
 463
 464         #: True if this is a fallback object handling a whole subtree.
 465         self._fallback = False
 466
 467         self._name = bus_name
 468
 469         if conn is None and object_path is not None:
 470             raise TypeError('If object_path is given, either conn or bus_name '
 471                             'is required')
 472         if conn is not None and object_path is not None:
 473             self.add_to_connection(conn, object_path)
 474
 475     @property
 476     def __dbus_object_path__(self):
 477         """The object-path at which this object is available.
 478         Access raises AttributeError if there is no object path, or more than
 479         one object path.
 480
 481         Changed in 0.82.0: AttributeError can be raised.
 482         """
 483         if self._object_path is _MANY:
 484             raise AttributeError('Object %r has more than one object path: '
 485                                  'use Object.locations instead' % self)
 486         elif self._object_path is None:
 487             raise AttributeError('Object %r has no object path yet' % self)
 488         else:
 489             return self._object_path
 490
 491     @property
 492     def connection(self):
 493         """The Connection on which this object is available.
 494         Access raises AttributeError if there is no Connection, or more than
 495         one Connection.
 496
 497         Changed in 0.82.0: AttributeError can be raised.
 498         """
 499         if self._connection is _MANY:
 500             raise AttributeError('Object %r is on more than one Connection: '
 501                                  'use Object.locations instead' % self)
 502         elif self._connection is None:
 503             raise AttributeError('Object %r has no Connection yet' % self)
 504         else:
 505             return self._connection
 506
 507     @property
 508     def locations(self):
 509         """An iterable over tuples representing locations at which this
 510         object is available.
 511
 512         Each tuple has at least two items, but may have more in future
 513         versions of dbus-python, so do not rely on their exact length.
 514         The first two items are the dbus.connection.Connection and the object
 515         path.
 516
 517         :Since: 0.82.0
 518         """
 519         return iter(self._locations)
 520
 521     def add_to_connection(self, connection, path):
 522         """Make this object accessible via the given D-Bus connection and
 523         object path.
 524
 525         :Parameters:
 526             `connection` : dbus.connection.Connection
 527                 Export the object on this connection. If the class attribute
 528                 SUPPORTS_MULTIPLE_CONNECTIONS is False (default), this object
 529                 can only be made available on one connection; if the class
 530                 attribute is set True by a subclass, the object can be made
 531                 available on more than one connection.
 532
 533             `path` : dbus.ObjectPath or other str
 534                 Place the object at this object path. If the class attribute
 535                 SUPPORTS_MULTIPLE_OBJECT_PATHS is False (default), this object
 536                 can only be made available at one object path; if the class
 537                 attribute is set True by a subclass, the object can be made
 538                 available with more than one object path.
 539
 540         :Raises ValueError: if the object's class attributes do not allow the
 541             object to be exported in the desired way.
 542         :Since: 0.82.0
 543         """
 544         if path == LOCAL_PATH:
 545             raise ValueError('Objects may not be exported on the reserved '
 546                              'path %s' % LOCAL_PATH)
 547
 548         self._locations_lock.acquire()
 549         try:
 550             if (self._connection is not None and
 551                 self._connection is not connection and
 552                 not self.SUPPORTS_MULTIPLE_CONNECTIONS):
 553                 raise ValueError('%r is already exported on '
 554                                  'connection %r' % (self, self._connection))
 555
 556             if (self._object_path is not None and
 557                 not self.SUPPORTS_MULTIPLE_OBJECT_PATHS and
 558                 self._object_path != path):
 559                 raise ValueError('%r is already exported at object '
 560                                  'path %s' % (self, self._object_path))
 561
 562             connection._register_object_path(path, self._message_cb,
 563                                              self._unregister_cb,
 564                                              self._fallback)
 565
 566             if self._connection is None:
 567                 self._connection = connection
 568             elif self._connection is not connection:
 569                 self._connection = _MANY
 570
 571             if self._object_path is None:
 572                 self._object_path = path
 573             elif self._object_path != path:
 574                 self._object_path = _MANY
 575
 576             self._locations.append((connection, path, self._fallback))
 577         finally:
 578             self._locations_lock.release()
 579
 580     def remove_from_connection(self, connection=None, path=None):
 581         """Make this object inaccessible via the given D-Bus connection
 582         and object path. If no connection or path is specified,
 583         the object ceases to be accessible via any connection or path.
 584
 585         It's not currently possible to export an object on more than one
 586         connection or with more than one object-path, but this will be
 587         supported in future.
 588
 589         :Parameters:
 590             `connection` : dbus.connection.Connection or None
 591                 Only remove the object from this Connection. If None,
 592                 remove from all Connections on which it's exported.
 593             `path` : dbus.ObjectPath or other str, or None
 594                 Only remove the object from this object path. If None,
 595                 remove from all object paths.
 596         :Raises LookupError:
 597             if the object was not exported on the requested connection
 598             or path, or (if both are None) was not exported at all.
 599         :Since: 0.81.1
 600         """
 601         self._locations_lock.acquire()
 602         try:
 603             if self._object_path is None or self._connection is None:
 604                 raise LookupError('%r is not exported' % self)
 605
 606             if connection is not None or path is not None:
 607                 dropped = []
 608                 for location in self._locations:
 609                     if ((connection is None or location[0] is connection) and
 610                         (path is None or location[1] == path)):
 611                         dropped.append(location)
 612             else:
 613                 dropped = self._locations
 614                 self._locations = []
 615
 616             if not dropped:
 617                 raise LookupError('%r is not exported at a location matching '
 618                                   '(%r,%r)' % (self, connection, path))
 619
 620             for location in dropped:
 621                 try:
 622                     location[0]._unregister_object_path(location[1])
 623                 except LookupError:
 624                     pass
 625                 if self._locations:
 626                     try:
 627                         self._locations.remove(location)
 628                     except ValueError:
 629                         pass
 630         finally:
 631             self._locations_lock.release()
 632
 633     def _unregister_cb(self, connection):
 634         # there's not really enough information to do anything useful here
 635         _logger.info('Unregistering exported object %r from some path '
 636                      'on %r', self, connection)
 637
 638     def _message_cb(self, connection, message):
 639         try:
 640             # lookup candidate method and parent method
 641             method_name = message.get_member()
 642             interface_name = message.get_interface()
 643             (candidate_method, parent_method) = _method_lookup(self, method_name, interface_name)
 644
 645             # set up method call parameters
 646             args = message.get_args_list(**parent_method._dbus_get_args_options)
 647             keywords = {}
 648
 649             if parent_method._dbus_out_signature is not None:
 650                 signature = Signature(parent_method._dbus_out_signature)
 651             else:
 652                 signature = None
 653
 654             # set up async callback functions
 655             if parent_method._dbus_async_callbacks:
 656                 (return_callback, error_callback) = parent_method._dbus_async_callbacks
 657                 keywords[return_callback] = lambda *retval: _method_reply_return(connection, message, method_name, signature, *retval)
 658                 keywords[error_callback] = lambda exception: _method_reply_error(connection, message, exception)
 659
 660             # include the sender etc. if desired
 661             if parent_method._dbus_sender_keyword:
 662                 keywords[parent_method._dbus_sender_keyword] = message.get_sender()
 663             if parent_method._dbus_path_keyword:
 664                 keywords[parent_method._dbus_path_keyword] = message.get_path()
 665             if parent_method._dbus_rel_path_keyword:
 666                 path = message.get_path()
 667                 rel_path = path
 668                 for exp in self._locations:
 669                     # pathological case: if we're exported in two places,
 670                     # one of which is a subtree of the other, then pick the
 671                     # subtree by preference (i.e. minimize the length of
 672                     # rel_path)
 673                     if exp[0] is connection:
 674                         if path == exp[1]:
 675                             rel_path = '/'
 676                             break
 677                         if exp[1] == '/':
 678                             # we already have rel_path == path at the beginning
 679                             continue
 680                         if path.startswith(exp[1] + '/'):
 681                             # yes we're in this exported subtree
 682                             suffix = path[len(exp[1]):]
 683                             if len(suffix) < len(rel_path):
 684                                 rel_path = suffix
 685                 rel_path = ObjectPath(rel_path)
 686                 keywords[parent_method._dbus_rel_path_keyword] = rel_path
 687
 688             if parent_method._dbus_destination_keyword:
 689                 keywords[parent_method._dbus_destination_keyword] = message.get_destination()
 690             if parent_method._dbus_message_keyword:
 691                 keywords[parent_method._dbus_message_keyword] = message
 692             if parent_method._dbus_connection_keyword:
 693                 keywords[parent_method._dbus_connection_keyword] = connection
 694
 695             # call method
 696             retval = candidate_method(self, *args, **keywords)
 697
 698             # we're done - the method has got callback functions to reply with
 699             if parent_method._dbus_async_callbacks:
 700                 return
 701
 702             # otherwise we send the return values in a reply. if we have a
 703             # signature, use it to turn the return value into a tuple as
 704             # appropriate
 705             if signature is not None:
 706                 signature_tuple = tuple(signature)
 707                 # if we have zero or one return values we want make a tuple
 708                 # for the _method_reply_return function, otherwise we need
 709                 # to check we're passing it a sequence
 710                 if len(signature_tuple) == 0:
 711                     if retval == None:
 712                         retval = ()
 713                     else:
 714                         raise TypeError('%s has an empty output signature but did not return None' %
 715                             method_name)
 716                 elif len(signature_tuple) == 1:
 717                     retval = (retval,)
 718                 else:
 719                     if operator.isSequenceType(retval):
 720                         # multi-value signature, multi-value return... proceed unchanged
 721                         pass
 722                     else:
 723                         raise TypeError('%s has multiple output values in signature %s but did not return a sequence' %
 724                             (method_name, signature))
 725
 726             # no signature, so just turn the return into a tuple and send it as normal
 727             else:
 728                 if retval is None:
 729                     retval = ()
 730                 elif (isinstance(retval, tuple)
 731                       and not isinstance(retval, Struct)):
 732                 # If the return is a tuple that is not a Struct, we use it
 733                 # as-is on the assumption that there are multiple return
 734                 # values - this is the usual Python idiom. (fd.o #10174)
 735                     pass
 736                 else:
 737                     retval = (retval,)
 738
 739             _method_reply_return(connection, message, method_name, signature, *retval)
 740         except Exception, exception:
 741             # send error reply
 742             _method_reply_error(connection, message, exception)
 743
 744     @method(INTROSPECTABLE_IFACE, in_signature='', out_signature='s',
 745             path_keyword='object_path', connection_keyword='connection')
 746     def Introspect(self, object_path, connection):
 747         """Return a string of XML encoding this object's supported interfaces,
 748         methods and signals.
 749         """
 750         reflection_data = _dbus_bindings.DBUS_INTROSPECT_1_0_XML_DOCTYPE_DECL_NODE
 751         reflection_data += '<node name="%s">\n' % object_path
 752
 753         interfaces = self._dbus_class_table[self.__class__.__module__ + '.' + self.__class__.__name__]
 754         for (name, funcs) in interfaces.iteritems():
 755             reflection_data += '  <interface name="%s">\n' % (name)
 756
 757             for func in funcs.values():
 758                 if getattr(func, '_dbus_is_method', False):
 759                     reflection_data += self.__class__._reflect_on_method(func)
 760                 elif getattr(func, '_dbus_is_signal', False):
 761                     reflection_data += self.__class__._reflect_on_signal(func)
 762
 763             reflection_data += '  </interface>\n'
 764
 765         for name in connection.list_exported_child_objects(object_path):
 766             reflection_data += '  <node name="%s"/>\n' % name
 767
 768         reflection_data += '</node>\n'
 769
 770         return reflection_data
 771
 772     def __repr__(self):
 773         where = ''
 774         if (self._object_path is not _MANY
 775             and self._object_path is not None):
 776             where = ' at %s' % self._object_path
 777         return '<%s.%s%s at %#x>' % (self.__class__.__module__,
 778                                    self.__class__.__name__, where,
 779                                    id(self))
 780     __str__ = __repr__
 781
 782 class FallbackObject(Object):
 783     """An object that implements an entire subtree of the object-path
 784     tree.
 785
 786     :Since: 0.82.0
 787     """
 788
 789     SUPPORTS_MULTIPLE_OBJECT_PATHS = True
 790
 791     def __init__(self, conn=None, object_path=None):
 792         """Constructor.
 793
 794         Note that the superclass' ``bus_name`` __init__ argument is not
 795         supported here.
 796
 797         :Parameters:
 798             `conn` : dbus.connection.Connection or None
 799                 The connection on which to export this object. If this is not
 800                 None, an `object_path` must also be provided.
 801
 802                 If None, the object is not initially available on any
 803                 Connection.
 804
 805             `object_path` : str or None
 806                 A D-Bus object path at which to make this Object available
 807                 immediately. If this is not None, a `conn` must also be
 808                 provided.
 809
 810                 This object will implements all object-paths in the subtree
 811                 starting at this object-path, except where a more specific
 812                 object has been added.
 813         """
 814         super(FallbackObject, self).__init__()
 815         self._fallback = True
 816
 817         if conn is None:
 818             if object_path is not None:
 819                 raise TypeError('If object_path is given, conn is required')
 820         elif object_path is None:
 821             raise TypeError('If conn is given, object_path is required')
 822         else:
 823             self.add_to_connection(conn, object_path)