dbus/bus.py

   1 """Bus mixin, for use within dbus-python only. See `_BusMixin`."""
   2
   3 # Copyright (C) 2007 Collabora Ltd. <http://www.collabora.co.uk/>
   4 #
   5 # Licensed under the Academic Free License version 2.1
   6 #
   7 # This program is free software; you can redistribute it and/or modify
   8 # it under the terms of the GNU Lesser General Public License as published
   9 # by the Free Software Foundation; either version 2.1 of the License, or
  10 # (at your option) any later version.
  11 #
  12 # This program is distributed in the hope that it will be useful,
  13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 # GNU General Public License for more details.
  16 #
  17 # You should have received a copy of the GNU General Public License
  18 # along with this program; if not, write to the Free Software
  19 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  20
  21 BUS_DAEMON_NAME = 'org.freedesktop.DBus'
  22 BUS_DAEMON_PATH = '/org/freedesktop/DBus'
  23 BUS_DAEMON_IFACE = BUS_DAEMON_NAME
  24
  25 from _dbus_bindings import validate_interface_name, validate_member_name,\
  26                            validate_bus_name, validate_object_path,\
  27                            validate_error_name
  28
  29
  30 class _BusDaemonMixin(object):
  31     """This mixin provides simple blocking wrappers for various methods on
  32     the org.freedesktop.DBus bus-daemon object, to reduce the amount of C
  33     code we need.
  34     """
  35
  36     def get_unix_user(self, bus_name):
  37         """Get the numeric uid of the process owning the given bus name.
  38
  39         :Parameters:
  40             `bus_name` : str
  41                 A bus name, either unique or well-known
  42         :Returns: a `dbus.UInt32`
  43         """
  44         validate_bus_name(bus_name)
  45         return self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
  46                                   BUS_DAEMON_IFACE, 'GetConnectionUnixUser',
  47                                   's', (bus_name,))
  48
  49     def start_service_by_name(self, bus_name, flags=0):
  50         """Start a service which will implement the given bus name on this Bus.
  51
  52         :Parameters:
  53             `bus_name` : str
  54                 The well-known bus name to be activated.
  55             `flags` : dbus.UInt32
  56                 Flags to pass to StartServiceByName (currently none are
  57                 defined)
  58
  59         :Returns: A tuple of 2 elements. The first is always True, the
  60             second is either START_REPLY_SUCCESS or
  61             START_REPLY_ALREADY_RUNNING.
  62
  63         :Raises DBusException: if the service could not be started.
  64         """
  65         validate_bus_name(bus_name)
  66         return (True, self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
  67                                          BUS_DAEMON_IFACE,
  68                                          'StartServiceByName',
  69                                          'su', (bus_name, flags)))
  70
  71     # XXX: it might be nice to signal IN_QUEUE, EXISTS by exception,
  72     # but this would not be backwards-compatible
  73     def request_name(self, name, flags=0):
  74         """Request a bus name.
  75
  76         :Parameters:
  77             `name` : str
  78                 The well-known name to be requested
  79             `flags` : dbus.UInt32
  80                 A bitwise-OR of 0 or more of the flags
  81                 `DBUS_NAME_FLAG_ALLOW_REPLACEMENT`,
  82                 `DBUS_NAME_FLAG_REPLACE_EXISTING`
  83                 and `DBUS_NAME_FLAG_DO_NOT_QUEUE`
  84         :Returns: `DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER`,
  85             `DBUS_REQUEST_NAME_REPLY_IN_QUEUE`,
  86             `DBUS_REQUEST_NAME_REPLY_EXISTS` or
  87             `DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER`
  88         :Raises DBusException: if the bus daemon cannot be contacted or
  89             returns an error.
  90         """
  91         validate_bus_name(name, allow_unique=False)
  92         return self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
  93                                   BUS_DAEMON_IFACE, 'RequestName',
  94                                   'su', (name, flags))
  95
  96     def release_name(self, name):
  97         """Release a bus name.
  98
  99         :Parameters:
 100             `name` : str
 101                 The well-known name to be released
 102         :Returns: `DBUS_RELEASE_NAME_REPLY_RELEASED`,
 103             `DBUS_RELEASE_NAME_REPLY_NON_EXISTENT`
 104             or `DBUS_RELEASE_NAME_REPLY_NOT_OWNER`
 105         :Raises DBusException: if the bus daemon cannot be contacted or
 106             returns an error.
 107         """
 108         validate_bus_name(name, allow_unique=False)
 109         return self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
 110                                   BUS_DAEMON_IFACE, 'ReleaseName',
 111                                   's', (name,))
 112
 113     def name_has_owner(self, bus_name):
 114         """Return True iff the given bus name has an owner on this bus.
 115
 116         :Parameters:
 117             `name` : str
 118                 The bus name to look up
 119         :Returns: a `bool`
 120         """
 121         return bool(self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
 122                                        BUS_DAEMON_IFACE, 'NameHasOwner',
 123                                        's', (bus_name,)))
 124
 125     def add_match_string(self, rule):
 126         """Arrange for this application to receive messages on the bus that
 127         match the given rule. This version will block.
 128
 129         :Parameters:
 130             `rule` : str
 131                 The match rule
 132         :Raises: `DBusException` on error.
 133         """
 134         self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
 135                            BUS_DAEMON_IFACE, 'AddMatch', 's', (rule,))
 136
 137     # FIXME: add an async success/error handler capability?
 138     # (and the same for remove_...)
 139     def add_match_string_non_blocking(self, rule):
 140         """Arrange for this application to receive messages on the bus that
 141         match the given rule. This version will not block, but any errors
 142         will be ignored.
 143
 144
 145         :Parameters:
 146             `rule` : str
 147                 The match rule
 148         :Raises: `DBusException` on error.
 149         """
 150         self.call_async(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
 151                         BUS_DAEMON_IFACE, 'AddMatch', 's', (rule,),
 152                         None, None)
 153
 154     def remove_match_string(self, rule):
 155         """Arrange for this application to receive messages on the bus that
 156         match the given rule. This version will block.
 157
 158         :Parameters:
 159             `rule` : str
 160                 The match rule
 161         :Raises: `DBusException` on error.
 162         """
 163         self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
 164                            BUS_DAEMON_IFACE, 'RemoveMatch', 's', (rule,))
 165
 166     def remove_match_string_non_blocking(self, rule):
 167         """Arrange for this application to receive messages on the bus that
 168         match the given rule. This version will not block, but any errors
 169         will be ignored.
 170
 171
 172         :Parameters:
 173             `rule` : str
 174                 The match rule
 175         :Raises: `DBusException` on error.
 176         """
 177         self.call_async(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
 178                         BUS_DAEMON_IFACE, 'RemoveMatch', 's', (rule,),
 179                         None, None)