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-or-later -->
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>
194