sd-bus: Add sd_bus_method_call/sd_bus_method_call_async docs + cleanups.

5 files changed, 129 insertions, 8 deletions

diff --git a/man/rules/meson.build b/man/rules/meson.build
index 296dd7da3a..d54e3bf78b 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -137,6 +137,7 @@ manpages = [
    'sd_bus_add_fallback_vtable'],
   ''],
  ['sd_bus_attach_event', '3', ['sd_bus_detach_event', 'sd_bus_get_event'], ''],
+ ['sd_bus_call_method', '3', ['sd_bus_call_method_async'], ''],
  ['sd_bus_close', '3', ['sd_bus_flush'], ''],
  ['sd_bus_creds_get_pid',
   '3',
@@ -217,7 +218,10 @@ manpages = [
   '3',
   ['SD_BUS_ERROR_END', 'SD_BUS_ERROR_MAP', 'sd_bus_error_map'],
   ''],
- ['sd_bus_get_fd', '3', ['sd_bus_get_events', 'sd_bus_get_timeout'], ''],
+ ['sd_bus_get_fd',
+  '3',
+  ['sd_bus_get_events', 'sd_bus_get_timeout', 'sd_bus_set_fd'],
+  ''],
  ['sd_bus_get_n_queued_read', '3', ['sd_bus_get_n_queued_write'], ''],
  ['sd_bus_is_open', '3', ['sd_bus_is_ready'], ''],
  ['sd_bus_message_append', '3', ['sd_bus_message_appendv'], ''],
diff --git a/man/sd-bus.xml b/man/sd-bus.xml
index 76865e1f8e..35db2bb69d 100644
--- a/man/sd-bus.xml
+++ b/man/sd-bus.xml
@@ -43,6 +43,8 @@
     <literallayout><citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_add_object_vtable</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_call_method</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_call_method_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
diff --git a/man/sd_bus_call_method.xml b/man/sd_bus_call_method.xml
new file mode 100644
index 0000000000..1565bab82d
--- /dev/null
+++ b/man/sd_bus_call_method.xml
@@ -0,0 +1,110 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
+
+<refentry id="sd_bus_call_method"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_bus_call_method</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_bus_call_method</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_bus_call_method</refname>
+    <refname>sd_bus_call_method_async</refname>
+
+    <refpurpose>Invoke a D-Bus method call</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_call_method</function></funcdef>
+        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
+        <paramdef>const char *<parameter>destination</parameter></paramdef>
+        <paramdef>const char *<parameter>path</parameter></paramdef>
+        <paramdef>const char *<parameter>interface</parameter></paramdef>
+        <paramdef>const char *<parameter>member</parameter></paramdef>
+        <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef>
+        <paramdef>sd_bus_message **<parameter>reply</parameter></paramdef>
+        <paramdef>const char *<parameter>types</parameter></paramdef>
+        <paramdef>...</paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_call_method_async</function></funcdef>
+        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
+        <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
+        <paramdef>const char *<parameter>destination</parameter></paramdef>
+        <paramdef>const char *<parameter>path</parameter></paramdef>
+        <paramdef>const char *<parameter>interface</parameter></paramdef>
+        <paramdef>const char *<parameter>member</parameter></paramdef>
+        <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
+        <paramdef>void *<parameter>userdata</parameter></paramdef>
+        <paramdef>const char *<parameter>types</parameter></paramdef>
+        <paramdef>...</paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_bus_call_method()</function> is a convenience function for calling a D-Bus
+    method. It combines the
+    <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
+    <citerefentry><refentrytitle>sd_bus_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    functions into a single function call.</para>
+
+    <para><function>sd_bus_call_method_async()</function> is a convenience function for calling a
+    D-Bus method asynchronously. It combines the
+    <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
+    <citerefentry><refentrytitle>sd_bus_call_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    functions into a single function call.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>On success, these functions returns a non-negative integer. On failure, they return a
+    negative errno-style error code.</para>
+
+    <refsect2 id='errors'>
+      <title>Errors</title>
+
+      <para>See the man pages of
+      <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_call</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
+      <citerefentry><refentrytitle>sd_bus_call_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+      for a list of possible errors.</para>
+    </refsect2>
+  </refsect1>
+
+  <xi:include href="libsystemd-pkgconfig.xml" />
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_call_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/man/sd_bus_message_new_method_call.xml b/man/sd_bus_message_new_method_call.xml
index 0d181ed82e..1201262690 100644
--- a/man/sd_bus_message_new_method_call.xml
+++ b/man/sd_bus_message_new_method_call.xml
@@ -28,7 +28,7 @@
       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
 
       <funcprototype>
-        <funcdef>int sd_bus_message_new_method_call</funcdef>
+        <funcdef>int <function>sd_bus_message_new_method_call</function></funcdef>
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
         <paramdef>sd_bus_message **<parameter>m</parameter></paramdef>
         <paramdef>const char *<parameter>destination</parameter></paramdef>
@@ -38,7 +38,7 @@
       </funcprototype>
 
       <funcprototype>
-        <funcdef>int sd_bus_message_new_method_return</funcdef>
+        <funcdef>int <function>sd_bus_message_new_method_return</function></funcdef>
         <paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
         <paramdef>sd_bus_message **<parameter>m</parameter></paramdef>
       </funcprototype>
@@ -70,7 +70,11 @@
     has only a single member with the given name and there is no ambiguity if the interface name is
     omitted.</para>
 
-    <para>The <function>sd_bus_message_new_method_call()</function> function creates a new bus
+    <para>Note that this is a low level interface. See
+    <citerefentry><refentrytitle>sd_bus_call_method</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    for a more convenient way of calling D-Bus methods.</para>
+
+    <para>The <function>sd_bus_message_new_method_return()</function> function creates a new bus
     message object that is a reply to the method call <parameter>call</parameter> and returns it in
     the <parameter>m</parameter> output parameter. The <parameter>call</parameter> parameter must be
     a method call message. The sender of <parameter>call</parameter> is used as the destination.
@@ -80,8 +84,8 @@
   <refsect1>
     <title>Return Value</title>
 
-    <para>This function returns 0 if the message object was successfully created, and a negative
-    errno-style error code otherwise.</para>
+    <para>On success, these functions returns a non-negative integer. On failure, they return a
+    negative errno-style error code.</para>
 
     <refsect2 id='errors'>
       <title>Errors</title>
@@ -160,6 +164,7 @@
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_bus_path_encode</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+      <citerefentry><refentrytitle>sd_bus_call_method</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     </para>
   </refsect1>
 
diff --git a/man/sd_bus_message_read.xml b/man/sd_bus_message_read.xml
index 2afa441742..ee7bdc4bfd 100644
--- a/man/sd_bus_message_read.xml
+++ b/man/sd_bus_message_read.xml
@@ -30,14 +30,14 @@
       <funcprototype>
         <funcdef>int <function>sd_bus_message_read</function></funcdef>
         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
-        <paramdef>char char *<parameter>types</parameter></paramdef>
+        <paramdef>const char *<parameter>types</parameter></paramdef>
         <paramdef>...</paramdef>
       </funcprototype>
 
       <funcprototype>
         <funcdef>int <function>sd_bus_message_readv</function></funcdef>
         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
-        <paramdef>char char *<parameter>types</parameter></paramdef>
+        <paramdef>const char *<parameter>types</parameter></paramdef>
         <paramdef>va_list <parameter>ap</parameter></paramdef>
       </funcprototype>
     </funcsynopsis>