man/sd_bus_track_add_name.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
   9 <refentry id="sd_bus_track_add_name" xmlns:xi="http://www.w3.org/2001/XInclude">
  10
  11   <refentryinfo>
  12     <title>sd_bus_track_add_name</title>
  13     <productname>systemd</productname>
  14
  15     <authorgroup>
  16       <author>
  17         <contrib>Developer</contrib>
  18         <firstname>Lennart</firstname>
  19         <surname>Poettering</surname>
  20         <email>lennart@poettering.net</email>
  21       </author>
  22     </authorgroup>
  23   </refentryinfo>
  24
  25   <refmeta>
  26     <refentrytitle>sd_bus_track_add_name</refentrytitle>
  27     <manvolnum>3</manvolnum>
  28   </refmeta>
  29
  30   <refnamediv>
  31     <refname>sd_bus_track_add_name</refname>
  32     <refname>sd_bus_track_add_sender</refname>
  33     <refname>sd_bus_track_remove_name</refname>
  34     <refname>sd_bus_track_remove_sender</refname>
  35     <refname>sd_bus_track_count</refname>
  36     <refname>sd_bus_track_count_sender</refname>
  37     <refname>sd_bus_track_count_name</refname>
  38     <refname>sd_bus_track_contains</refname>
  39     <refname>sd_bus_track_first</refname>
  40     <refname>sd_bus_track_next</refname>
  41
  42     <refpurpose>Add, remove and retrieve bus peers tracked in a bus peer tracking object</refpurpose>
  43   </refnamediv>
  44
  45   <refsynopsisdiv>
  46     <funcsynopsis>
  47       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  48
  49       <funcprototype>
  50         <funcdef>int <function>sd_bus_track_add_name</function></funcdef>
  51         <paramdef>sd_bus_track* <parameter>t</parameter></paramdef>
  52         <paramdef>const char* <parameter>name</parameter></paramdef>
  53       </funcprototype>
  54
  55       <funcprototype>
  56         <funcdef>int <function>sd_bus_track_add_sender</function></funcdef>
  57         <paramdef>sd_bus_track* <parameter>t</parameter></paramdef>
  58         <paramdef>sd_bus_message* <parameter>message</parameter></paramdef>
  59       </funcprototype>
  60
  61       <funcprototype>
  62         <funcdef>int <function>sd_bus_track_remove_name</function></funcdef>
  63         <paramdef>sd_bus_track* <parameter>t</parameter></paramdef>
  64         <paramdef>const char* <parameter>name</parameter></paramdef>
  65       </funcprototype>
  66
  67       <funcprototype>
  68         <funcdef>int <function>sd_bus_track_remove_sender</function></funcdef>
  69         <paramdef>sd_bus_track* <parameter>t</parameter></paramdef>
  70         <paramdef>sd_bus_message* <parameter>message</parameter></paramdef>
  71       </funcprototype>
  72
  73       <funcprototype>
  74         <funcdef>unsigned <function>sd_bus_track_count</function></funcdef>
  75         <paramdef>sd_bus_track* <parameter>t</parameter></paramdef>
  76       </funcprototype>
  77
  78       <funcprototype>
  79         <funcdef>int <function>sd_bus_track_count_name</function></funcdef>
  80         <paramdef>sd_bus_track* <parameter>t</parameter></paramdef>
  81         <paramdef>const char* <parameter>name</parameter></paramdef>
  82       </funcprototype>
  83
  84       <funcprototype>
  85         <funcdef>int <function>sd_bus_track_count_sender</function></funcdef>
  86         <paramdef>sd_bus_track* <parameter>t</parameter></paramdef>
  87         <paramdef>sd_bus_message* <parameter>message</parameter></paramdef>
  88       </funcprototype>
  89
  90       <funcprototype>
  91         <funcdef>int <function>sd_bus_track_contains</function></funcdef>
  92         <paramdef>sd_bus_track* <parameter>t</parameter></paramdef>
  93         <paramdef>const char* <parameter>name</parameter></paramdef>
  94       </funcprototype>
  95
  96       <funcprototype>
  97         <funcdef>const char* <function>sd_bus_track_first</function></funcdef>
  98         <paramdef>sd_bus_track* <parameter>t</parameter></paramdef>
  99       </funcprototype>
 100
 101       <funcprototype>
 102         <funcdef>const char* <function>sd_bus_track_next</function></funcdef>
 103         <paramdef>sd_bus_track* <parameter>t</parameter></paramdef>
 104       </funcprototype>
 105
 106     </funcsynopsis>
 107   </refsynopsisdiv>
 108
 109   <refsect1>
 110     <title>Description</title>
 111
 112     <para><function>sd_bus_track_add_name()</function> adds a peer to track to a bus peer tracking object. The first
 113     argument should refer to a bus peer tracking object created with
 114     <citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, the second
 115     name should refer to a D-Bus peer name to track, either in unique or well-known service format. If the name is not
 116     tracked yet it will be added to the list of names to track. If it already is being tracked and non-recursive mode
 117     is enabled, no operation is executed by this call. If recursive mode is enabled a per-name counter is increased by
 118     one each time this call is invoked, and <function>sd_bus_track_remove_name()</function> has to be called as many
 119     times as <function>sd_bus_track_add_name()</function> was invoked before in order to stop tracking of the name. Use
 120     <citerefentry><refentrytitle>sd_bus_track_set_recursive</refentrytitle><manvolnum>3</manvolnum></citerefentry> to
 121     switch from the default non-recursive mode to recursive mode, or back. Note that the specified name is tracked as
 122     it is, well-known names are not resolved to unique names by this call. Note that multiple bus peer tracking objects
 123     may track the same name.</para>
 124
 125     <para><function>sd_bus_track_remove_name()</function> undoes the effect of
 126     <function>sd_bus_track_add_name()</function> and removes a bus peer name from the list of peers to watch. Depending
 127     on whether non-recursive or recursive mode is enabled for the bus peer tracking object this call will either remove
 128     the name fully from the tracking object, or will simply decrement the per-name counter by one, removing the name
 129     only when the counter reaches zero (see above). Note that a bus peer disconnecting from the bus will implicitly
 130     remove its names fully from the bus peer tracking object, regardless of the current per-name counter.</para>
 131
 132     <para><function>sd_bus_track_add_sender()</function> and <function>sd_bus_track_remove_sender()</function> are
 133     similar to <function>sd_bus_track_add_name()</function> and <function>sd_bus_track_remove_name()</function> but
 134     take a bus message as argument. The sender of this bus message is determined and added to/removed from the bus peer
 135     tracking object. As messages always originate from unique names, and never from well-known names this means that
 136     this call will effectively only add unique names to the bus peer tracking object.</para>
 137
 138     <para><function>sd_bus_track_count()</function> returns the number of names currently being tracked by the
 139     specified bus peer tracking object. Note that this function always returns the actual number of names tracked, and
 140     hence if <function>sd_bus_track_add_name()</function> has been invoked multiple times for the same name it is only
 141     counted as one, regardless if recursive mode is used or not.</para>
 142
 143     <para><function>sd_bus_track_count_name()</function> returns the current per-name counter for the specified
 144     name. If non-recursive mode is used this returns either 1 or 0, depending on whether the specified name has been
 145     added to the tracking object before, or not. If recursive mode has been enabled, values larger than 1 may be
 146     returned too, in case <function>sd_bus_track_add_name()</function> has been called multiple times for the same
 147     name.</para>
 148
 149     <para><function>sd_bus_track_count_sender()</function> is similar to
 150     <function>sd_bus_track_count_name()</function>, but takes a bus message object and returns the per-name counter
 151     matching the sender of the message.</para>
 152
 153     <para><function>sd_bus_track_contains()</function> may be used to determine whether the specified name has been
 154     added at least once to the specified bus peer tracking object.</para>
 155
 156     <para><function>sd_bus_track_first()</function> and <function>sd_bus_track_next()</function> may be used to
 157     enumerate all names currently being tracked by the passed bus peer tracking
 158     object. <function>sd_bus_track_first()</function> returns the first entry in the object, and resets an internally
 159     maintained read index. Each subsequent invocation of <function>sd_bus_track_next()</function> returns the next name
 160     contained in the bus object. If the end is reached <constant>NULL</constant> is returned. If no names have been
 161     added to the object yet <function>sd_bus_track_first()</function> will return <constant>NULL</constant>
 162     immediately. The order in which names are returned is undefined; in particular which name is considered the first
 163     returned is not defined. If recursive mode is enabled and the same name has been added multiple times to the bus
 164     peer tracking object it is only returned once by this enumeration. If new names are added to or existing names
 165     removed from the bus peer tracking object while it is being enumerated the enumeration ends on the next invocation
 166     of <function>sd_bus_track_next()</function> as <constant>NULL</constant> is returned.</para>
 167   </refsect1>
 168
 169   <refsect1>
 170     <title>Return Value</title>
 171
 172     <para>On success, <function>sd_bus_track_add_name()</function> and <function>sd_bus_track_add_sender()</function>
 173     return 0 if the specified name has already been added to the bus peer tracking object before and positive if it
 174     hasn't. On failure, they return a negative errno-style error code.</para>
 175
 176     <para><function>sd_bus_track_remove_name()</function> and <function>sd_bus_track_remove_sender()</function> return
 177     positive if the specified name was previously tracked by the bus peer tracking object and has now been removed. In
 178     non-recursive mode, 0 is returned if the specified name was not being tracked yet. In recursive mode
 179     <constant>-EUNATCH</constant> is returned in this case. On failure, they return a negative errno-style error
 180     code.</para>
 181
 182     <para><function>sd_bus_track_count()</function> returns the number of names currently being tracked, or 0 on
 183     failure.</para>
 184
 185     <para><function>sd_bus_track_count_name()</function> and <function>sd_bus_track_count_sender()</function> return
 186     the current per-name counter for the specified name or the sender of the specified message. Zero is returned for
 187     names that are not being tracked yet, a positive value for names added at least once. Larger values than 1 are only
 188     returned in recursive mode. On failure, a negative errno-style error code is returned.</para>
 189
 190     <para><function>sd_bus_track_contains()</function> returns the passed name if it exists in the bus peer tracking
 191     object. On failure, and if the name has not been added yet <constant>NULL</constant> is returned.</para>
 192
 193     <para><function>sd_bus_track_first()</function> and <function>sd_bus_track_next()</function> return the first/next
 194     name contained in the bus peer tracking object, and <constant>NULL</constant> if the end of the enumeration is
 195     reached and on error.</para>
 196   </refsect1>
 197
 198   <refsect1>
 199     <title>Errors</title>
 200
 201     <para>Returned errors may indicate the following problems:</para>
 202
 203     <variablelist>
 204
 205       <varlistentry>
 206         <term><constant>-EUNATCH</constant></term>
 207
 208         <listitem><para><function>sd_bus_track_remove_name()</function> or
 209         <function>sd_bus_track_remove_sender()</function> have been invoked for a name not previously added to the bus
 210         peer object.</para></listitem>
 211       </varlistentry>
 212
 213       <varlistentry>
 214         <term><constant>-EINVAL</constant></term>
 215
 216         <listitem><para>Specified parameter is invalid.</para></listitem>
 217       </varlistentry>
 218
 219       <varlistentry>
 220         <term><constant>-ENOMEM</constant></term>
 221
 222         <listitem><para>Memory allocation failed.</para></listitem>
 223       </varlistentry>
 224
 225     </variablelist>
 226   </refsect1>
 227
 228   <xi:include href="libelogind-pkgconfig.xml" />
 229
 230   <refsect1>
 231     <title>See Also</title>
 232
 233     <para>
 234       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 235       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 236       <citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 237     </para>
 238   </refsect1>
 239
 240 </refentry>