Signal filtering

[John (J5) Palmieri]

On Fri, 2005-08-26 at 11:50 +0200, Philip Van Hoof wrote:
> Hi there,
> 
> At this moment I'm working on a specification. For the specification I
> will have use the D-BUS signal filtering features.

Filtering has been in since the beginning.  We just added filtering on
argument types.   

> I was wondering what the status of this feature is. If it's implemented
> and ready for use I'd like to know how I can use it. I'd also like to
> know where I can find documentation or source code from which I can
> learn myself how I'd have to use it.

libhal has some good examples.  The filtering stuff isn't documented
extensively but I believe it is on our TODO.  To add a match rule you
call the dbus_bus_add_match:

dbus_bus_add_match (dbus_connection,
			    "type='signal',"
			    "interface='org.freedesktop.Hal.Manager',"
			    "sender='org.freedesktop.Hal',"
			    "path='/org/freedesktop/Hal/Manager'", &error);

Basically it takes a dbus connection object, a string of comma seperated
key/value pairs that specify the rule and a dbus error object so you can
get errors back.  If you exclude any of the key value pairs it becomes a
wildcard (i.e. if you exclude all but the type='signal' key you would
get all signals coming from the bus).

With the latest releases 0.36.x you can add arg keys.  So arg0, arg1,
arg2 ... argn.  They will match on arguments sent by the signal or
method.

> And when making a specification (like dbus-specification.html) what
> would be the preferred notation for this feature?
> 
> Like:
> 
> org.freedesktop.DBus.NameOwnerChanged
> This is a signal: 
>             NameOwnerChanged (STRING name, STRING old_owner, STRING new_owner)
> 

Filters shouldn't be noted in a specification.  They are optimizations
so that every program is not spammed by every signal that goes over the
bus.  In fact if you use the bindings filters are hidden from the user.

-- 
John (J5) Palmieri <johnp at redhat.com>