sd_bus_add_match

Index · Directives systemd 234

## Name

sd_bus_add_match — Add a match rule for message dispatching

## Synopsis

    #include <systemd/sd-bus.h>

`int sd_bus_add_match(` | sd_bus *bus,
| sd_bus_slot **slot,
| const char *match,
| sd_bus_message_handler_t callback,
| void *userdata`)`;

`typedef int (*sd_bus_message_handler_t)(` | sd_bus_message *m,
| void *userdata,
| sd_bus_error *ret_error`)`;

## Description

`sd_bus_add_match()` installs a match rule for incoming messages received on the specified bus connection object `bus`. The syntax of the match rule expression passed in `match` is described in the D-Bus Specification. The specified handler function `callback` is called for eaching incoming message matching the specified expression, the `userdata` parameter is passed as-is to the callback function.

On success, and if non-`NULL`, the `slot` return parameter will be set to a slot object that may be used as a reference to the installed match, and may be utilized to remove it again at a later time with sd_bus_slot_unref(3). If specified as `NULL` the lifetime of the match is bound to the lifetime of the bus object itself, and the match cannot be removed independently.

The message `m` passed to the callback is only borrowed, that is, the callback should not call sd_bus_message_unref(3) on it. If the callback wants to hold on to the message beyond the lifetime of the callback, it needs to call sd_bus_message_ref(3) to create a new reference.

If an error occurs during the callback invocation, the callback should return a negative error number. If it wants other callbacks that match the same rule to be called, it should return 0. Otherwise it should return a positive integer.

## Return Value

On success, `sd_bus_add_match()` returns 0 or a positive integer. On failure, it returns a negative errno-style error code.

## See Also

systemd(1), sd-bus(3)