1SD_BUS_ADD_MATCH(3) sd_bus_add_match SD_BUS_ADD_MATCH(3)
2
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
11 #include <systemd/sd-bus.h>
12 typedef int (*sd_bus_message_handler_t)(sd_bus_message *m,
14 void *userdata,
15 sd_bus_error *ret_error);
16 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 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 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 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
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 sd_bus_add_match_async() operates very similarly 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 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 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 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 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 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 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
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
105 Functions described here are available as a shared library, which can
106 be compiled against and linked to with the libsystemd pkg-config(1)
107 file.
108 The code described here uses getenv(3), which is declared to be not
110 multi-thread-safe. This means that the code calling the functions
111 described here must not call setenv(3) from a parallel thread. It is
112 recommended to only do calls to setenv() from an early phase of the
113 program when no other threads have been started.
114
116 systemd(1), sd-bus(3), sd_bus_slot_unref(3), sd_bus_message_ref(3),
117 sd_bus_set_bus_client(3), sd_bus_slot_set_floating(3)
118
120 1. D-Bus Specification
121 https://dbus.freedesktop.org/doc/dbus-specification.html
122systemd 254 SD_BUS_ADD_MATCH(3)