man/sd_bus_add_match.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7
   8   This file is part of systemd.
   9
  10   Copyright 2016 Julian Orth
  11
  12   systemd is free software; you can redistribute it and/or modify it
  13   under the terms of the GNU Lesser General Public License as published by
  14   the Free Software Foundation; either version 2.1 of the License, or
  15   (at your option) any later version.
  16
  17   systemd is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public License
  23   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  24 -->
  25
  26 <refentry id="sd_bus_add_match">
  27
  28   <refentryinfo>
  29     <title>sd_bus_add_match</title>
  30     <productname>systemd</productname>
  31
  32     <authorgroup>
  33       <author>
  34         <firstname>Julian</firstname>
  35         <surname>Orth</surname>
  36         <email>ju.orth@gmail.com</email>
  37       </author>
  38     </authorgroup>
  39   </refentryinfo>
  40
  41   <refmeta>
  42     <refentrytitle>sd_bus_add_match</refentrytitle>
  43     <manvolnum>3</manvolnum>
  44   </refmeta>
  45
  46   <refnamediv>
  47     <refname>sd_bus_add_match</refname>
  48
  49     <refpurpose>Add a match rule for message dispatching</refpurpose>
  50   </refnamediv>
  51
  52   <refsynopsisdiv>
  53     <funcsynopsis>
  54       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  55
  56       <funcprototype>
  57         <funcdef>int <function>sd_bus_add_match</function></funcdef>
  58         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  59         <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
  60         <paramdef>const char *<parameter>match</parameter></paramdef>
  61         <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
  62         <paramdef>void *<parameter>userdata</parameter></paramdef>
  63       </funcprototype>
  64
  65       <funcprototype>
  66         <funcdef>typedef int (*<function>sd_bus_message_handler_t</function>)</funcdef>
  67         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  68         <paramdef>void *<parameter>userdata</parameter></paramdef>
  69         <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef>
  70       </funcprototype>
  71     </funcsynopsis>
  72   </refsynopsisdiv>
  73
  74   <refsect1>
  75     <title>Description</title>
  76
  77     <para>
  78       <function>sd_bus_add_match()</function> installs a match rule for incoming messages received on the specified bus
  79       connection object <parameter>bus</parameter>. The syntax of the match rule expression passed in
  80       <parameter>match</parameter> is described in the <ulink
  81       url="https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus Specification</ulink>. The specified handler
  82       function <parameter>callback</parameter> is called for eaching incoming message matching the specified
  83       expression, the <parameter>userdata</parameter> parameter is passed as-is to the callback function.
  84     </para>
  85
  86     <para>
  87       On success, and if non-<constant>NULL</constant>, the <parameter>slot</parameter> return parameter will be set to
  88       a slot object that may be used as a reference to the installed match, and may be utilized to remove it again at a
  89       later time with
  90       <citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
  91       specified as <constant>NULL</constant> the lifetime of the match is bound to the lifetime of the bus object itself, and the match
  92       cannot be removed independently.
  93     </para>
  94
  95     <para>
  96       The message <parameter>m</parameter> passed to the callback is only borrowed, that is, the callback should not
  97       call <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> on
  98       it. If the callback wants to hold on to the message beyond the lifetime of the callback, it needs to call
  99       <citerefentry><refentrytitle>sd_bus_message_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry> to create
 100       a new reference.
 101     </para>
 102
 103     <para>
 104       If an error occurs during the callback invocation, the callback should return a negative error number. If it
 105       wants other callbacks that match the same rule to be called, it should return 0. Otherwise it should return a
 106       positive integer.
 107     </para>
 108   </refsect1>
 109
 110   <refsect1>
 111     <title>Return Value</title>
 112
 113     <para>
 114       On success, <function>sd_bus_add_match()</function> returns 0 or a positive integer. On failure, it returns a
 115       negative errno-style error code.
 116     </para>
 117   </refsect1>
 118
 119   <refsect1>
 120     <title>See Also</title>
 121
 122     <para>
 123       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 124       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 125     </para>
 126   </refsect1>
 127
 128 </refentry>