From: Daan De Meyer <daan.j.demeyer@gmail.com>
Date: Mon, 20 Apr 2020 16:38:38 +0000 (+0200)
Subject: sd-bus: Add sd_bus_is_server + sd_bus_set/is_bus_client docs
X-Git-Tag: v246-rc1~554
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=842a362c3a439f88186fa3a2d5903390f9fe5181;p=thirdparty%2Fsystemd.git

sd-bus: Add sd_bus_is_server + sd_bus_set/is_bus_client docs
---

diff --git a/man/rules/meson.build b/man/rules/meson.build
index 772ac1dc248..3b52d33e371 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -398,7 +398,13 @@ manpages = [
    'sd_bus_set_propertyv'],
   ''],
  ['sd_bus_set_sender', '3', ['sd_bus_get_sender'], ''],
- ['sd_bus_set_server', '3', ['sd_bus_get_bus_id'], ''],
+ ['sd_bus_set_server',
+  '3',
+  ['sd_bus_get_bus_id',
+   'sd_bus_is_bus_client',
+   'sd_bus_is_server',
+   'sd_bus_set_bus_client'],
+  ''],
  ['sd_bus_set_watch_bind', '3', ['sd_bus_get_watch_bind'], ''],
  ['sd_bus_slot_get_bus',
   '3',
diff --git a/man/sd-bus.xml b/man/sd-bus.xml
index f47e78cd682..3237eb82cc6 100644
--- a/man/sd-bus.xml
+++ b/man/sd-bus.xml
@@ -80,6 +80,8 @@
 <citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_get_method_call_timeout</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_get_n_queued_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_is_bus_client</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_is_server</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_message_append_array</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
@@ -125,6 +127,7 @@
 <citerefentry><refentrytitle>sd_bus_set_property</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_set_propertyv</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_set_sender</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_set_bus_client</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_set_server</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_set_watch_bind</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 <citerefentry><refentrytitle>sd_bus_set_close_on_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
diff --git a/man/sd_bus_set_server.xml b/man/sd_bus_set_server.xml
index 2e065596a2d..228dc806e4e 100644
--- a/man/sd_bus_set_server.xml
+++ b/man/sd_bus_set_server.xml
@@ -18,9 +18,12 @@
 
   <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>
 
-    <refpurpose>Configure server mode for a bus object</refpurpose>
+    <refpurpose>Configure direct connection mode for a bus object</refpurpose>
   </refnamediv>
 
   <refsynopsisdiv>
@@ -34,11 +37,27 @@
         <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>
     </funcsynopsis>
   </refsynopsisdiv>
 
@@ -55,16 +74,44 @@
     <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>
   </refsect1>
 
   <refsect1>
     <title>Return Value</title>
 
-    <para>On success, these functions return a non-negative integer. On failure, they return a
-    negative errno-style error code.</para>
+    <para>On success, <function>sd_bus_set_server()</function>,
+    <function>sd_bus_get_bus_id()</function> and <function>sd_bus_set_bus_client()</function> return
+    a non-negative integer. On failure, they return a negative errno-style error code.</para>
+
+    <para><function>sd_bus_is_server()</function> and <function>sd_bus_is_bus_client()</function>
+    return 1 when the server or client mode is enabled, respectively. Otherwise, they return 0.
+    </para>
 
     <refsect2>
       <title>Errors</title>