]>
Commit | Line | Data |
---|---|---|
c40bd284 DDM |
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> | |
842a362c | 21 | <refname>sd_bus_is_server</refname> |
c40bd284 | 22 | <refname>sd_bus_get_bus_id</refname> |
842a362c DDM |
23 | <refname>sd_bus_set_bus_client</refname> |
24 | <refname>sd_bus_is_bus_client</refname> | |
0eb5b641 DDM |
25 | <refname>sd_bus_set_monitor</refname> |
26 | <refname>sd_bus_is_monitor</refname> | |
c40bd284 | 27 | |
0eb5b641 | 28 | <refpurpose>Configure connection mode for a bus object</refpurpose> |
c40bd284 DDM |
29 | </refnamediv> |
30 | ||
31 | <refsynopsisdiv> | |
32 | <funcsynopsis> | |
33 | <funcsynopsisinfo>#include <systemd/sd-bus.h></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 | ||
842a362c DDM |
42 | <funcprototype> |
43 | <funcdef>int <function>sd_bus_is_server</function></funcdef> | |
44 | <paramdef>sd_bus *<parameter>bus</parameter></paramdef> | |
45 | </funcprototype> | |
46 | ||
c40bd284 DDM |
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> | |
842a362c DDM |
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> | |
0eb5b641 DDM |
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> | |
c40bd284 DDM |
74 | </funcsynopsis> |
75 | </refsynopsisdiv> | |
76 | ||
77 | <refsect1> | |
78 | <title>Description</title> | |
79 | ||
7fffaafa DDM |
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, | |
c40bd284 DDM |
87 | <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
88 | can be used to generate a random id instead.</para> | |
89 | ||
7fffaafa DDM |
90 | <para><function>sd_bus_is_server()</function> returns whether the server mode is enabled for the given |
91 | bus object.</para> | |
842a362c | 92 | |
c40bd284 | 93 | <para><function>sd_bus_get_bus_id()</function> stores the D-Bus server id configured using |
7fffaafa DDM |
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> | |
842a362c | 102 | family of functions or any of the functions in the |
7fffaafa DDM |
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 | |
842a362c DDM |
106 | <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
107 | followed by | |
7fffaafa DDM |
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> | |
842a362c | 111 | |
7fffaafa DDM |
112 | <para><function>sd_bus_is_bus_client()</function> returns whether the client mode is enabled/disabled for |
113 | the given bus object.</para> | |
0eb5b641 DDM |
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 | ||
c40bd284 DDM |
127 | </refsect1> |
128 | ||
129 | <refsect1> | |
130 | <title>Return Value</title> | |
131 | ||
842a362c | 132 | <para>On success, <function>sd_bus_set_server()</function>, |
0eb5b641 DDM |
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> | |
842a362c | 136 | |
0eb5b641 DDM |
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> | |
c40bd284 DDM |
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> |