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