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
  30 import _dbus_bindings
  31 import dbus._dbus as _dbus
  32 from dbus.exceptions import NameExistsException
  33 from dbus.exceptions import UnknownMethodException
  34 from dbus.decorators import method
  35 from dbus.decorators import signal
  36 from dbus.proxies import LOCAL_PATH
  37
  38
  39 _logger = logging.getLogger('dbus.service')
  40
  41
  42 class _VariantSignature(object):
  43     """A fake method signature which, when iterated, yields an endless stream
  44     of 'v' characters representing variants (handy with zip()).
  45
  46     It has no string representation.
  47     """
  48     def __iter__(self):
  49         """Return self."""
  50         return self
  51
  52     def next(self):
  53         """Return 'v' whenever called."""
  54         return 'v'
  55
  56 class BusName(object):
  57     """A base class for exporting your own Named Services across the Bus.
  58
  59     When instantiated, objects of this class attempt to claim the given
  60     well-known name on the given bus for the current process. The name is
  61     released when the BusName object becomes unreferenced.
  62
  63     If a well-known name is requested multiple times, multiple references
  64     to the same BusName object will be returned.
  65
  66     Caveats
  67     -------
  68     - Assumes that named services are only ever requested using this class -
  69       if you request names from the bus directly, confusion may occur.
  70     - Does not handle queueing.
  71     """
  72     def __new__(cls, name, bus=None, allow_replacement=False , replace_existing=False, do_not_queue=False):
  73         """Constructor, which may either return an existing cached object
  74         or a new object.
  75
  76         :Parameters:
  77             `name` : str
  78                 The well-known name to be advertised
  79             `bus` : dbus.Bus
  80                 A Bus on which this service will be advertised; if None
  81                 (default) the session bus will be used
  82             `allow_replacement` : bool
  83                 If True, other processes trying to claim the same well-known
  84                 name will take precedence over this one.
  85             `replace_existing` : bool
  86                 If True, this process can take over the well-known name
  87                 from other processes already holding it.
  88             `do_not_queue` : bool
  89                 If True, this service will not be placed in the queue of
  90                 services waiting for the requested name if another service
  91                 already holds it.
  92         """
  93         _dbus_bindings.validate_bus_name(name, allow_well_known=True,
  94                                          allow_unique=False)
  95
  96         # get default bus
  97         if bus == None:
  98             bus = _dbus.Bus()
  99
 100         # see if this name is already defined, return it if so
 101         # FIXME: accessing internals of Bus
 102         if name in bus._bus_names:
 103             return bus._bus_names[name]
 104
 105         # otherwise register the name
 106         name_flags = (
 107             (allow_replacement and _dbus_bindings.NAME_FLAG_ALLOW_REPLACEMENT or 0) |
 108             (replace_existing and _dbus_bindings.NAME_FLAG_REPLACE_EXISTING or 0) |
 109             (do_not_queue and _dbus_bindings.NAME_FLAG_DO_NOT_QUEUE or 0))
 110
 111         retval = bus.request_name(name, name_flags)
 112
 113         # TODO: more intelligent tracking of bus name states?
 114         if retval == _dbus_bindings.REQUEST_NAME_REPLY_PRIMARY_OWNER:
 115             pass
 116         elif retval == _dbus_bindings.REQUEST_NAME_REPLY_IN_QUEUE:
 117             # queueing can happen by default, maybe we should
 118             # track this better or let the user know if they're
 119             # queued or not?
 120             pass
 121         elif retval == _dbus_bindings.REQUEST_NAME_REPLY_EXISTS:
 122             raise NameExistsException(name)
 123         elif retval == _dbus_bindings.REQUEST_NAME_REPLY_ALREADY_OWNER:
 124             # if this is a shared bus which is being used by someone
 125             # else in this process, this can happen legitimately
 126             pass
 127         else:
 128             raise RuntimeError('requesting bus name %s returned unexpected value %s' % (name, retval))
 129
 130         # and create the object
 131         bus_name = object.__new__(cls)
 132         bus_name._bus = bus
 133         bus_name._name = name
 134
 135         # cache instance (weak ref only)
 136         # FIXME: accessing Bus internals again
 137         bus._bus_names[name] = bus_name
 138
 139         return bus_name
 140
 141     # do nothing because this is called whether or not the bus name
 142     # object was retrieved from the cache or created new
 143     def __init__(self, *args, **keywords):
 144         pass
 145
 146     # we can delete the low-level name here because these objects
 147     # are guaranteed to exist only once for each bus name
 148     def __del__(self):
 149         self._bus.release_name(self._name)
 150         pass
 151
 152     def get_bus(self):
 153         """Get the Bus this Service is on"""
 154         return self._bus
 155
 156     def get_name(self):
 157         """Get the name of this service"""
 158         return self._name
 159
 160     def __repr__(self):
 161         return '<dbus.service.BusName %s on %r at %#x>' % (self._name, self._bus, id(self))
 162     __str__ = __repr__
 163
 164
 165 def _method_lookup(self, method_name, dbus_interface):
 166     """Walks the Python MRO of the given class to find the method to invoke.
 167
 168     Returns two methods, the one to call, and the one it inherits from which
 169     defines its D-Bus interface name, signature, and attributes.
 170     """
 171     parent_method = None
 172     candidate_class = None
 173     successful = False
 174
 175     # split up the cases when we do and don't have an interface because the
 176     # latter is much simpler
 177     if dbus_interface:
 178         # search through the class hierarchy in python MRO order
 179         for cls in self.__class__.__mro__:
 180             # if we haven't got a candidate class yet, and we find a class with a
 181             # suitably named member, save this as a candidate class
 182             if (not candidate_class and method_name in cls.__dict__):
 183                 if ("_dbus_is_method" in cls.__dict__[method_name].__dict__
 184                     and "_dbus_interface" in cls.__dict__[method_name].__dict__):
 185                     # however if it is annotated for a different interface
 186                     # than we are looking for, it cannot be a candidate
 187                     if cls.__dict__[method_name]._dbus_interface == dbus_interface:
 188                         candidate_class = cls
 189                         parent_method = cls.__dict__[method_name]
 190                         successful = True
 191                         break
 192                     else:
 193                         pass
 194                 else:
 195                     candidate_class = cls
 196
 197             # if we have a candidate class, carry on checking this and all
 198             # superclasses for a method annoated as a dbus method
 199             # on the correct interface
 200             if (candidate_class and method_name in cls.__dict__
 201                 and "_dbus_is_method" in cls.__dict__[method_name].__dict__
 202                 and "_dbus_interface" in cls.__dict__[method_name].__dict__
 203                 and cls.__dict__[method_name]._dbus_interface == dbus_interface):
 204                 # the candidate class has a dbus method on the correct interface,
 205                 # or overrides a method that is, success!
 206                 parent_method = cls.__dict__[method_name]
 207                 successful = True
 208                 break
 209
 210     else:
 211         # simpler version of above
 212         for cls in self.__class__.__mro__:
 213             if (not candidate_class and method_name in cls.__dict__):
 214                 candidate_class = cls
 215
 216             if (candidate_class and method_name in cls.__dict__
 217                 and "_dbus_is_method" in cls.__dict__[method_name].__dict__):
 218                 parent_method = cls.__dict__[method_name]
 219                 successful = True
 220                 break
 221
 222     if successful:
 223         return (candidate_class.__dict__[method_name], parent_method)
 224     else:
 225         if dbus_interface:
 226             raise UnknownMethodException('%s is not a valid method of interface %s' % (method_name, dbus_interface))
 227         else:
 228             raise UnknownMethodException('%s is not a valid method' % method_name)
 229
 230
 231 def _method_reply_return(connection, message, method_name, signature, *retval):
 232     reply = _dbus_bindings.MethodReturnMessage(message)
 233     try:
 234         reply.append(signature=signature, *retval)
 235     except Exception, e:
 236         if signature is None:
 237             try:
 238                 signature = reply.guess_signature(retval) + ' (guessed)'
 239             except Exception, e:
 240                 _logger.error('Unable to guess signature for arguments %r: '
 241                               '%s: %s', retval, e.__class__, e)
 242                 raise
 243         _logger.error('Unable to append %r to message with signature %s: '
 244                       '%s: %s', retval, signature, e.__class__, e)
 245         raise
 246
 247     connection.send_message(reply)
 248
 249
 250 def _method_reply_error(connection, message, exception):
 251     if hasattr(exception, '_dbus_error_name'):
 252         name = exception._dbus_error_name
 253     elif getattr(exception, '__module__', '') in ('', '__main__'):
 254         name = 'org.freedesktop.DBus.Python.%s' % exception.__class__.__name__
 255     else:
 256         name = 'org.freedesktop.DBus.Python.%s.%s' % (exception.__module__, exception.__class__.__name__)
 257
 258     contents = traceback.format_exc()
 259     reply = _dbus_bindings.ErrorMessage(message, name, contents)
 260
 261     connection.send_message(reply)
 262
 263
 264 class InterfaceType(type):
 265     def __init__(cls, name, bases, dct):
 266         # these attributes are shared between all instances of the Interface
 267         # object, so this has to be a dictionary that maps class names to
 268         # the per-class introspection/interface data
 269         class_table = getattr(cls, '_dbus_class_table', {})
 270         cls._dbus_class_table = class_table
 271         interface_table = class_table[cls.__module__ + '.' + name] = {}
 272
 273         # merge all the name -> method tables for all the interfaces
 274         # implemented by our base classes into our own
 275         for b in bases:
 276             base_name = b.__module__ + '.' + b.__name__
 277             if getattr(b, '_dbus_class_table', False):
 278                 for (interface, method_table) in class_table[base_name].iteritems():
 279                     our_method_table = interface_table.setdefault(interface, {})
 280                     our_method_table.update(method_table)
 281
 282         # add in all the name -> method entries for our own methods/signals
 283         for func in dct.values():
 284             if getattr(func, '_dbus_interface', False):
 285                 method_table = interface_table.setdefault(func._dbus_interface, {})
 286                 method_table[func.__name__] = func
 287
 288         super(InterfaceType, cls).__init__(name, bases, dct)
 289
 290     # methods are different to signals, so we have two functions... :)
 291     def _reflect_on_method(cls, func):
 292         args = func._dbus_args
 293
 294         if func._dbus_in_signature:
 295             # convert signature into a tuple so length refers to number of
 296             # types, not number of characters. the length is checked by
 297             # the decorator to make sure it matches the length of args.
 298             in_sig = tuple(_dbus_bindings.Signature(func._dbus_in_signature))
 299         else:
 300             # magic iterator which returns as many v's as we need
 301             in_sig = _VariantSignature()
 302
 303         if func._dbus_out_signature:
 304             out_sig = _dbus_bindings.Signature(func._dbus_out_signature)
 305         else:
 306             # its tempting to default to _dbus_bindings.Signature('v'), but
 307             # for methods that return nothing, providing incorrect
 308             # introspection data is worse than providing none at all
 309             out_sig = []
 310
 311         reflection_data = '    <method name="%s">\n' % (func.__name__)
 312         for pair in zip(in_sig, args):
 313             reflection_data += '      <arg direction="in"  type="%s" name="%s" />\n' % pair
 314         for type in out_sig:
 315             reflection_data += '      <arg direction="out" type="%s" />\n' % type
 316         reflection_data += '    </method>\n'
 317
 318         return reflection_data
 319
 320     def _reflect_on_signal(cls, func):
 321         args = func._dbus_args
 322
 323         if func._dbus_signature:
 324             # convert signature into a tuple so length refers to number of
 325             # types, not number of characters
 326             sig = tuple(_dbus_bindings.Signature(func._dbus_signature))
 327         else:
 328             # magic iterator which returns as many v's as we need
 329             sig = _VariantSignature()
 330
 331         reflection_data = '    <signal name="%s">\n' % (func.__name__)
 332         for pair in zip(sig, args):
 333             reflection_data = reflection_data + '      <arg type="%s" name="%s" />\n' % pair
 334         reflection_data = reflection_data + '    </signal>\n'
 335
 336         return reflection_data
 337
 338 class Interface(object):
 339     __metaclass__ = InterfaceType
 340
 341 class Object(Interface):
 342     r"""A base class for exporting your own Objects across the Bus.
 343
 344     Just inherit from Object and mark exported methods with the
 345     @\ `dbus.service.method` or @\ `dbus.service.signal` decorator.
 346
 347     Example::
 348
 349         class Example(dbus.service.object):
 350             def __init__(self, object_path):
 351                 dbus.service.Object.__init__(self, dbus.SessionBus(), path)
 352                 self._last_input = None
 353
 354             @dbus.service.method(interface='com.example.Sample',
 355                                  in_signature='v', out_signature='s')
 356             def StringifyVariant(self, var):
 357                 self.LastInputChanged(var)      # emits the signal
 358                 return str(var)
 359
 360             @dbus.service.signal(interface='com.example.Sample',
 361                                  signature='v')
 362             def LastInputChanged(self, var):
 363                 # run just before the signal is actually emitted
 364                 # just put "pass" if nothing should happen
 365                 self._last_input = var
 366
 367             @dbus.service.method(interface='com.example.Sample',
 368                                  in_signature='', out_signature='v')
 369             def GetLastInput(self):
 370                 return self._last_input
 371     """
 372
 373     # the signature of __init__ is a bit mad, for backwards compatibility
 374     def __init__(self, conn=None, object_path=None, bus_name=None):
 375         """Constructor. Either conn or bus_name is required; object_path
 376         is also required.
 377
 378         :Parameters:
 379             `conn` : dbus.Connection
 380                 The connection on which to export this object.
 381
 382                 If None, use the Bus associated with the given ``bus_name``,
 383                 or raise TypeError if there is no ``bus_name`` either.
 384
 385                 For backwards compatibility, if an instance of
 386                 dbus.service.BusName is passed as the first parameter,
 387                 this is equivalent to passing its associated Bus as
 388                 ``conn``, and passing the BusName itself as ``bus_name``.
 389
 390             `object_path` : str
 391                 The D-Bus object path at which to export this Object.
 392
 393             `bus_name` : dbus.service.BusName
 394                 Represents a well-known name claimed by this process. A
 395                 reference to the BusName object will be held by this
 396                 Object, preventing the name from being released during this
 397                 Object's lifetime (unless it's released manually).
 398         """
 399         if object_path is None:
 400             raise TypeError('The object_path argument is required')
 401         _dbus_bindings.validate_object_path(object_path)
 402         if object_path == LOCAL_PATH:
 403             raise DBusException('Objects may not be exported on the reserved '
 404                                 'path %s' % LOCAL_PATH)
 405
 406         if isinstance(conn, BusName):
 407             # someone's using the old API; don't gratuitously break them
 408             bus_name = conn
 409             conn = bus_name.get_bus()
 410         elif conn is None:
 411             # someone's using the old API but naming arguments, probably
 412             if bus_name is None:
 413                 raise TypeError('Either conn or bus_name is required')
 414             conn = bus_name.get_bus()
 415
 416         self._object_path = object_path
 417         self._name = bus_name
 418         self._bus = conn
 419
 420         self._connection = self._bus.get_connection()
 421
 422         self._connection._register_object_path(object_path, self._message_cb, self._unregister_cb)
 423
 424     __dbus_object_path__ = property(lambda self: self._object_path, None, None,
 425                                     "The D-Bus object path of this object")
 426
 427     def _unregister_cb(self, connection):
 428         _logger.info('Unregistering exported object %r', self)
 429
 430     def _message_cb(self, connection, message):
 431         try:
 432             # lookup candidate method and parent method
 433             method_name = message.get_member()
 434             interface_name = message.get_interface()
 435             (candidate_method, parent_method) = _method_lookup(self, method_name, interface_name)
 436
 437             # set up method call parameters
 438             args = message.get_args_list(**parent_method._dbus_get_args_options)
 439             keywords = {}
 440
 441             if parent_method._dbus_out_signature is not None:
 442                 signature = _dbus_bindings.Signature(parent_method._dbus_out_signature)
 443             else:
 444                 signature = None
 445
 446             # set up async callback functions
 447             if parent_method._dbus_async_callbacks:
 448                 (return_callback, error_callback) = parent_method._dbus_async_callbacks
 449                 keywords[return_callback] = lambda *retval: _method_reply_return(connection, message, method_name, signature, *retval)
 450                 keywords[error_callback] = lambda exception: _method_reply_error(connection, message, exception)
 451
 452             # include the sender etc. if desired
 453             if parent_method._dbus_sender_keyword:
 454                 keywords[parent_method._dbus_sender_keyword] = message.get_sender()
 455             if parent_method._dbus_path_keyword:
 456                 keywords[parent_method._dbus_path_keyword] = message.get_path()
 457             if parent_method._dbus_destination_keyword:
 458                 keywords[parent_method._dbus_destination_keyword] = message.get_destination()
 459             if parent_method._dbus_message_keyword:
 460                 keywords[parent_method._dbus_message_keyword] = message
 461
 462             # call method
 463             retval = candidate_method(self, *args, **keywords)
 464
 465             # we're done - the method has got callback functions to reply with
 466             if parent_method._dbus_async_callbacks:
 467                 return
 468
 469             # otherwise we send the return values in a reply. if we have a
 470             # signature, use it to turn the return value into a tuple as
 471             # appropriate
 472             if signature is not None:
 473                 signature_tuple = tuple(signature)
 474                 # if we have zero or one return values we want make a tuple
 475                 # for the _method_reply_return function, otherwise we need
 476                 # to check we're passing it a sequence
 477                 if len(signature_tuple) == 0:
 478                     if retval == None:
 479                         retval = ()
 480                     else:
 481                         raise TypeError('%s has an empty output signature but did not return None' %
 482                             method_name)
 483                 elif len(signature_tuple) == 1:
 484                     retval = (retval,)
 485                 else:
 486                     if operator.isSequenceType(retval):
 487                         # multi-value signature, multi-value return... proceed unchanged
 488                         pass
 489                     else:
 490                         raise TypeError('%s has multiple output values in signature %s but did not return a sequence' %
 491                             (method_name, signature))
 492
 493             # no signature, so just turn the return into a tuple and send it as normal
 494             else:
 495                 if retval is None:
 496                     retval = ()
 497                 elif (isinstance(retval, tuple)
 498                       and not isinstance(retval, _dbus_bindings.Struct)):
 499                 # If the return is a tuple that is not a Struct, we use it
 500                 # as-is on the assumption that there are multiple return
 501                 # values - this is the usual Python idiom. (fd.o #10174)
 502                     pass
 503                 else:
 504                     retval = (retval,)
 505
 506             _method_reply_return(connection, message, method_name, signature, *retval)
 507         except Exception, exception:
 508             # send error reply
 509             _method_reply_error(connection, message, exception)
 510
 511     @method('org.freedesktop.DBus.Introspectable', in_signature='', out_signature='s')
 512     def Introspect(self):
 513         """Return a string of XML encoding this object's supported interfaces,
 514         methods and signals.
 515         """
 516         reflection_data = '<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">\n'
 517         reflection_data += '<node name="%s">\n' % (self._object_path)
 518
 519         interfaces = self._dbus_class_table[self.__class__.__module__ + '.' + self.__class__.__name__]
 520         for (name, funcs) in interfaces.iteritems():
 521             reflection_data += '  <interface name="%s">\n' % (name)
 522
 523             for func in funcs.values():
 524                 if getattr(func, '_dbus_is_method', False):
 525                     reflection_data += self.__class__._reflect_on_method(func)
 526                 elif getattr(func, '_dbus_is_signal', False):
 527                     reflection_data += self.__class__._reflect_on_signal(func)
 528
 529             reflection_data += '  </interface>\n'
 530
 531         reflection_data += '</node>\n'
 532
 533         return reflection_data
 534
 535     def __repr__(self):
 536         return '<dbus.service.Object %s on %r at %#x>' % (self._object_path, self._name, id(self))
 537     __str__ = __repr__
 538