| SD_BUS_ADD_MATCH(3) | sd_bus_add_match | SD_BUS_ADD_MATCH(3) |
.SH "NAME" sd_bus_add_match, sd_bus_add_match_async,
sd_bus_match_signal, sd_bus_match_signal_async - Add a match rule for
incoming message dispatching
.SH "SYNOPSIS"
#include <systemd/sd-bus.h>
.HP 960u typedef int
(*sd_bus_message_handler_t)(sd_bus_message *m,
void *userdata,
sd_bus_error *ret_error);
.HP 504u int sd_bus_add_match(sd_bus *bus,
sd_bus_slot **slot,
const char *match,
sd_bus_message_handler_t callback,
void *userdata);
.HP 648u int sd_bus_add_match_async(sd_bus *bus,
sd_bus_slot **slot,
const char *match,
sd_bus_message_handler_t callback,
sd_bus_message_handler_t install_callback,
void *userdata);
.HP 576u int sd_bus_match_signal(sd_bus *bus,
sd_bus_slot **slot,
const char *sender,
const char *path,
const char *interface,
const char *member,
sd_bus_message_handler_t callback,
void *userdata);
.HP 720u int sd_bus_match_signal_async(sd_bus *bus,
sd_bus_slot **slot,
const char *sender,
const char *path,
const char *interface,
const char *member,
sd_bus_message_handler_t callback,
sd_bus_message_handler_t install_callback,
void *userdata);
.SH "DESCRIPTION"
.PP sd_bus_add_match() installs a match rule for 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[1]. The specified handler function callback is
called for each incoming message matching the specified expression, the
userdata parameter is passed as-is to the callback function. The
match is installed synchronously when connected to a bus broker, i.e. the
call sends a control message requested the match to be added to the broker
and waits until the broker confirms the match has been installed
successfully.
.PP sd_bus_add_match_async() operates very similarly to
sd_bus_add_match(), however it installs the match asynchronously, in
a non-blocking fashion: a request is sent to the broker, but the call does
not wait for a response. The install_callback function is called when
the response is later received, with the response message from the broker as
parameter. If this function is specified as NULL a default
implementation is used that terminates the bus connection should installing
the match fail.
.PP sd_bus_match_signal() is very similar to
sd_bus_add_match(), but only matches signals, and instead of a match
expression accepts four parameters: sender (the service name of the
sender), path (the object path of the emitting object),
interface (the interface the signal belongs to), member (the
signal name), from which the match string is internally generated.
Optionally, these parameters may be specified as NULL in which case
the relevant field of incoming signals is not tested.
.PP sd_bus_match_signal_async() combines the signal matching logic of
sd_bus_match_signal() with the asynchronous behaviour of
sd_bus_add_match_async().
.PP 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 is
generally not removed independently. See sd_bus_slot_set_floating(3)
for details.
.PP 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.
.PP If an error occurs during the callback invocation, the callback should
return a negative error number (optionally, a more precise error may be
returned in ret_error, as well). If it wants other callbacks that
match the same rule to be called, it should return 0. Otherwise, it should
return a positive integer.
.PP If the bus refers to a direct connection (i.e. not a bus
connection, as set with sd_bus_set_bus_client(3)) the match is only
installed on the client side, and the synchronous and asynchronous functions
operate the same.
.SH "RETURN VALUE"
.PP On success, sd_bus_add_match() and the other calls return 0 or a
positive integer. On failure, they return a negative errno-style error
code.
.SH "NOTES"
.PP Functions described here are available as a shared library, which can be
compiled against and linked to with the
libsystemd pkg-config(1) file.
.PP All functions listed here are thread-agnostic and only a single thread
may operate on a given object at any given time. Different threads may
access the same object at different times. Multiple independent objects may
be used from different threads in parallel.
.PP The code described here uses getenv(3), which is declared to be
not multi-thread-safe. This means that the code calling the functions
described here must not call setenv(3) from a parallel thread. It is
recommended to only do calls to setenv() from an early phase of the
program when no other threads have been started.
.SH "HISTORY"
.PP sd_bus_add_match() and sd_bus_message_handler_t() were
added in version 221.
.PP sd_bus_add_match_async(), sd_bus_match_signal(), and
sd_bus_match_signal_async() were added in version 237.
.SH "SEE ALSO"
.PP systemd(1), sd-bus(3), sd_bus_slot_unref(3),
sd_bus_message_ref(3), sd_bus_set_bus_client(3),
sd_bus_slot_set_floating(3)
NOTES
- 1.
- D-Bus Specification
| systemd 262.2 |