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

SYNOPSIS

       #include <systemd/sd-bus.h>

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

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

       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);

       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);

       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);

DESCRIPTION

       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 eaching 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.

       sd_bus_add_match_async() operates very similar to sd_bus_match_signal(), 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.

       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.

       sd_bus_match_signal_async() is combines the signal matching logic of sd_bus_match_signal() with the
       asynchronous behaviour of sd_bus_add_match_async().

       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
       (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.

       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.

RETURN VALUE

       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.

NOTES

       sd_bus_add_match() and the other functions described here are available as a shared library, which can be
       compiled and linked to with the libsystemd pkg-config(1) file.

SEE ALSO

       systemd(1), sd-bus(3), sd_bus_slot_unref(3), sd_bus_message_ref(3), sd_bus_set_bus_client(3)

NOTES

        1. D-Bus Specification
           https://dbus.freedesktop.org/doc/dbus-specification.html