# sd_bus_add_match

## 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 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.
    
           **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.
    
           **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()** 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 is generally not removed independently. See
           sd_bus_slot_set_floating(3) for details.
    
           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



           Functions described here are available as a shared library, which
           can be compiled against and linked to with the
           **libsystemd pkg-config**(1) file.
    
           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.
    


## NOTES



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


* * *