man/sd_bus_set_server.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   5
   6 <refentry id="sd_bus_set_server"
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>sd_bus_set_server</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>sd_bus_set_server</refentrytitle>
  16     <manvolnum>3</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>sd_bus_set_server</refname>
  21     <refname>sd_bus_is_server</refname>
  22     <refname>sd_bus_get_bus_id</refname>
  23     <refname>sd_bus_set_bus_client</refname>
  24     <refname>sd_bus_is_bus_client</refname>
  25     <refname>sd_bus_set_monitor</refname>
  26     <refname>sd_bus_is_monitor</refname>
  27
  28     <refpurpose>Configure connection mode for a bus object</refpurpose>
  29   </refnamediv>
  30
  31   <refsynopsisdiv>
  32     <funcsynopsis>
  33       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  34
  35       <funcprototype>
  36         <funcdef>int <function>sd_bus_set_server</function></funcdef>
  37         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  38         <paramdef>int <parameter>b</parameter></paramdef>
  39         <paramdef>sd_id128_t <parameter>id</parameter></paramdef>
  40       </funcprototype>
  41
  42       <funcprototype>
  43         <funcdef>int <function>sd_bus_is_server</function></funcdef>
  44         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  45       </funcprototype>
  46
  47       <funcprototype>
  48         <funcdef>int <function>sd_bus_get_bus_id</function></funcdef>
  49         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  50         <paramdef>sd_id128_t *<parameter>id</parameter></paramdef>
  51       </funcprototype>
  52
  53       <funcprototype>
  54         <funcdef>int <function>sd_bus_set_bus_client</function></funcdef>
  55         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  56         <paramdef>int <parameter>b</parameter></paramdef>
  57       </funcprototype>
  58
  59       <funcprototype>
  60         <funcdef>int <function>sd_bus_is_bus_client</function></funcdef>
  61         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  62       </funcprototype>
  63
  64       <funcprototype>
  65         <funcdef>int <function>sd_bus_set_monitor</function></funcdef>
  66         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  67         <paramdef>int <parameter>b</parameter></paramdef>
  68       </funcprototype>
  69
  70       <funcprototype>
  71         <funcdef>int <function>sd_bus_is_monitor</function></funcdef>
  72         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  73       </funcprototype>
  74     </funcsynopsis>
  75   </refsynopsisdiv>
  76
  77   <refsect1>
  78     <title>Description</title>
  79
  80     <para><function>sd_bus_set_server()</function> configures the bus object as a server for direct D-Bus
  81     connections. <parameter>b</parameter> enables/disables the server mode. If zero, the server mode is
  82     disabled. Otherwise, the server mode is enabled. Configuring a bus object as a server is required to
  83     allow establishing direct connections between two peers without going via the D-Bus daemon.
  84     <parameter>id</parameter> must contain a 128-bit integer id for the server. If clients add a guid field
  85     to their D-Bus address string, the server id must match this guid or the D-Bus authentication handshake
  86     will fail. If no specific id is defined for the server,
  87     <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  88     can be used to generate a random id instead.</para>
  89
  90     <para><function>sd_bus_is_server()</function> returns whether the server mode is enabled for the given
  91     bus object.</para>
  92
  93     <para><function>sd_bus_get_bus_id()</function> stores the D-Bus server id configured using
  94     <function>sd_bus_set_server()</function> (for server bus objects) or received during D-Bus authentication
  95     (for client bus objects) in <parameter>id</parameter>.</para>
  96
  97     <para><function>sd_bus_set_bus_client()</function> configures the bus object as a D-Bus daemon client.
  98     <parameter>b</parameter> enables/disables the client mode. If zero, the client mode is disabled and the
  99     bus object should connect directly to a D-Bus server. Otherwise, the client mode is enabled and the bus
 100     object should connect to a D-Bus daemon. When connecting to an existing bus using any of the functions in
 101     the <citerefentry><refentrytitle>sd_bus_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 102     family of functions or any of the functions in the
 103     <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry> family
 104     of functions, the bus object is automatically configured as a bus client. However, when connecting to a
 105     D-Bus daemon by calling
 106     <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 107     followed by
 108     <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>, the bus
 109     object should be manually configured as a bus client using <function>sd_bus_set_bus_client()</function>.
 110     By default, a bus object is not configured as a D-Bus daemon client.</para>
 111
 112     <para><function>sd_bus_is_bus_client()</function> returns whether the client mode is enabled/disabled for
 113     the given bus object.</para>
 114
 115     <para><function>sd_bus_set_monitor()</function> configures the bus object as a D-Bus monitor object.
 116     <parameter>b</parameter> enables/disables the monitor mode. If zero, the monitor mode is disabled. If
 117     non-zero, the monitor mode is enabled. When the monitor mode is enabled, no messages may be sent via the
 118     bus object and it may not expose any objects on the bus. To start monitoring messages, call the
 119     <function>org.freedesktop.DBus.Monitoring.BecomeMonitor</function> method of the D-Bus daemon and pass
 120     a list of matches indicating which messages to intercept. See
 121     <ulink url="https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-become-monitor">
 122     The D-Bus specification</ulink> for more information.</para>
 123
 124     <para><function>sd_bus_is_monitor()</function> returns whether the monitor mode is enabled/disabled for
 125     the given bus object.</para>
 126
 127   </refsect1>
 128
 129   <refsect1>
 130     <title>Return Value</title>
 131
 132     <para>On success, <function>sd_bus_set_server()</function>,
 133     <function>sd_bus_get_bus_id()</function>, <function>sd_bus_set_bus_client()</function> and
 134     <function>sd_bus_set_monitor()</function> return a non-negative integer. On failure, they return a
 135     negative errno-style error code.</para>
 136
 137     <para><function>sd_bus_is_server()</function>, <function>sd_bus_is_bus_client()</function> and
 138     <function>sd_bus_is_monitor()</function> return a positive integer when the server or client mode is
 139     enabled, respectively. Otherwise, they return zero.</para>
 140
 141     <refsect2>
 142       <title>Errors</title>
 143
 144       <para>Returned errors may indicate the following problems:</para>
 145
 146       <variablelist>
 147         <varlistentry>
 148           <term><constant>-ECHILD</constant></term>
 149
 150           <listitem><para>The bus connection has been created in a different process.</para></listitem>
 151         </varlistentry>
 152
 153         <varlistentry>
 154           <term><constant>-EPERM</constant></term>
 155
 156           <listitem><para>The bus connection has already been started.</para></listitem>
 157         </varlistentry>
 158
 159          <varlistentry>
 160           <term><constant>-ENOPKG</constant></term>
 161
 162           <listitem><para>The bus cannot be resolved.</para></listitem>
 163         </varlistentry>
 164
 165         <varlistentry>
 166           <term><constant>-EINVAL</constant></term>
 167
 168           <listitem><para>A required parameter was <constant>NULL</constant> or
 169           <parameter>b</parameter> was zero and <parameter>id</parameter> did not equal
 170           <constant>SD_ID128_NULL</constant>.</para></listitem>
 171         </varlistentry>
 172
 173         <varlistentry>
 174           <term><constant>-ENOTCONN</constant></term>
 175
 176           <listitem><para>The bus is not connected.</para></listitem>
 177         </varlistentry>
 178       </variablelist>
 179     </refsect2>
 180   </refsect1>
 181
 182   <xi:include href="libsystemd-pkgconfig.xml" />
 183
 184   <refsect1>
 185     <title>See Also</title>
 186
 187     <para>
 188       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 189       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 190     </para>
 191   </refsect1>
 192
 193 </refentry>