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