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 from _dbus_bindings import validate_interface_name, validate_member_name,\
  22                            validate_bus_name, validate_object_path,\
  23                            validate_error_name,\
  24                            BUS_DAEMON_NAME, BUS_DAEMON_PATH, BUS_DAEMON_IFACE
  25
  26
  27 class _BusDaemonMixin(object):
  28     """This mixin provides simple blocking wrappers for various methods on
  29     the org.freedesktop.DBus bus-daemon object, to reduce the amount of C
  30     code we need.
  31     """
  32
  33     def get_unix_user(self, bus_name):
  34         """Get the numeric uid of the process owning the given bus name.
  35
  36         :Parameters:
  37             `bus_name` : str
  38                 A bus name, either unique or well-known
  39         :Returns: a `dbus.UInt32`
  40         """
  41         validate_bus_name(bus_name)
  42         return self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
  43                                   BUS_DAEMON_IFACE, 'GetConnectionUnixUser',
  44                                   's', (bus_name,))
  45
  46     def start_service_by_name(self, bus_name, flags=0):
  47         """Start a service which will implement the given bus name on this Bus.
  48
  49         :Parameters:
  50             `bus_name` : str
  51                 The well-known bus name to be activated.
  52             `flags` : dbus.UInt32
  53                 Flags to pass to StartServiceByName (currently none are
  54                 defined)
  55
  56         :Returns: A tuple of 2 elements. The first is always True, the
  57             second is either START_REPLY_SUCCESS or
  58             START_REPLY_ALREADY_RUNNING.
  59
  60         :Raises DBusException: if the service could not be started.
  61         """
  62         validate_bus_name(bus_name)
  63         return (True, self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
  64                                          BUS_DAEMON_IFACE,
  65                                          'StartServiceByName',
  66                                          'su', (bus_name, flags)))
  67
  68     # XXX: it might be nice to signal IN_QUEUE, EXISTS by exception,
  69     # but this would not be backwards-compatible
  70     def request_name(self, name, flags=0):
  71         """Request a bus name.
  72
  73         :Parameters:
  74             `name` : str
  75                 The well-known name to be requested
  76             `flags` : dbus.UInt32
  77                 A bitwise-OR of 0 or more of the flags
  78                 `DBUS_NAME_FLAG_ALLOW_REPLACEMENT`,
  79                 `DBUS_NAME_FLAG_REPLACE_EXISTING`
  80                 and `DBUS_NAME_FLAG_DO_NOT_QUEUE`
  81         :Returns: `DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER`,
  82             `DBUS_REQUEST_NAME_REPLY_IN_QUEUE`,
  83             `DBUS_REQUEST_NAME_REPLY_EXISTS` or
  84             `DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER`
  85         :Raises DBusException: if the bus daemon cannot be contacted or
  86             returns an error.
  87         """
  88         validate_bus_name(name, allow_unique=False)
  89         return self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
  90                                   BUS_DAEMON_IFACE, 'RequestName',
  91                                   'su', (name, flags))
  92
  93     def release_name(self, name):
  94         """Release a bus name.
  95
  96         :Parameters:
  97             `name` : str
  98                 The well-known name to be released
  99         :Returns: `DBUS_RELEASE_NAME_REPLY_RELEASED`,
 100             `DBUS_RELEASE_NAME_REPLY_NON_EXISTENT`
 101             or `DBUS_RELEASE_NAME_REPLY_NOT_OWNER`
 102         :Raises DBusException: if the bus daemon cannot be contacted or
 103             returns an error.
 104         """
 105         validate_bus_name(name, allow_unique=False)
 106         return self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
 107                                   BUS_DAEMON_IFACE, 'ReleaseName',
 108                                   's', (name,))
 109
 110     def list_names(self):
 111         """Return a list of all currently-owned names on the bus.
 112
 113         :Returns: a dbus.Array of dbus.UTF8String
 114         """
 115         return self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
 116                                   BUS_DAEMON_IFACE, 'ListNames',
 117                                   '', (), utf8_strings=True)
 118
 119     def list_activatable_names(self):
 120         """Return a list of all names that can be activated on the bus.
 121
 122         :Returns: a dbus.Array of dbus.UTF8String
 123         """
 124         return self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
 125                                   BUS_DAEMON_IFACE, 'ListNames',
 126                                   '', (), utf8_strings=True)
 127
 128     def get_name_owner(self, bus_name):
 129         """Return the unique connection name of the primary owner of the
 130         given name.
 131
 132         :Raises DBusException: if the `bus_name` has no owner
 133         """
 134         validate_bus_name(bus_name, allow_unique=False)
 135         return self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
 136                                   BUS_DAEMON_IFACE, 'GetNameOwner',
 137                                   's', (bus_name,), utf8_strings=True)
 138
 139     def name_has_owner(self, bus_name):
 140         """Return True iff the given bus name has an owner on this bus.
 141
 142         :Parameters:
 143             `name` : str
 144                 The bus name to look up
 145         :Returns: a `bool`
 146         """
 147         return bool(self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
 148                                        BUS_DAEMON_IFACE, 'NameHasOwner',
 149                                        's', (bus_name,)))
 150
 151     def add_match_string(self, rule):
 152         """Arrange for this application to receive messages on the bus that
 153         match the given rule. This version will block.
 154
 155         :Parameters:
 156             `rule` : str
 157                 The match rule
 158         :Raises: `DBusException` on error.
 159         """
 160         self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
 161                            BUS_DAEMON_IFACE, 'AddMatch', 's', (rule,))
 162
 163     # FIXME: add an async success/error handler capability?
 164     # (and the same for remove_...)
 165     def add_match_string_non_blocking(self, rule):
 166         """Arrange for this application to receive messages on the bus that
 167         match the given rule. This version will not block, but any errors
 168         will be ignored.
 169
 170
 171         :Parameters:
 172             `rule` : str
 173                 The match rule
 174         :Raises: `DBusException` on error.
 175         """
 176         self.call_async(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
 177                         BUS_DAEMON_IFACE, 'AddMatch', 's', (rule,),
 178                         None, None)
 179
 180     def remove_match_string(self, rule):
 181         """Arrange for this application to receive messages on the bus that
 182         match the given rule. This version will block.
 183
 184         :Parameters:
 185             `rule` : str
 186                 The match rule
 187         :Raises: `DBusException` on error.
 188         """
 189         self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
 190                            BUS_DAEMON_IFACE, 'RemoveMatch', 's', (rule,))
 191
 192     def remove_match_string_non_blocking(self, rule):
 193         """Arrange for this application to receive messages on the bus that
 194         match the given rule. This version will not block, but any errors
 195         will be ignored.
 196
 197
 198         :Parameters:
 199             `rule` : str
 200                 The match rule
 201         :Raises: `DBusException` on error.
 202         """
 203         self.call_async(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
 204                         BUS_DAEMON_IFACE, 'RemoveMatch', 's', (rule,),
 205                         None, None)