User  |  Syst  |  Libr  |  Device  |  Files  |  Other  |  Admin  |  Head  |

---

   sd_bus_match_signal    ( 3 )

---

---

Имя (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 similar 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.

---

Примечание (Note)

These APIs are implemented 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),
       sd_bus_slot_set_floating(3)

---

Примечание (Note)

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

---