man/rules/meson.build

@@ -121,7 +121,7 @@ manpages = [
    'sd_bus_match_signal',
    'sd_bus_match_signal_async'],
   ''],
- ['sd_bus_add_object',
+ ['sd_bus_add_object_vtable',
   '3',
   ['SD_BUS_METHOD',
    'SD_BUS_METHOD_WITH_NAMES',
@@ -134,9 +134,7 @@ manpages = [
    'SD_BUS_VTABLE_END',
    'SD_BUS_VTABLE_START',
    'SD_BUS_WRITABLE_PROPERTY',
-   'sd_bus_add_fallback',
+   'sd_bus_add_fallback_vtable'],
-   'sd_bus_add_fallback_vtable',
-   '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'], ''],

man/sd-bus.xml

@@ -41,10 +41,7 @@
 
     <para>See
     <literallayout><citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
-<citerefentry><refentrytitle>sd_bus_add_object</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_add_object_vtable</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
-<citerefentry><refentrytitle>sd_bus_add_fallback</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
-<citerefentry><refentrytitle>sd_bus_add_fallback_vtable</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_attach_event</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>,

man/sd_bus_add_object_vtable.xml

@@ -3,22 +3,20 @@
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
 
-<refentry id="sd_bus_add_object"
+<refentry id="sd_bus_add_object_vtable"
           xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
-    <title>sd_bus_add_object</title>
+    <title>sd_bus_add_object_vtable</title>
     <productname>systemd</productname>
   </refentryinfo>
 
   <refmeta>
-    <refentrytitle>sd_bus_add_object</refentrytitle>
+    <refentrytitle>sd_bus_add_object_vtable</refentrytitle>
     <manvolnum>3</manvolnum>
   </refmeta>
 
   <refnamediv>
-    <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>
@@ -78,24 +76,6 @@
         <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef>
       </funcprototype>
 
-      <funcprototype>
-        <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>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
-        <paramdef>void *<parameter>userdata</parameter></paramdef>
-      </funcprototype>
-
-      <funcprototype>
-        <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>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_vtable</function></funcdef>
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
@@ -208,82 +188,40 @@
   <refsect1>
     <title>Description</title>
 
-    <para><function>sd_bus_add_object_vtable()</function> is used to declare attributes for the
+    <para><function>sd_bus_add_object_vtable()</function> is used to declare attributes for the path object
-    object path <parameter>path</parameter> connected to the bus connection
+    path <parameter>path</parameter> connected to the bus connection <parameter>bus</parameter> under the
-    <parameter>bus</parameter> under the interface <parameter>interface</parameter>. The table
+    interface <parameter>interface</parameter>. The table <parameter>vtable</parameter> may contain property
-    <parameter>vtable</parameter> may contain property declarations using
+    declarations using <constant>SD_BUS_PROPERTY()</constant> or
-    <constant>SD_BUS_PROPERTY()</constant> or <constant>SD_BUS_WRITABLE_PROPERTY()</constant>,
+    <constant>SD_BUS_WRITABLE_PROPERTY()</constant>, method declarations using
-    method declarations using <constant>SD_BUS_METHOD()</constant>,
+    <constant>SD_BUS_METHOD()</constant>, <constant>SD_BUS_METHOD_WITH_NAMES()</constant>,
-    <constant>SD_BUS_METHOD_WITH_NAMES()</constant>,
     <constant>SD_BUS_METHOD_WITH_OFFSET()</constant>, or
     <constant>SD_BUS_METHOD_WITH_NAMES_OFFSET()</constant>, and signal declarations using
-    <constant>SD_BUS_SIGNAL_WITH_NAMES()</constant> or <constant>SD_BUS_SIGNAL()</constant>, see
+    <constant>SD_BUS_SIGNAL_WITH_NAMES()</constant> or <constant>SD_BUS_SIGNAL()</constant>, see below. The
-    below. The <replaceable>userdata</replaceable> parameter contains a pointer that will be passed
+    <replaceable>userdata</replaceable> parameter contains a pointer that will be passed to various callback
-    to various callback functions. It may be specified as <constant>NULL</constant> if no value is
+    functions. It may be specified as <constant>NULL</constant> if no value is necessary.</para>
-    necessary. An interface can have any number of vtables attached to it.</para>
 
     <para><function>sd_bus_add_fallback_vtable()</function> is similar to
-    <function>sd_bus_add_object_vtable()</function>, but is used to register "fallback" attributes.
+    <function>sd_bus_add_object_vtable()</function>, but is used to register "fallback" attributes. When
-    When looking for an attribute declaration, bus object paths registered with
+    looking for an attribute declaration, bus object paths registered with
-    <function>sd_bus_add_object_vtable()</function> are checked first. If no match is found, the
+    <function>sd_bus_add_object_vtable()</function> are checked first. If no match is found, the fallback
-    fallback vtables are checked for each prefix of the bus object path, i.e. with the last
+    vtables are checked for each prefix of the bus object path, i.e. with the last slash-separated components
-    slash-separated components successively removed. This allows the vtable to be used for an
+    successively removed. This allows the vtable to be used for an arbitrary number of dynamically created
-    arbitrary number of dynamically created objects.</para>
+    objects.</para>
 
-    <para>Parameter <replaceable>find</replaceable> is a function which is used to locate the target
+    <para>Parameter <replaceable>find</replaceable> is a function which is used to locate the target object
-    object based on the bus object path <replaceable>path</replaceable>. It must return
+    based on the bus object path <replaceable>path</replaceable>. It must return <constant>1</constant> and
-    <constant>1</constant> and set the <parameter>ret_found</parameter> output parameter if the
+    set the <parameter>ret_found</parameter> output parameter if the object is found, return
-    object is found, return <constant>0</constant> if the object was not found, and return a
+    <constant>0</constant> if the object was not found, and return a negative errno-style error code or
-    negative errno-style error code or initialize the error structure
+    initialize the error structure <replaceable>ret_error</replaceable> on error. The pointer passed in
-    <replaceable>ret_error</replaceable> on error. The pointer passed in
+    <parameter>ret_found</parameter> will be used as the <parameter>userdata</parameter> parameter for the
-    <parameter>ret_found</parameter> will be used as the <parameter>userdata</parameter> parameter
+    callback functions (offset by the <parameter>offset</parameter> offsets as specified in the vtable
-    for the callback functions (offset by the <parameter>offset</parameter> offsets as specified in
+    entries).</para>
-    the vtable entries).</para>
 
-    <para><function>sd_bus_add_object()</function> attaches a callback directly to the object path
+    <para>For both functions, a match slot is created internally. If the output parameter
-    <parameter>path</parameter>. An object path can have any number of callbacks attached to it.
+    <replaceable>slot</replaceable> is <constant>NULL</constant>, a "floating" slot object is created, see
-    Each callback is prepended to the list of callbacks which are always called in order.
-    <function>sd_bus_add_fallback()</function> is similar to
-    <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 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
-    returns zero, an error reply is sent back to the caller indicating no matching object for the
-    request was found. Note that you can return a positive integer from a callback without
-    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 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
-    back to the caller as a D-Bus error as if
-    <citerefentry><refentrytitle>sd_bus_reply_method_errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-    was called. Additionally, all callbacks take a <structname>sd_bus_error</structname> output
-    parameter that can be used to provide more detailed error information. If
-    <parameter>ret_error</parameter> is set when the callback finishes, the corresponding D-Bus
-    error is sent back to the caller as if
-    <citerefentry><refentrytitle>sd_bus_reply_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-    was called. Any error stored in <parameter>ret_error</parameter> takes priority over any
-    negative values returned by the same callback when determining which error to send back to
-    the caller. Use
-    <citerefentry><refentrytitle>sd_bus_error_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-    or one of its variants to set <parameter>ret_error</parameter> and return a negative integer
-    from a callback with a single function call. To send an error reply after a callback has already
-    finished, use
-    <citerefentry><refentrytitle>sd_bus_reply_method_errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-    or one of its variants.</para>
-
-    <para>For all functions, a match slot is created internally. If the output parameter
-    <replaceable>slot</replaceable> is <constant>NULL</constant>, a "floating" slot object is
-    created, see
     <citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
-    Otherwise, a pointer to the slot object is returned. In that case, the reference to the slot
+    Otherwise, a pointer to the slot object is returned. In that case, the reference to the slot object
-    object should be dropped when the vtable is not needed anymore, see
+    should be dropped when the vtable is not needed anymore, see
     <citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
     </para>
 
@@ -307,28 +245,23 @@
           <term><constant>SD_BUS_METHOD_WITH_OFFSET()</constant></term>
           <term><constant>SD_BUS_METHOD()</constant></term>
 
-          <listitem><para>Declare a D-Bus method with the name <replaceable>member</replaceable>,
+          <listitem><para>Declare a D-Bus method with the name <replaceable>member</replaceable>, parameter
-          parameter signature <replaceable>signature</replaceable>, result signature
+          signature <replaceable>signature</replaceable>, result signature <replaceable>result</replaceable>.
-          <replaceable>result</replaceable>. Parameters <replaceable>in_names</replaceable> and
+          Parameters <replaceable>in_names</replaceable> and <replaceable>out_names</replaceable> specify the
-          <replaceable>out_names</replaceable> specify the argument names of the input and output
+          argument names of the input and output arguments in the function signature. The handler function
-          arguments in the function signature. The handler function
+          <replaceable>handler</replaceable> must be of type <function>sd_bus_message_handler_t</function>.
-          <replaceable>handler</replaceable> must be of type
+          It will be called to handle the incoming messages that call this method. It receives a pointer that
-          <function>sd_bus_message_handler_t</function>. It will be called to handle the incoming
+          is the <replaceable>userdata</replaceable> parameter passed to the registration function offset by
-          messages that call this method. It receives a pointer that is the
+          <replaceable>offset</replaceable> bytes. This may be used to pass pointers to different fields in
-          <replaceable>userdata</replaceable> parameter passed to the registration function offset
+          the same data structure to different methods in the same
-          by <replaceable>offset</replaceable> bytes. This may be used to pass pointers to different
+          vtable. <replaceable>in_names</replaceable> and <replaceable>out_names</replaceable> should be
-          fields in the same data structure to different methods in the same vtable. To send a reply
+          created using the <constant>SD_BUS_PARAM()</constant> macro, see below. Parameter
-          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>,
-          <constant>SD_BUS_METHOD_WITH_OFFSET()</constant>, and <constant>SD_BUS_METHOD()</constant>
+          <constant>SD_BUS_METHOD_WITH_OFFSET()</constant>, and <constant>SD_BUS_METHOD()</constant> are
-          are variants which specify zero offset (<replaceable>userdata</replaceable> parameter is
+          variants which specify zero offset (<replaceable>userdata</replaceable> parameter is passed with
-          passed with no change), leave the names unset (i.e. no parameter names), or both.</para>
+          no change), leave the names unset (i.e. no parameter names), or both.</para>
           </listitem>
         </varlistentry>
 
@@ -352,31 +285,29 @@
           <term><constant>SD_BUS_WRITABLE_PROPERTY()</constant></term>
           <term><constant>SD_BUS_PROPERTY()</constant></term>
 
-          <listitem><para>Declare a D-Bus property with the name <replaceable>member</replaceable>
+          <listitem><para>Declare a D-Bus property with the name <replaceable>member</replaceable> and value
-          and value signature <replaceable>signature</replaceable>. Parameters
+          signature <replaceable>signature</replaceable>. Parameters <replaceable>get</replaceable> and
-          <replaceable>get</replaceable> and <replaceable>set</replaceable> are the getter and
+          <replaceable>set</replaceable> are the getter and setter methods. They are called with a pointer
-          setter methods. They are called with a pointer that is the
+          that is the <replaceable>userdata</replaceable> parameter passed to the registration function
-          <replaceable>userdata</replaceable> parameter passed to the registration function offset
+          offset by <replaceable>offset</replaceable> bytes. This may be used pass pointers to different
-          by <replaceable>offset</replaceable> bytes. This may be used pass pointers to different
+          fields in the same data structure to different setters and getters in the same vtable. Parameter
-          fields in the same data structure to different setters and getters in the same vtable.
+          <replaceable>flags</replaceable> is a combination of flags, see below.</para>
-          Parameter <replaceable>flags</replaceable> is a combination of flags, see below.</para>
 
-          <para>The setter and getter methods may be omitted (specified as
+          <para>The setter and getter methods may be omitted (specified as <constant>NULL</constant>), if the
-          <constant>NULL</constant>), if the property is one of the basic types or
+          property has one of the basic types or <literal>as</literal> in case of read-only properties. In
-          <literal>as</literal> in case of read-only properties. In those cases, the
+          those cases, the <replaceable>userdata</replaceable> and <replaceable>offset</replaceable>
-          <replaceable>userdata</replaceable> and <replaceable>offset</replaceable> parameters must
+          parameters must together point to valid variable of the corresponding type. A default setter and
-          together point to a valid variable of the corresponding type. A default setter and getter
+          getters will be provided, which simply copy the argument between this variable and the message.
-          will be provided, which simply copy the argument between this variable and the message.
           </para>
 
-          <para><constant>SD_BUS_PROPERTY()</constant> is used to define a read-only property.
+          <para><constant>SD_BUS_PROPERTY()</constant> is used to define a read-only property.</para>
-          </para></listitem>
+          </listitem>
         </varlistentry>
 
         <varlistentry>
           <term><constant>SD_BUS_PARAM()</constant></term>
-          <listitem><para>Parameter names should be wrapped in this macro, see the example below.
+          <listitem><para>Parameter names should be wrapped in this macro, see the example below.</para>
-          </para></listitem>
+          </listitem>
         </varlistentry>
       </variablelist>
     </refsect2>
@@ -401,9 +332,10 @@
         <varlistentry>
           <term><constant>SD_BUS_VTABLE_HIDDEN</constant></term>
 
-          <listitem><para>Make this vtable entry hidden. It will not be shown in introspection data.
+          <listitem><para>Make this vtable entry hidden. It will not be shown in introspection data.  If
-          If specified for <constant>SD_BUS_VTABLE_START()</constant>, all entries in the array are
+          specified for <constant>SD_BUS_VTABLE_START()</constant>, all entries in the array are hidden.
-          hidden.</para></listitem>
+          </para>
+          </listitem>
         </varlistentry>
 
         <varlistentry>
@@ -411,7 +343,8 @@
 
           <listitem><para>Mark this vtable entry as unprivileged. If not specified, the
           <constant>org.freedesktop.systemd1.Privileged</constant> annotation with value
-          <literal>true</literal> will be shown in introspection data.</para></listitem>
+          <literal>true</literal> will be shown in introspection data.</para>
+          </listitem>
         </varlistentry>
 
         <varlistentry>
@@ -428,28 +361,27 @@
           <term><constant>SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION</constant></term>
 
           <listitem><para>Those three flags correspond to different values of the
-          <constant>org.freedesktop.DBus.Property.EmitsChangedSignal</constant> annotation, which
+          <constant>org.freedesktop.DBus.Property.EmitsChangedSignal</constant> annotation, which specifies
-          specifies whether the
+          whether the <constant>org.freedesktop.DBus.Properties.PropertiesChanged</constant> signal is
-          <constant>org.freedesktop.DBus.Properties.PropertiesChanged</constant> signal is emitted
+          emitted whenever the property changes. <constant>SD_BUS_VTABLE_PROPERTY_CONST</constant> corresponds to
-          whenever the property changes. <constant>SD_BUS_VTABLE_PROPERTY_CONST</constant>
+          <constant>const</constant> and means that the property never changes during the lifetime of the
-          corresponds to <constant>const</constant> and means that the property never changes during
+          object it belongs to, so no signal needs to be emitted.
-          the lifetime of the object it belongs to, so no signal needs to be emitted.
+          <constant>SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE</constant> corresponds to <constant>true</constant> and means
-          <constant>SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE</constant> corresponds to
+          that the signal is emitted. <constant>SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION</constant> corresponds to
-          <constant>true</constant> and means that the signal is emitted.
+          <constant>invalidates</constant> and means that the signal is emitted, but the value is not included
-          <constant>SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION</constant> corresponds to
+          in the signal.</para>
-          <constant>invalidates</constant> and means that the signal is emitted, but the value is
+          </listitem>
-          not included in the signal.</para></listitem>
         </varlistentry>
 
         <varlistentry>
           <term><constant>SD_BUS_VTABLE_PROPERTY_EXPLICIT</constant></term>
 
-          <listitem><para>Mark this vtable property entry as requiring explicit request to for the
+          <listitem><para>Mark this vtable property entry as requiring explicit request to for the value to
-          value to be shown (generally because the value is large or slow to calculate). This entry
+          be shown (generally because the value is large or slow to calculate). This entry cannot be combined
-          cannot be combined with <constant>SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE</constant>, and will
+          with <constant>SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE</constant>, and will not be shown in property listings by
-          not be shown in property listings by default (e.g. <command>busctl introspect</command>).
+          default (e.g. <command>busctl introspect</command>).  This corresponds to the
-          This corresponds to the <constant>org.freedesktop.systemd1.Explicit</constant> annotation
+          <constant>org.freedesktop.systemd1.Explicit</constant> annotation in introspection data.</para>
-          in introspection data.</para></listitem>
+          </listitem>
         </varlistentry>
       </variablelist>
     </refsect2>
@@ -463,9 +395,9 @@
 
       <programlisting><xi:include href="vtable-example.c" parse="text" /></programlisting>
 
-      <para>This creates a simple client on the bus (the user bus, when run as normal user). We may
+      <para>This creates a simple client on the bus (the user bus, when run as normal user).
-      use the D-Bus <constant>org.freedesktop.DBus.Introspectable.Introspect</constant> call to
+      We may use the D-Bus <constant>org.freedesktop.DBus.Introspectable.Introspect</constant>
-      acquire the XML description of the interface:</para>
+      call to acquire the XML description of the interface:</para>
 
       <programlisting><xi:include href="vtable-example.xml" parse="text" /></programlisting>
     </example>
@@ -475,8 +407,8 @@
     <title>Return Value</title>
 
     <para>On success, <function>sd_bus_add_object_vtable</function> and
-    <function>sd_bus_add_fallback_vtable</function> calls return 0 or a positive integer. On
+    <function>sd_bus_add_fallback_vtable</function> calls return 0 or a positive integer. On failure, they
-    failure, they return a negative errno-style error code.</para>
+    return a negative errno-style error code.</para>
 
     <refsect2>
       <title>Errors</title>
@@ -487,9 +419,8 @@
         <varlistentry>
           <term><constant>-EINVAL</constant></term>
 
-          <listitem><para>One of the required parameters is <constant>NULL</constant> or invalid. A
+          <listitem><para>One of the required parameters is <constant>NULL</constant> or invalid. A reserved
-          reserved D-Bus interface was passed as the <replaceable>interface</replaceable> parameter.
+          D-Bus interface was passed as the <replaceable>interface</replaceable> parameter.</para></listitem>
-          </para></listitem>
         </varlistentry>
 
         <varlistentry>
@@ -514,8 +445,8 @@
           <term><constant>-EPROTOTYPE</constant></term>
 
           <listitem><para><function>sd_bus_add_object_vtable</function> and
-          <function>sd_bus_add_fallback_vtable</function> have been both called for the same bus
+          <function>sd_bus_add_fallback_vtable</function> have been both called
-          object path, which is not allowed.</para></listitem>
+          for the same bus object path, which is not allowed.</para></listitem>
         </varlistentry>
 
         <varlistentry>