sd-bus: Add note about sd_bus_reply_method_return to SD_BUS_METHOD docs

diff --git a/man/rules/meson.build b/man/rules/meson.build
index d451ac7bbecf65bab075a290fbfcca246e37e712..9cdfe5d2919820aa50315254c8c97589c2428385 100644 (file)
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -121,7 +121,7 @@ manpages = [
    'sd_bus_match_signal',
    'sd_bus_match_signal_async'],
   ''],
- ['sd_bus_add_object_vtable',
+ ['sd_bus_add_object',
   '3',
   ['SD_BUS_METHOD',
    'SD_BUS_METHOD_WITH_NAMES',
@@ -136,7 +136,7 @@ manpages = [
    'SD_BUS_WRITABLE_PROPERTY',
    'sd_bus_add_fallback',
    'sd_bus_add_fallback_vtable',
-   'sd_bus_add_object'],
+   'sd_bus_add_object_vtable'],
   ''],
  ['sd_bus_attach_event', '3', ['sd_bus_detach_event', 'sd_bus_get_event'], ''],
  ['sd_bus_call', '3', ['sd_bus_call_async'], ''],

diff --git a/man/sd_bus_add_object_vtable.xml b/man/sd_bus_add_object.xml
similarity index 97%
rename from man/sd_bus_add_object_vtable.xml
rename to man/sd_bus_add_object.xml
index 218a54647b5dbb4e88d4bce72f961379d12f6f1d..2abe2342f0a6d97b858c7fefe1f42f393759e579 100644 (file)
--- a/man/sd_bus_add_object_vtable.xml
+++ b/man/sd_bus_add_object.xml
@@ -3,24 +3,24 @@
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
 
-<refentry id="sd_bus_add_object_vtable"
+<refentry id="sd_bus_add_object"
           xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
-    <title>sd_bus_add_object_vtable</title>
+    <title>sd_bus_add_object</title>
     <productname>systemd</productname>
   </refentryinfo>
 
   <refmeta>
-    <refentrytitle>sd_bus_add_object_vtable</refentrytitle>
+    <refentrytitle>sd_bus_add_object</refentrytitle>
     <manvolnum>3</manvolnum>
   </refmeta>
 
   <refnamediv>
-    <refname>sd_bus_add_object_vtable</refname>
-    <refname>sd_bus_add_fallback_vtable</refname>
     <refname>sd_bus_add_object</refname>
     <refname>sd_bus_add_fallback</refname>
+    <refname>sd_bus_add_object_vtable</refname>
+    <refname>sd_bus_add_fallback_vtable</refname>
     <refname>SD_BUS_VTABLE_START</refname>
     <refname>SD_BUS_VTABLE_END</refname>
     <refname>SD_BUS_METHOD_WITH_NAMES_OFFSET</refname>
@@ -79,41 +79,41 @@
       </funcprototype>
 
       <funcprototype>
-        <funcdef>int <function>sd_bus_add_object_vtable</function></funcdef>
+        <funcdef>int <function>sd_bus_add_object</function></funcdef>
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
         <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
         <paramdef>const char *<parameter>path</parameter></paramdef>
-        <paramdef>const char *<parameter>interface</parameter></paramdef>
-        <paramdef>const sd_bus_vtable *<parameter>vtable</parameter></paramdef>
+        <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
         <paramdef>void *<parameter>userdata</parameter></paramdef>
       </funcprototype>
 
       <funcprototype>
-        <funcdef>int <function>sd_bus_add_fallback_vtable</function></funcdef>
+        <funcdef>int <function>sd_bus_add_fallback</function></funcdef>
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
         <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
-        <paramdef>const char *<parameter>prefix</parameter></paramdef>
-        <paramdef>const char *<parameter>interface</parameter></paramdef>
-        <paramdef>const sd_bus_vtable *<parameter>vtable</parameter></paramdef>
-        <paramdef>sd_bus_object_find_t <parameter>find</parameter></paramdef>
+        <paramdef>const char *<parameter>path</parameter></paramdef>
+        <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
         <paramdef>void *<parameter>userdata</parameter></paramdef>
       </funcprototype>
 
       <funcprototype>
-        <funcdef>int <function>sd_bus_add_object</function></funcdef>
+        <funcdef>int <function>sd_bus_add_object_vtable</function></funcdef>
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
         <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
         <paramdef>const char *<parameter>path</parameter></paramdef>
-        <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
+        <paramdef>const char *<parameter>interface</parameter></paramdef>
+        <paramdef>const sd_bus_vtable *<parameter>vtable</parameter></paramdef>
         <paramdef>void *<parameter>userdata</parameter></paramdef>
       </funcprototype>
 
       <funcprototype>
-        <funcdef>int <function>sd_bus_add_fallback</function></funcdef>
+        <funcdef>int <function>sd_bus_add_fallback_vtable</function></funcdef>
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
         <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
-        <paramdef>const char *<parameter>path</parameter></paramdef>
-        <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
+        <paramdef>const char *<parameter>prefix</parameter></paramdef>
+        <paramdef>const char *<parameter>interface</parameter></paramdef>
+        <paramdef>const sd_bus_vtable *<parameter>vtable</parameter></paramdef>
+        <paramdef>sd_bus_object_find_t <parameter>find</parameter></paramdef>
         <paramdef>void *<parameter>userdata</parameter></paramdef>
       </funcprototype>
 
@@ -247,8 +247,8 @@
     <function>sd_bus_add_object()</function> but applies to fallback paths instead.</para>
 
     <para>When a request is received, any associated callbacks are called sequentially until a
-    callback returns a non-zero integer. Return zero from a callback to defer handling of the
-    request to the next callback. Callbacks are called in the following order: first, callbacks
+    callback returns a non-zero integer. Return zero from a callback to give other callbacks the
+    chance to process the request. Callbacks are called in the following order: first, callbacks
     attached directly to the request object path are called, followed by any D-Bus method callbacks
     attached to the request object path, interface and member. Finally, the property callbacks
     attached to the request object path, interface and member are called. If the final callback
@@ -257,7 +257,7 @@
     immediately sending a reply. This informs sd-bus this callback will take responsibility for
     replying to the request without forcing the callback to produce a reply immediately. This allows
     a callback to perform any number of asynchronous operations required to construct a reply. Note
-    that if producing a reply takes too long, the method call will timeout at the caller.</para>
+    that if producing a reply takes too long, the method call will time out at the caller.</para>
 
     <para>If a callback was invoked to handle a request that expects a reply and the callback
     returns a negative value, the value is interpreted as a negative errno-style error code and sent
@@ -317,9 +317,12 @@
           messages that call this method. It receives a pointer that is the
           <replaceable>userdata</replaceable> parameter passed to the registration function offset
           by <replaceable>offset</replaceable> bytes. This may be used to pass pointers to different
-          fields in the same data structure to different methods in the same vtable.
-          <replaceable>in_names</replaceable> and <replaceable>out_names</replaceable> should be
-          created using the <constant>SD_BUS_PARAM()</constant> macro, see below. Parameter
+          fields in the same data structure to different methods in the same vtable. To send a reply
+          from <parameter>handler</parameter>, call
+          <citerefentry><refentrytitle>sd_bus_reply_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+          with the message the callback was invoked with. <replaceable>in_names</replaceable> and
+          <replaceable>out_names</replaceable> should be created using the
+          <constant>SD_BUS_PARAM()</constant> macro, see below. Parameter
           <replaceable>flags</replaceable> is a combination of flags, see below.</para>
 
           <para><constant>SD_BUS_METHOD_WITH_NAMES()</constant>,