From 8d1e7dfeb9f68541225e7a990dd700d35bb8342c Mon Sep 17 00:00:00 2001 From: "John (J5) Palmieri" Date: Thu, 18 Aug 2005 04:04:57 +0000 Subject: * ChangeLog: clean up my last entry a bit * doc/introspect.xsl: New stylesheet for converting introspection data into browser renderable xhtml. Contributed by Lennart Poettering. * doc/introspect.dtd: Fixups in the introspect format from Lennart Poettering. * doc/dbus-tutorial.xml: - Add Colin Walter to the Authors section for authoring the GLib section - Add descriptions of the new signature and type functionality in the Python complex type mapping section - Add a sidenote on the new args matching functionality in the Python bindings - Fixed up some of the examples to use the gobject.MainLoop instead of gtk.main * python/_dbus.py: (Bus::_create_args_dict): New. Converts a hash of arg matches to a more useable format (Bus::add_signal_receiver): add a **keywords parameter for catching arg match parameters (Bus::remove_signal_receiver): add a **keywords parameter for catching arg match parameters * python/matchrules.py: (MatchTree::exec_matches): Check for arg matches (SignalMatchRule::add_args_match): New method (SignalMatchRule::execute): Added args_list parameter as an optimization so we don't have to marshal the args more than once (SignalMatchRule::match_args_from_list): New method that checks to see if the rule's arg matches match an argument list. Only arguments set in the rule are checked. (SignalMatchRule::match_args_from_rule): New method that checks to see if the rule's arg matches match another rule's. All args have to match in order for this method to return true. If either rule has more args then it is not a match. (SignalMatchRule::is_match): Add args match (SignalMatchRule::repr): Add args to the final output if they exist --- ChangeLog | 99 +++++++++++++++++++------- doc/Makefile.am | 3 +- doc/dbus-tutorial.xml | 99 ++++++++++++++++++++++---- doc/introspect.dtd | 19 ++--- doc/introspect.xsl | 106 ++++++++++++++++++++++++++++ python/_dbus.py | 55 +++++++++++++-- python/examples/example-signal-recipient.py | 3 +- python/matchrules.py | 64 +++++++++++++++-- 8 files changed, 386 insertions(+), 62 deletions(-) create mode 100644 doc/introspect.xsl diff --git a/ChangeLog b/ChangeLog index 155b773e..a131af27 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,45 @@ +2005-08-17 John (J5) Palmieri + * ChangeLog: clean up my last entry a bit + + * doc/introspect.xsl: New stylesheet for converting introspection data + into browser renderable xhtml. Contributed by Lennart Poettering. + + * doc/introspect.dtd: Fixups in the introspect format from Lennart + Poettering. + + * doc/dbus-tutorial.xml: + - Add Colin Walter to the Authors section for authoring the GLib + section + - Add descriptions of the new signature and type functionality + in the Python complex type mapping section + - Add a sidenote on the new args matching functionality in + the Python bindings + - Fixed up some of the examples to use the gobject.MainLoop + instead of gtk.main + + * python/_dbus.py: + (Bus::_create_args_dict): New. Converts a hash of arg matches + to a more useable format + (Bus::add_signal_receiver): add a **keywords parameter for catching + arg match parameters + (Bus::remove_signal_receiver): add a **keywords parameter for catching + arg match parameters + + * python/matchrules.py: + (MatchTree::exec_matches): Check for arg matches + (SignalMatchRule::add_args_match): New method + (SignalMatchRule::execute): Added args_list parameter as an optimization + so we don't have to marshal the args more than once + (SignalMatchRule::match_args_from_list): New method that checks to see + if the rule's arg matches match an argument list. Only arguments + set in the rule are checked. + (SignalMatchRule::match_args_from_rule): New method that checks to see + if the rule's arg matches match another rule's. All args have to match + in order for this method to return true. If either rule has more args + then it is not a match. + (SignalMatchRule::is_match): Add args match + (SignalMatchRule::repr): Add args to the final output if they exist + 2005-08-17 Ross Burton * glib/dbus-gproxy.c: @@ -11,37 +53,40 @@ * python/dbus_bindings.pyx: - Fixed type objects to have self passed into __init__ - Added the Variant type - - Add the ability to specify types or signatures for Array, Variant and Dictionary - - (Connection::send_with_reply_handlers): return a PendingCall object - - (_pending_call_notification): handle the case when an error is returned + - Add the ability to specify types or signatures for Array, Variant + and Dictionary + (Connection::send_with_reply_handlers): return a PendingCall object + (_pending_call_notification): handle the case when an error is returned without an error message in the body - - (MessageIter::get_boolean): return True or False instead of an integer - - (MessageIter::python_value_to_dbus_sig): add direct checking of types and - add checks for objects with embeded signatures or types (Array, Variant and - Dictionary) - - (MessageIter::append_byte): handle case when the value is a dbus.Byte - - (MessageIter::append_dict): handle embeded types or signatures - - (MessageIter::append_array): handle embeded types or signatures - - (MessageIter::append_variant): new method + (MessageIter::get_boolean): return True or False instead of an integer + (MessageIter::python_value_to_dbus_sig): add direct checking of types + and add checks for objects with embeded signatures or types (Array, + Variant and Dictionary) + (MessageIter::append_byte): handle case when the value is a dbus.Byte + (MessageIter::append_dict): handle embeded types or signatures + (MessageIter::append_array): handle embeded types or signatures + (MessageIter::append_variant): new method * python/proxies.py: - - (DeferedMethod): New. Dummy executable object used when queuing calls blocking on - introspection data - - (ProxyMethod::__call__): add the timeout keyword for specifying longer or - shorter timeouts for method calls - - (ProxyObject): Add first pass at an introspection state machine - - (ProxyObject::__init__): Add introspect keyword for turing off an on + (DeferedMethod): New. Dummy executable object used when queuing calls + blocking on introspection data + (ProxyMethod::__call__): add the timeout keyword for specifying longer + or shorter timeouts for method calls + (ProxyObject): Add first pass at an introspection state machine + (ProxyObject::__init__): Add introspect keyword for turing off an on introspection. - - (ProxyObject::_Introspect): Internal Introspect call that bypasses the usual - mechanisms for sending messages. This is to avoid a deadlock where the Intospect - call would be queued waiting for the Introspect call to finish ;-) - - (ProxyObject::_introspect_reply_handler): New. This method is called when - introspection returns with no error - - (ProxyObject::_introspect_error_handler): New. This method is called when - introspection encounters an error - - (ProxyObject::__getattr__): Code to handle different introspection states. - Queue async calls or block blocking calls if we are introspecting. Pass through - as normal if we are not or are done with introspecting. + (ProxyObject::_Introspect): Internal Introspect call that bypasses + the usual mechanisms for sending messages. This is to avoid a deadlock + where the Intospect call would be queued waiting for the Introspect + call to finish ;-) + (ProxyObject::_introspect_reply_handler): New. This method is called + when introspection returns with no error + (ProxyObject::_introspect_error_handler): New. This method is called + when introspection encounters an error + (ProxyObject::__getattr__): Code to handle different introspection + states. Queue async calls or block blocking calls if we are + introspecting. Pass through as normal if we are not or are done with + introspecting. * python/service.py: Import signal and method from decorators.py diff --git a/doc/Makefile.am b/doc/Makefile.am index 3032c866..8a252ad3 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -6,7 +6,8 @@ EXTRA_DIST= \ dbus-test-plan.xml \ dbus-tutorial.xml \ dcop-howto.txt \ - file-boilerplate.c + file-boilerplate.c \ + introspect.xsl HTML_FILES= \ dbus-faq.html \ diff --git a/doc/dbus-tutorial.xml b/doc/dbus-tutorial.xml index d066c0a9..a5b210b6 100644 --- a/doc/dbus-tutorial.xml +++ b/doc/dbus-tutorial.xml @@ -34,7 +34,16 @@ - + + Colin + Walters + + Red Hat, Inc. +
+ walters@redhat.com +
+ + @@ -1195,7 +1204,7 @@ main (int argc, char **argv) D-BUS basic type - Python object + Python wrapper Notes @@ -1269,6 +1278,7 @@ main (int argc, char **argv) D-BUS type Python type + Python wrapper Notes @@ -1276,28 +1286,63 @@ main (int argc, char **argv) ARRAY Python lists + dbus.Array Python lists, denoted by square brackets [], are converted into arrays and visa versa. The one restriction is that when sending a Python list each element of the list must be of the same - type. This is because D-BUS arrays can contain only one element type. Use Python tuples for mixed types. + type. This is because D-BUS arrays can contain only one element type. Use Python tuples for mixed types. + + When using the wrapper you may also specify a type or signature of the elements contained in the Array. + This is manditory when passing an empty Array to a method on the bus because Python can not guess at the + contents of an empty array. For example if a method is expecting an Array of int32's and you need to pass + it an empty Array you would do it as such: + + emptyint32array = dbus.Array([], type=dbus.Int32) + + or + + emptyint32array = dbus.Array([], signature="i") + + Note that dbus.Array derives from list so it acts just like a python list. + STRUCT Python tuple + dbus.Struct Python tuples, denoted by parentheses (,), are converted into structs and visa versa. Tuples can have mixed types. DICTIONARY Python dictionary + dbus.Dictionary D-BUS doesn't have an explicit dictionary type. Instead it uses LISTS of DICT_ENTRIES to represent a dictionary. A DICT_ENTRY is simply a two element struct containing a key/value pair. - Python dictionaries are automatically converted to a LIST of DICT_ENTRIES and visa versa. + Python dictionaries are automatically converted to a LIST of DICT_ENTRIES and visa versa. + + Since dictonaries are described as lists of dict_entries we also need the signature in order + to pass empty dictionaries. The wrapper provides a way of specifying this through the key_type/value_type + type parameters or the signature parameters. To send an empty Dictionary where the key is a string + and the value is a string you would do it as such: + + emptystringstringdict = dbus.Dictionary({}, key_type=dbus.String, value_type=dbus.Value) + + or + + emptystringstringdict = dbus.Dictionary({}, signature="ss") + + Note that dbus.Dictionary derives from dict so it acts just like a python dictionary. + VARIANT any type + dbus.Variant A variant is a container for any type. Python exports its methods to accept only variants - since we are an untyped language and can demarshal into any Python type. + since we are an untyped language and can demarshal into any Python type. + + To send a variant you must first wrap it in adbus.Variant. If no type or signiture is + given to the variant the marshaler will get the type from the contents. @@ -1340,7 +1385,7 @@ proxy_obj.ListNames(dbus_interface = 'org.freedesktop.DBus') calls allows you to return control to the GUI while you wait for the reply. This is exceedingly easy to do in Python. Here is an example using the GLib/GTK+ mainloop. -import gtk +import gobject import dbus if getattr(dbus, 'version', (0,0,0)) >= (0,41,0): import dbus.glib @@ -1357,7 +1402,8 @@ dbus_iface = dbus.Interface(proxy_obj, 'org.freedesktop.DBus') dbus_iface.ListNames(reply_handler=print_list_names_reply, error_handler=print_error) -gtk.main() +mainloop = gobject.MainLoop() +mainloop.run() @@ -1383,7 +1429,7 @@ gtk.main() which takes a signal name and handler as arguments. Let us look at an example of connecting to the HAL service to receive signals when devices are added and removed and when devices register a capability. This example assumes you have HAL already running. -import gtk +import gobject import dbus if getattr(dbus, 'version', (0,0,0)) >= (0,41,0): import dbus.glib @@ -1407,7 +1453,8 @@ hal_manager.connect_to_signal('DeviceAdded', device_added_callback) hal_manager.connect_to_signal('DeviceRemoved', device_removed_callback) hal_manager.connect_to_signal('NewCapability', device_capability_callback) -gtk.main() +mainloop = gobject.MainLoop() +mainloop.run() @@ -1439,6 +1486,28 @@ bus.add_signal_receiver(device_capability_callback, All this can be done without creating the proxy object if one wanted to but in most cases you would want to have a reference to the object so once a signal was received operations could be executed on the object. + + Signal matching on arguments + + Starting with D-Bus 0.36 and the (0, 43, 0) version of the python + bindings you can now add a match on arguments being sent in a signal. + This is useful for instance for only getting NameOwnerChanged + signals for your service. Lets say we create a name on the bus called + 'org.foo.MyName' we could also add a match to just get + NameOwnerChanges for that name as such: + +bus.add_signal_receiver(myname_changed, + 'NameOwnerChanged', + 'org.freedesktop.DBus', + 'org.freedesktop.DBus', + '/org/freedesktop/DBus', + arg0='org.foo.MyName') + + + It is as simple as that. To match the second arg you would use arg1=, + the third arg2=, etc. + + Cost of Creating a Proxy Object @@ -1473,6 +1542,7 @@ bus.add_signal_receiver(device_capability_callback, a Python object that inherits from dbus.service.Object. The following is the start of an example HelloWorld object that we want to export over the session bus. +import gobject import dbus import dbus.service if getattr(dbus, 'version', (0,0,0)) >= (0,41,0): @@ -1486,7 +1556,8 @@ session_bus = dbus.SessionBus() bus_name = dbus.service.BusName('org.freedesktop.HelloWorld', bus=session_bus) object = HelloWorldObject(bus_name) -gtk.main() +mainloop = gobject.MainLoop() +mainloop.run() @@ -1500,6 +1571,7 @@ gtk.main() Let's make this object do something and export a method over the bus. +import gobject import dbus import dbus.service if getattr(dbus, 'version', (0,0,0)) >= (0,41,0): @@ -1517,7 +1589,8 @@ session_bus = dbus.SessionBus() bus_name = dbus.service.BusName('org.freedesktop.HelloWorld', bus=session_bus) object = HelloWorldObject(bus_name) -gtk.main() +mainloop = gobject.MainLoop() +mainloop.run() @@ -1572,6 +1645,7 @@ print iface.hello() Setting up signals to emit is just as easy as exporting methods. It uses the same syntax as methods. +import gobject import dbus import dbus.service if getattr(dbus, 'version', (0,0,0)) >= (0,41,0): @@ -1595,7 +1669,8 @@ object = HelloWorldObject(bus_name) object.hello_signal('I sent a hello signal') -gtk.main() +mainloop = gobject.MainLoop() +mainloop.run() diff --git a/doc/introspect.dtd b/doc/introspect.dtd index fd6aa472..15d913af 100644 --- a/doc/introspect.dtd +++ b/doc/introspect.dtd @@ -4,15 +4,18 @@ - - + + - + - + + + + @@ -21,12 +24,10 @@ The DTD format can't express that subtlety. --> - - - - + + - + diff --git a/doc/introspect.xsl b/doc/introspect.xsl new file mode 100644 index 00000000..e892999a --- /dev/null +++ b/doc/introspect.xsl @@ -0,0 +1,106 @@ + + + + + + + + + + + + + DBUS Introspection data + + + + +
+

+ interface + +

+ +
    + + + + +
  • + + + + +
      + + +
    • + + + + + + + out + + + in + + + + + + + + +
      • +       +
    + +
    • +     + +
+
+ + + + + + + +
  • + annotation + = + +
    • +     + +     diff --git a/python/_dbus.py b/python/_dbus.py index 6074be16..2a290bd6 100644 --- a/python/_dbus.py +++ b/python/_dbus.py @@ -41,9 +41,10 @@ dbus_object = dbus_service.get_object('/org/freedesktop/DBus', print(dbus_object.ListServices()) """ +import dbus + import dbus_bindings -import dbus from proxies import * from exceptions import * from matchrules import * @@ -104,25 +105,67 @@ class Bus: """Get a proxy object to call over the bus""" return self.ProxyObjectClass(self, named_service, object_path) - def add_signal_receiver(self, handler_function, signal_name=None, dbus_interface=None, named_service=None, path=None): + def _create_args_dict(self, keywords): + args_dict = None + for (key, value) in keywords.iteritems(): + if key.startswith('arg'): + try: + snum = key[3:] + num = int(snum) + + if not args_dict: + args_dict = {} + + args_dict[num] = value + except ValueError: + raise TypeError("Invalid arg index %s"%snum) + else: + raise TypeError("Unknown keyword %s"%(key)) + + return args_dict + + def add_signal_receiver(self, handler_function, + signal_name=None, + dbus_inteface=None, + named_service=None, + path=None, + **keywords): + + args_dict = self._create_args_dict(keywords) + if (named_service and named_service[0] != ':'): bus_object = self.get_object('org.freedesktop.DBus', '/org/freedesktop/DBus') named_service = bus_object.GetNameOwner(named_service, dbus_interface='org.freedesktop.DBus') match_rule = SignalMatchRule(signal_name, dbus_interface, named_service, path) + + if args_dict: + match_rule.add_args_match(args_dict) + match_rule.add_handler(handler_function) self._match_rule_tree.add(match_rule) - dbus_bindings.bus_add_match(self._connection, str(match_rule)) + dbus_bindings.bus_add_match(self._connection, repr(match_rule)) - def remove_signal_receiver(self, handler_function, signal_name=None, dbus_interface=None, named_service=None, path=None): + def remove_signal_receiver(self, handler_function, + signal_name=None, + dbus_interface=None, + named_service=None, + path=None, + **keywords): + + args_dict = self._create_args_dict(keywords) + if (named_service and named_service[0] != ':'): bus_object = self.get_object('org.freedesktop.DBus', '/org/freedesktop/DBus') named_service = bus_object.GetNameOwner(named_service, dbus_interface='org.freedesktop.DBus') match_rule = SignalMatchRule(signal_name, dbus_interface, named_service, path) + if (args_dict): + match_rule.add_args_match(args_dict) + if (handler_function): match_rule.add_handler(handler_function) @@ -139,8 +182,8 @@ class Bus: return dbus_bindings.HANDLER_RESULT_NOT_YET_HANDLED dbus_interface = message.get_interface() - named_service = message.get_sender() - path = message.get_path() + named_service = message.get_sender() + path = message.get_path() signal_name = message.get_member() match_rule = SignalMatchRule(signal_name, dbus_interface, named_service, path) diff --git a/python/examples/example-signal-recipient.py b/python/examples/example-signal-recipient.py index 558a41f0..a06d4943 100644 --- a/python/examples/example-signal-recipient.py +++ b/python/examples/example-signal-recipient.py @@ -38,13 +38,14 @@ def catchall_hello_signals_handler(hello_string): def catchall_testservice_interface_handler(hello_string, dbus_message): print "org.designfu.TestService interface says " + hello_string + " when it sent signal " + dbus_message.get_member() -object.connect_to_signal("HelloSignal", hello_signal_handler, dbus_interface="org.designfu.TestService") +object.connect_to_signal("HelloSignal", hello_signal_handler, dbus_interface="org.designfu.TestService", arg0="Hello") #lets make a catchall bus.add_signal_receiver(catchall_signal_handler) bus.add_signal_receiver(catchall_hello_signals_handler, dbus_interface = "org.designfu.TestService", signal_name = "HelloSignal") bus.add_signal_receiver(catchall_testservice_interface_handler, dbus_interface = "org.designfu.TestService") + gobject.timeout_add(2000, emit_signal) # Tell the remote object to emit the signal diff --git a/python/matchrules.py b/python/matchrules.py index d65e3920..3a2fbedf 100644 --- a/python/matchrules.py +++ b/python/matchrules.py @@ -70,6 +70,8 @@ class SignalMatchTree: path.add(rule.path, leaf=rule) def exec_matches(self, match_rule, message): + args = message.get_args_list() + sender_matches = self._tree.get_matches(match_rule.sender) for sender_node in sender_matches: interface_matches = sender_node.get_matches(match_rule.dbus_interface) @@ -80,7 +82,8 @@ class SignalMatchTree: for path_node in path_matches: if(path_node.rules): for rule in path_node.rules: - rule.execute(message) + if (rule.match_args_from_list(args)): + rule.execute(message, args) def remove(self, rule): try: @@ -121,9 +124,16 @@ class SignalMatchRule: self.dbus_interface = dbus_interface self.sender = sender self.path = path + self.args = None - def execute(self, message): - args = message.get_args_list() + def add_args_match(self, args): + self.args = args + + def execute(self, message, args=None): + #optimization just in case we already extarcted the args + if not args: + args = message.get_args_list() + for handler in self.handler_functions: if getattr(handler, "_dbus_pass_message", False): keywords = {"dbus_message": message} @@ -133,12 +143,48 @@ class SignalMatchRule: def add_handler(self, handler): self.handler_functions.append(handler) - + + #matches only those arguments listed by self + def match_args_from_list(self, args_list): + if not self.args: + return True + + last_index = len(args_list) - 1 + for (index, value) in self.args.iteritems(): + if index > last_index: + return False + + if not (args_list[index] == value): + return False + + return True + + #does exact matching + def match_args_from_rule(self, rule): + if self.args == rule.args: + return True + + if self.args == None or rule.args == None: + return False + + my_args_list = self.args.items() + match_args_list = rule.args.iterms() + + if len(my_args_list) != len(match_args_list): + return False + + for (key, value) in my_args_list: + if rule.args.get(key) != value: + return False + + return True + def is_match(self, rule): if (self.signal_name == rule.signal_name and self.dbus_interface == rule.dbus_interface and self.sender == rule.sender and - self.path == rule.path): + self.path == rule.path and + self.match_args_from_rule(rule)): if rule.handler_functions == []: return True @@ -167,5 +213,11 @@ class SignalMatchRule: if (self.signal_name): repr = repr + ",member='%s'" % (self.signal_name) - + + if (self.args): + my_args_list = self.args.items() + my_args_list.sort() + for (index, value) in my_args_list: + repr = repr + ",arg%i='%s'" % (index, value) + return repr -- cgit