# Copyright (C) 2003-2007 Red Hat Inc.
# Copyright (C) 2003 David Zeuthen
# Copyright (C) 2004 Rob Taylor
# Copyright (C) 2005-2007 Collabora Ltd.
#
# SPDX-License-Identifier: MIT
#
# Permission is hereby granted, free of charge, to any person
# obtaining a copy of this software and associated documentation
# files (the "Software"), to deal in the Software without
# restriction, including without limitation the rights to use, copy,
# modify, merge, publish, distribute, sublicense, and/or sell copies
# of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
# DEALINGS IN THE SOFTWARE.
import logging
try:
from threading import RLock
except ImportError:
from dummy_threading import RLock
import _dbus_bindings
from dbus._expat_introspect_parser import process_introspection_data
from dbus.exceptions import (
DBusException, IntrospectionParserException, MissingErrorHandlerException,
MissingReplyHandlerException)
__docformat__ = 'restructuredtext'
_logger = logging.getLogger('dbus.proxies')
from _dbus_bindings import (
BUS_DAEMON_IFACE, BUS_DAEMON_NAME, BUS_DAEMON_PATH, INTROSPECTABLE_IFACE,
LOCAL_PATH)
from dbus._compat import is_py2
class _DeferredMethod:
"""A proxy method which will only get called once we have its
introspection reply.
"""
def __init__(self, proxy_method, append, block):
self._proxy_method = proxy_method
# the test suite relies on the existence of this property
self._method_name = proxy_method._method_name
self._append = append
self._block = block
def __call__(self, *args, **keywords):
if ('reply_handler' in keywords or
keywords.get('ignore_reply', False)):
# defer the async call til introspection finishes
self._append(self._proxy_method, args, keywords)
return None
else:
# we're being synchronous, so block
self._block()
return self._proxy_method(*args, **keywords)
def call_async(self, *args, **keywords):
self._append(self._proxy_method, args, keywords)
class _ProxyMethod:
"""A proxy method.
Typically a member of a ProxyObject. Calls to the
method produce messages that travel over the Bus and are routed
to a specific named Service.
"""
def __init__(self, proxy, connection, bus_name, object_path, method_name,
iface):
if object_path == LOCAL_PATH:
raise DBusException('Methods may not be called on the reserved '
'path %s' % LOCAL_PATH)
# trust that the proxy, and the properties it had, are OK
self._proxy = proxy
self._connection = connection
self._named_service = bus_name
self._object_path = object_path
# fail early if the method name is bad
_dbus_bindings.validate_member_name(method_name)
# the test suite relies on the existence of this property
self._method_name = method_name
# fail early if the interface name is bad
if iface is not None:
_dbus_bindings.validate_interface_name(iface)
self._dbus_interface = iface
def __call__(self, *args, **keywords):
reply_handler = keywords.pop('reply_handler', None)
error_handler = keywords.pop('error_handler', None)
ignore_reply = keywords.pop('ignore_reply', False)
signature = keywords.pop('signature', None)
if reply_handler is not None or error_handler is not None:
if reply_handler is None:
raise MissingReplyHandlerException()
elif error_handler is None:
raise MissingErrorHandlerException()
elif ignore_reply:
raise TypeError('ignore_reply and reply_handler cannot be '
'used together')
dbus_interface = keywords.pop('dbus_interface', self._dbus_interface)
if signature is None:
if dbus_interface is None:
key = self._method_name
else:
key = dbus_interface + '.' + self._method_name
signature = self._proxy._introspect_method_map.get(key, None)
if ignore_reply or reply_handler is not None:
self._connection.call_async(self._named_service,
self._object_path,
dbus_interface,
self._method_name,
signature,
args,
reply_handler,
error_handler,
**keywords)
else:
return self._connection.call_blocking(self._named_service,
self._object_path,
dbus_interface,
self._method_name,
signature,
args,
**keywords)
def call_async(self, *args, **keywords):
reply_handler = keywords.pop('reply_handler', None)
error_handler = keywords.pop('error_handler', None)
signature = keywords.pop('signature', None)
dbus_interface = keywords.pop('dbus_interface', self._dbus_interface)
if signature is None:
if dbus_interface:
key = dbus_interface + '.' + self._method_name
else:
key = self._method_name
signature = self._proxy._introspect_method_map.get(key, None)
self._connection.call_async(self._named_service,
self._object_path,
dbus_interface,
self._method_name,
signature,
args,
reply_handler,
error_handler,
**keywords)
class ProxyObject(object):
"""A proxy to the remote Object.
A ProxyObject is provided by the Bus. ProxyObjects
have member functions, and can be called like normal Python objects.
"""
ProxyMethodClass = _ProxyMethod
DeferredMethodClass = _DeferredMethod
INTROSPECT_STATE_DONT_INTROSPECT = 0
INTROSPECT_STATE_INTROSPECT_IN_PROGRESS = 1
INTROSPECT_STATE_INTROSPECT_DONE = 2
def __init__(self, conn=None, bus_name=None, object_path=None,
introspect=True, follow_name_owner_changes=False, **kwargs):
"""Initialize the proxy object.
:Parameters:
`conn` : `dbus.connection.Connection`
The bus or connection on which to find this object.
The keyword argument `bus` is a deprecated alias for this.
`bus_name` : str
A bus name for the application owning the object, to be used
as the destination for method calls and the sender for
signal matches. The keyword argument ``named_service`` is a
deprecated alias for this.
`object_path` : str
The object path at which the application exports the object
`introspect` : bool
If true (default), attempt to introspect the remote
object to find out supported methods and their signatures
`follow_name_owner_changes` : bool
If true (default is false) and the `bus_name` is a
well-known name, follow ownership changes for that name
"""
bus = kwargs.pop('bus', None)
if bus is not None:
if conn is not None:
raise TypeError('conn and bus cannot both be specified')
conn = bus
from warnings import warn
warn('Passing the bus parameter to ProxyObject by name is '
'deprecated: please use positional parameters',
DeprecationWarning, stacklevel=2)
named_service = kwargs.pop('named_service', None)
if named_service is not None:
if bus_name is not None:
raise TypeError('bus_name and named_service cannot both be '
'specified')
bus_name = named_service
from warnings import warn
warn('Passing the named_service parameter to ProxyObject by name '
'is deprecated: please use positional parameters',
DeprecationWarning, stacklevel=2)
if kwargs:
raise TypeError('ProxyObject.__init__ does not take these '
'keyword arguments: %s'
% ', '.join(kwargs.keys()))
if follow_name_owner_changes:
# we don't get the signals unless the Bus has a main loop
# XXX: using Bus internals
conn._require_main_loop()
self._bus = conn
if bus_name is not None:
_dbus_bindings.validate_bus_name(bus_name)
# the attribute is still called _named_service for the moment,
# for the benefit of telepathy-python
self._named_service = self._requested_bus_name = bus_name
_dbus_bindings.validate_object_path(object_path)
self.__dbus_object_path__ = object_path
if not follow_name_owner_changes:
self._named_service = conn.activate_name_owner(bus_name)
#PendingCall object for Introspect call
self._pending_introspect = None
#queue of async calls waiting on the Introspect to return
self._pending_introspect_queue = []
#dictionary mapping method names to their input signatures
self._introspect_method_map = {}
# must be a recursive lock because block() is called while locked,
# and calls the callback which re-takes the lock
self._introspect_lock = RLock()
if not introspect or self.__dbus_object_path__ == LOCAL_PATH:
self._introspect_state = self.INTROSPECT_STATE_DONT_INTROSPECT
else:
self._introspect_state = self.INTROSPECT_STATE_INTROSPECT_IN_PROGRESS
self._pending_introspect = self._Introspect()
bus_name = property(lambda self: self._named_service, None, None,
"""The bus name to which this proxy is bound. (Read-only,
may change.)
If the proxy was instantiated using a unique name, this property
is that unique name.
If the proxy was instantiated with a well-known name and with
``follow_name_owner_changes`` set false (the default), this
property is the unique name of the connection that owned that
well-known name when the proxy was instantiated, which might
not actually own the requested well-known name any more.
If the proxy was instantiated with a well-known name and with
``follow_name_owner_changes`` set true, this property is that
well-known name.
""")
requested_bus_name = property(lambda self: self._requested_bus_name,
None, None,
"""The bus name which was requested when this proxy was
instantiated.
""")
object_path = property(lambda self: self.__dbus_object_path__,
None, None,
"""The object-path of this proxy.""")
# XXX: We don't currently support this because it's the signal receiver
# that's responsible for tracking name owner changes, but it
# seems a natural thing to add in future.
#unique_bus_name = property(lambda self: something, None, None,
# """The unique name of the connection to which this proxy is
# currently bound. (Read-only, may change.)
# """)
def connect_to_signal(self, signal_name, handler_function, dbus_interface=None, **keywords):
"""Arrange for the given function to be called when the given signal
is received.
:Parameters:
`signal_name` : str
The name of the signal
`handler_function` : callable
A function to be called when the signal is emitted by
the remote object. Its positional arguments will be the
arguments of the signal; optionally, it may be given
keyword arguments as described below.
`dbus_interface` : str
Optional interface with which to qualify the signal name.
If None (the default) the handler will be called whenever a
signal of the given member name is received, whatever
its interface.
:Keywords:
`utf8_strings` : bool
If True, the handler function will receive any string
arguments as dbus.UTF8String objects (a subclass of str
guaranteed to be UTF-8). If False (default) it will receive
any string arguments as dbus.String objects (a subclass of
unicode).
`byte_arrays` : bool
If True, the handler function will receive any byte-array
arguments as dbus.ByteArray objects (a subclass of str).
If False (default) it will receive any byte-array
arguments as a dbus.Array of dbus.Byte (subclasses of:
a list of ints).
`sender_keyword` : str
If not None (the default), the handler function will receive
the unique name of the sending endpoint as a keyword
argument with this name
`destination_keyword` : str
If not None (the default), the handler function will receive
the bus name of the destination (or None if the signal is a
broadcast, as is usual) as a keyword argument with this name.
`interface_keyword` : str
If not None (the default), the handler function will receive
the signal interface as a keyword argument with this name.
`member_keyword` : str
If not None (the default), the handler function will receive
the signal name as a keyword argument with this name.
`path_keyword` : str
If not None (the default), the handler function will receive
the object-path of the sending object as a keyword argument
with this name
`message_keyword` : str
If not None (the default), the handler function will receive
the `dbus.lowlevel.SignalMessage` as a keyword argument with
this name.
`arg...` : unicode or UTF-8 str
If there are additional keyword parameters of the form
``arg``\\ *n*, match only signals where the *n*\\ th argument
is the value given for that keyword parameter. As of this time
only string arguments can be matched (in particular,
object paths and signatures can't).
"""
return \
self._bus.add_signal_receiver(handler_function,
signal_name=signal_name,
dbus_interface=dbus_interface,
bus_name=self._named_service,
path=self.__dbus_object_path__,
**keywords)
def _Introspect(self):
kwargs = {}
return self._bus.call_async(self._named_service,
self.__dbus_object_path__,
INTROSPECTABLE_IFACE, 'Introspect', '', (),
self._introspect_reply_handler,
self._introspect_error_handler,
require_main_loop=False, **kwargs)
def _introspect_execute_queue(self):
# FIXME: potential to flood the bus
# We should make sure mainloops all have idle handlers
# and do one message per idle
for (proxy_method, args, keywords) in self._pending_introspect_queue:
proxy_method(*args, **keywords)
self._pending_introspect_queue = []
def _introspect_reply_handler(self, data):
self._introspect_lock.acquire()
try:
try:
self._introspect_method_map = process_introspection_data(data)
except IntrospectionParserException as e:
self._introspect_error_handler(e)
return
self._introspect_state = self.INTROSPECT_STATE_INTROSPECT_DONE
self._pending_introspect = None
self._introspect_execute_queue()
finally:
self._introspect_lock.release()
def _introspect_error_handler(self, error):
logging.basicConfig()
_logger.error("Introspect error on %s:%s: %s.%s: %s",
self._named_service, self.__dbus_object_path__,
error.__class__.__module__, error.__class__.__name__,
error)
self._introspect_lock.acquire()
try:
_logger.debug('Executing introspect queue due to error')
self._introspect_state = self.INTROSPECT_STATE_DONT_INTROSPECT
self._pending_introspect = None
self._introspect_execute_queue()
finally:
self._introspect_lock.release()
def _introspect_block(self):
self._introspect_lock.acquire()
try:
if self._pending_introspect is not None:
self._pending_introspect.block()
# else someone still has a _DeferredMethod from before we
# finished introspection: no need to do anything special any more
finally:
self._introspect_lock.release()
def _introspect_add_to_queue(self, callback, args, kwargs):
self._introspect_lock.acquire()
try:
if self._introspect_state == self.INTROSPECT_STATE_INTROSPECT_IN_PROGRESS:
self._pending_introspect_queue.append((callback, args, kwargs))
else:
# someone still has a _DeferredMethod from before we
# finished introspection
callback(*args, **kwargs)
finally:
self._introspect_lock.release()
def __getattr__(self, member):
if member.startswith('__') and member.endswith('__'):
raise AttributeError(member)
else:
return self.get_dbus_method(member)
def get_dbus_method(self, member, dbus_interface=None):
"""Return a proxy method representing the given D-Bus method. The
returned proxy method can be called in the usual way. For instance, ::
proxy.get_dbus_method("Foo", dbus_interface='com.example.Bar')(123)
is equivalent to::
proxy.Foo(123, dbus_interface='com.example.Bar')
or even::
getattr(proxy, "Foo")(123, dbus_interface='com.example.Bar')
However, using `get_dbus_method` is the only way to call D-Bus
methods with certain awkward names - if the author of a service
implements a method called ``connect_to_signal`` or even
``__getattr__``, you'll need to use `get_dbus_method` to call them.
For services which follow the D-Bus convention of CamelCaseMethodNames
this won't be a problem.
"""
ret = self.ProxyMethodClass(self, self._bus,
self._named_service,
self.__dbus_object_path__, member,
dbus_interface)
# this can be done without taking the lock - the worst that can
# happen is that we accidentally return a _DeferredMethod just after
# finishing introspection, in which case _introspect_add_to_queue and
# _introspect_block will do the right thing anyway
if self._introspect_state == self.INTROSPECT_STATE_INTROSPECT_IN_PROGRESS:
ret = self.DeferredMethodClass(ret, self._introspect_add_to_queue,
self._introspect_block)
return ret
def __repr__(self):
return ''%(
self._bus, self._named_service, self.__dbus_object_path__, id(self))
__str__ = __repr__
class Interface(object):
"""An interface into a remote object.
An Interface can be used to wrap ProxyObjects
so that calls can be routed to their correct
D-Bus interface.
"""
def __init__(self, object, dbus_interface):
"""Construct a proxy for the given interface on the given object.
:Parameters:
`object` : `dbus.proxies.ProxyObject` or `dbus.Interface`
The remote object or another of its interfaces
`dbus_interface` : str
An interface the `object` implements
"""
if isinstance(object, Interface):
self._obj = object.proxy_object
else:
self._obj = object
self._dbus_interface = dbus_interface
object_path = property (lambda self: self._obj.object_path, None, None,
"The D-Bus object path of the underlying object")
__dbus_object_path__ = object_path
bus_name = property (lambda self: self._obj.bus_name, None, None,
"The bus name to which the underlying proxy object "
"is bound")
requested_bus_name = property (lambda self: self._obj.requested_bus_name,
None, None,
"The bus name which was requested when the "
"underlying object was created")
proxy_object = property (lambda self: self._obj, None, None,
"""The underlying proxy object""")
dbus_interface = property (lambda self: self._dbus_interface, None, None,
"""The D-Bus interface represented""")
def connect_to_signal(self, signal_name, handler_function,
dbus_interface=None, **keywords):
"""Arrange for a function to be called when the given signal is
emitted.
The parameters and keyword arguments are the same as for
`dbus.proxies.ProxyObject.connect_to_signal`, except that if
`dbus_interface` is None (the default), the D-Bus interface that
was passed to the `Interface` constructor is used.
"""
if not dbus_interface:
dbus_interface = self._dbus_interface
return self._obj.connect_to_signal(signal_name, handler_function,
dbus_interface, **keywords)
def __getattr__(self, member):
if member.startswith('__') and member.endswith('__'):
raise AttributeError(member)
else:
return self._obj.get_dbus_method(member, self._dbus_interface)
def get_dbus_method(self, member, dbus_interface=None):
"""Return a proxy method representing the given D-Bus method.
This is the same as `dbus.proxies.ProxyObject.get_dbus_method`
except that if `dbus_interface` is None (the default),
the D-Bus interface that was passed to the `Interface` constructor
is used.
"""
if dbus_interface is None:
dbus_interface = self._dbus_interface
return self._obj.get_dbus_method(member, dbus_interface)
def __repr__(self):
return ''%(
self._obj, self._dbus_interface, id(self))
__str__ = __repr__