2018-07-03 00:15:39 +03:00
<?xml version='1.0'?>
2019-03-14 16:40:58 +03:00
< !DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
2016-06-21 18:52:32 +03:00
<!--
2020-11-09 07:23:58 +03:00
SPDX-License-Identifier: LGPL-2.1-or-later
2017-11-18 19:22:32 +03:00
2018-06-12 20:00:24 +03:00
Copyright © 2016 Julian Orth
2016-06-21 18:52:32 +03:00
-->
2018-08-03 18:34:40 +03:00
<refentry id= "sd_bus_add_match" xmlns:xi= "http://www.w3.org/2001/XInclude" >
2016-06-21 18:52:32 +03:00
<refentryinfo >
<title > sd_bus_add_match</title>
<productname > systemd</productname>
</refentryinfo>
<refmeta >
<refentrytitle > sd_bus_add_match</refentrytitle>
<manvolnum > 3</manvolnum>
</refmeta>
<refnamediv >
<refname > sd_bus_add_match</refname>
2017-12-20 18:31:58 +03:00
<refname > sd_bus_add_match_async</refname>
<refname > sd_bus_match_signal</refname>
<refname > sd_bus_match_signal_async</refname>
2016-06-21 18:52:32 +03:00
2017-12-20 18:31:58 +03:00
<refpurpose > Add a match rule for incoming message dispatching</refpurpose>
2016-06-21 18:52:32 +03:00
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcsynopsisinfo > #include < systemd/sd-bus.h> </funcsynopsisinfo>
2020-05-19 20:05:03 +03:00
<funcprototype id= "sd_bus_message_handler_t" >
2017-12-20 18:31:58 +03:00
<funcdef > typedef int (*<function > sd_bus_message_handler_t</function> )</funcdef>
<paramdef > sd_bus_message *<parameter > m</parameter> </paramdef>
<paramdef > void *<parameter > userdata</parameter> </paramdef>
<paramdef > sd_bus_error *<parameter > ret_error</parameter> </paramdef>
</funcprototype>
2016-06-21 18:52:32 +03:00
<funcprototype >
<funcdef > int <function > sd_bus_add_match</function> </funcdef>
<paramdef > sd_bus *<parameter > bus</parameter> </paramdef>
<paramdef > sd_bus_slot **<parameter > slot</parameter> </paramdef>
<paramdef > const char *<parameter > match</parameter> </paramdef>
<paramdef > sd_bus_message_handler_t <parameter > callback</parameter> </paramdef>
<paramdef > void *<parameter > userdata</parameter> </paramdef>
</funcprototype>
<funcprototype >
2017-12-20 18:31:58 +03:00
<funcdef > int <function > sd_bus_add_match_async</function> </funcdef>
<paramdef > sd_bus *<parameter > bus</parameter> </paramdef>
<paramdef > sd_bus_slot **<parameter > slot</parameter> </paramdef>
<paramdef > const char *<parameter > match</parameter> </paramdef>
<paramdef > sd_bus_message_handler_t <parameter > callback</parameter> </paramdef>
<paramdef > sd_bus_message_handler_t <parameter > install_callback</parameter> </paramdef>
<paramdef > void *<parameter > userdata</parameter> </paramdef>
</funcprototype>
<funcprototype >
<funcdef > int <function > sd_bus_match_signal</function> </funcdef>
<paramdef > sd_bus *<parameter > bus</parameter> </paramdef>
<paramdef > sd_bus_slot **<parameter > slot</parameter> </paramdef>
<paramdef > const char *<parameter > sender</parameter> </paramdef>
<paramdef > const char *<parameter > path</parameter> </paramdef>
<paramdef > const char *<parameter > interface</parameter> </paramdef>
<paramdef > const char *<parameter > member</parameter> </paramdef>
<paramdef > sd_bus_message_handler_t <parameter > callback</parameter> </paramdef>
<paramdef > void *<parameter > userdata</parameter> </paramdef>
</funcprototype>
<funcprototype >
<funcdef > int <function > sd_bus_match_signal_async</function> </funcdef>
<paramdef > sd_bus *<parameter > bus</parameter> </paramdef>
<paramdef > sd_bus_slot **<parameter > slot</parameter> </paramdef>
<paramdef > const char *<parameter > sender</parameter> </paramdef>
<paramdef > const char *<parameter > path</parameter> </paramdef>
<paramdef > const char *<parameter > interface</parameter> </paramdef>
<paramdef > const char *<parameter > member</parameter> </paramdef>
<paramdef > sd_bus_message_handler_t <parameter > callback</parameter> </paramdef>
<paramdef > sd_bus_message_handler_t <parameter > install_callback</parameter> </paramdef>
2016-06-21 18:52:32 +03:00
<paramdef > void *<parameter > userdata</parameter> </paramdef>
</funcprototype>
2017-12-20 18:31:58 +03:00
2016-06-21 18:52:32 +03:00
</funcsynopsis>
</refsynopsisdiv>
<refsect1 >
<title > Description</title>
2017-12-20 18:31:58 +03:00
<para > <function > sd_bus_add_match()</function> installs a match rule for messages received on the specified bus
connection object <parameter > bus</parameter> . The syntax of the match rule expression passed in
<parameter > match</parameter> is described in the <ulink
url="https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus Specification</ulink> . The specified handler
2021-03-06 20:54:33 +03:00
function <parameter > callback</parameter> is called for each incoming message matching the specified expression,
2017-12-20 18:31:58 +03:00
the <parameter > userdata</parameter> 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.</para>
2022-08-23 13:12:28 +03:00
<para > <function > sd_bus_add_match_async()</function> operates very similarly to
2021-03-06 20:54:33 +03:00
<function > sd_bus_add_match()</function> , however it installs the match asynchronously, in a non-blocking
2017-12-20 18:31:58 +03:00
fashion: a request is sent to the broker, but the call does not wait for a response. The
<parameter > install_callback</parameter> function is called when the response is later received, with the response
message from the broker as parameter. If this function is specified as <constant > NULL</constant> a default
implementation is used that terminates the bus connection should installing the match fail.</para>
<para > <function > sd_bus_match_signal()</function> is very similar to <function > sd_bus_add_match()</function> , but
only matches signals, and instead of a match expression accepts four parameters: <parameter > sender</parameter> (the
service name of the sender), <parameter > path</parameter> (the object path of the emitting object),
<parameter > interface</parameter> (the interface the signal belongs to), <parameter > member</parameter> (the signal
name), from which the match string is internally generated. Optionally, these parameters may be specified as
<constant > NULL</constant> in which case the relevant field of incoming signals is not tested.</para>
2018-05-30 17:28:28 +03:00
<para > <function > sd_bus_match_signal_async()</function> combines the signal matching logic of
2017-12-20 18:31:58 +03:00
<function > sd_bus_match_signal()</function> with the asynchronous behaviour of
<function > sd_bus_add_match_async()</function> .</para>
<para > On success, and if non-<constant > NULL</constant> , the <parameter > slot</parameter> 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
<citerefentry > <refentrytitle > sd_bus_slot_unref</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> . If specified
as <constant > NULL</constant> the lifetime of the match is bound to the lifetime of the bus object itself, and the
2018-05-30 17:33:12 +03:00
match is generally not removed independently. See
<citerefentry > <refentrytitle > sd_bus_slot_set_floating</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> for
details.</para>
2017-12-20 18:31:58 +03:00
<para > The message <parameter > m</parameter> passed to the callback is only borrowed, that is, the callback should
not call <citerefentry > <refentrytitle > sd_bus_message_unref</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
on it. If the callback wants to hold on to the message beyond the lifetime of the callback, it needs to call
<citerefentry > <refentrytitle > sd_bus_message_ref</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> to create a
new reference.</para>
<para > 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 <parameter > ret_error</parameter> , 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.
2016-06-21 18:52:32 +03:00
</para>
2017-12-20 18:31:58 +03:00
<para > If the <parameter > bus</parameter> refers to a direct connection (i.e. not a bus connection, as set with
<citerefentry > <refentrytitle > sd_bus_set_bus_client</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ) the
match is only installed on the client side, and the synchronous and asynchronous functions operate the same.</para>
</refsect1>
2016-06-21 18:52:32 +03:00
2017-12-20 18:31:58 +03:00
<refsect1 >
<title > Return Value</title>
2017-05-18 19:24:17 +03:00
<para >
2017-12-20 18:31:58 +03:00
On success, <function > sd_bus_add_match()</function> and the other calls return 0 or a positive integer. On
failure, they return a negative errno-style error code.
2016-06-21 18:52:32 +03:00
</para>
</refsect1>
<refsect1 >
2017-12-20 18:31:58 +03:00
<title > Notes</title>
2016-06-21 18:52:32 +03:00
2018-08-03 18:34:40 +03:00
<xi:include href= "libsystemd-pkgconfig.xml" xpointer= "pkgconfig-text" />
2016-06-21 18:52:32 +03:00
</refsect1>
<refsect1 >
<title > See Also</title>
<para >
<citerefentry > <refentrytitle > systemd</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> ,
2017-12-20 18:31:58 +03:00
<citerefentry > <refentrytitle > sd-bus</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > sd_bus_slot_unref</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > sd_bus_message_ref</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
2018-05-30 17:33:12 +03:00
<citerefentry > <refentrytitle > sd_bus_set_bus_client</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > sd_bus_slot_set_floating</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
2016-06-21 18:52:32 +03:00
</para>
</refsect1>
</refentry>