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