sd_bus_add_match(3)

1SD_BUS_ADD_MATCH(3)            sd_bus_add_match            SD_BUS_ADD_MATCH(3)
2
3
4

NAME

6       sd_bus_add_match, sd_bus_add_match_async, sd_bus_match_signal,
7       sd_bus_match_signal_async - Add a match rule for incoming message
8       dispatching
9

SYNOPSIS

11       #include <systemd/sd-bus.h>
12
13       typedef int (*sd_bus_message_handler_t)(sd_bus_message *m,
14                                               void *userdata,
15                                               sd_bus_error *ret_error);
16
17       int sd_bus_add_match(sd_bus *bus, sd_bus_slot **slot,
18                            const char *match,
19                            sd_bus_message_handler_t callback,
20                            void *userdata);
21
22       int sd_bus_add_match_async(sd_bus *bus, sd_bus_slot **slot,
23                                  const char *match,
24                                  sd_bus_message_handler_t callback,
25                                  sd_bus_message_handler_t install_callback,
26                                  void *userdata);
27
28       int sd_bus_match_signal(sd_bus *bus, sd_bus_slot **slot,
29                               const char *sender, const char *path,
30                               const char *interface, const char *member,
31                               sd_bus_message_handler_t callback,
32                               void *userdata);
33
34       int sd_bus_match_signal_async(sd_bus *bus, sd_bus_slot **slot,
35                                     const char *sender, const char *path,
36                                     const char *interface,
37                                     const char *member,
38                                     sd_bus_message_handler_t callback,
39                                     sd_bus_message_handler_t install_callback,
40                                     void *userdata);
41

DESCRIPTION

43       sd_bus_add_match() installs a match rule for messages received on the
44       specified bus connection object bus. The syntax of the match rule
45       expression passed in match is described in the D-Bus Specification[1].
46       The specified handler function callback is called for each incoming
47       message matching the specified expression, the userdata parameter is
48       passed as-is to the callback function. The match is installed
49       synchronously when connected to a bus broker, i.e. the call sends a
50       control message requested the match to be added to the broker and waits
51       until the broker confirms the match has been installed successfully.
52
53       sd_bus_add_match_async() operates very similar to sd_bus_add_match(),
54       however it installs the match asynchronously, in a non-blocking
55       fashion: a request is sent to the broker, but the call does not wait
56       for a response. The install_callback function is called when the
57       response is later received, with the response message from the broker
58       as parameter. If this function is specified as NULL a default
59       implementation is used that terminates the bus connection should
60       installing the match fail.
61
62       sd_bus_match_signal() is very similar to sd_bus_add_match(), but only
63       matches signals, and instead of a match expression accepts four
64       parameters: sender (the service name of the sender), path (the object
65       path of the emitting object), interface (the interface the signal
66       belongs to), member (the signal name), from which the match string is
67       internally generated. Optionally, these parameters may be specified as
68       NULL in which case the relevant field of incoming signals is not
69       tested.
70
71       sd_bus_match_signal_async() combines the signal matching logic of
72       sd_bus_match_signal() with the asynchronous behaviour of
73       sd_bus_add_match_async().
74
75       On success, and if non-NULL, the slot return parameter will be set to a
76       slot object that may be used as a reference to the installed match, and
77       may be utilized to remove it again at a later time with
78       sd_bus_slot_unref(3). If specified as NULL the lifetime of the match is
79       bound to the lifetime of the bus object itself, and the match is
80       generally not removed independently. See sd_bus_slot_set_floating(3)
81       for details.
82
83       The message m passed to the callback is only borrowed, that is, the
84       callback should not call sd_bus_message_unref(3) on it. If the callback
85       wants to hold on to the message beyond the lifetime of the callback, it
86       needs to call sd_bus_message_ref(3) to create a new reference.
87
88       If an error occurs during the callback invocation, the callback should
89       return a negative error number (optionally, a more precise error may be
90       returned in ret_error, as well). If it wants other callbacks that match
91       the same rule to be called, it should return 0. Otherwise it should
92       return a positive integer.
93
94       If the bus refers to a direct connection (i.e. not a bus connection, as
95       set with sd_bus_set_bus_client(3)) the match is only installed on the
96       client side, and the synchronous and asynchronous functions operate the
97       same.
98

RETURN VALUE

100       On success, sd_bus_add_match() and the other calls return 0 or a
101       positive integer. On failure, they return a negative errno-style error
102       code.
103

NOTES

105       These APIs are implemented as a shared library, which can be compiled
106       and linked to with the libsystemd pkg-config(1) file.
107

NOTES

113        1. D-Bus Specification
114           https://dbus.freedesktop.org/doc/dbus-specification.html
115
116
117
118systemd 249                                                SD_BUS_ADD_MATCH(3)

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

SEE ALSO

NOTES