sd-bus: Add sd_bus_set_server, sd_bus_get_bus_id docs

sd-bus: Add sd_bus_add_object_manager docs
sd-bus: Add sd_bus_add_filter docs
2020-04-19 21:41:03 +02:00 · 2020-04-19 19:02:11 +02:00 · 2020-04-19 19:00:22 +02:00
5 changed files with 260 additions and 1 deletions
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@ -144,8 +144,10 @@ manpages = [
   'SD_BUS_WRITABLE_PROPERTY',
   'sd_bus_add_fallback',
   'sd_bus_add_fallback_vtable',
+   'sd_bus_add_filter',
   'sd_bus_add_object_vtable'],
  ''],
+ ['sd_bus_add_object_manager', '3', [], ''],
 ['sd_bus_attach_event', '3', ['sd_bus_detach_event', 'sd_bus_get_event'], ''],
 ['sd_bus_call', '3', ['sd_bus_call_async'], ''],
 ['sd_bus_call_method',
@ -377,6 +379,7 @@ 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_watch_bind', '3', ['sd_bus_get_watch_bind'], ''],
 ['sd_bus_slot_get_bus',
  '3',
--- a/man/sd-bus.xml
+++ b/man/sd-bus.xml
@ -42,9 +42,11 @@
    <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_manager</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_add_filter</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>,
@ -59,6 +61,7 @@
 <citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_get_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_get_bus_id</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <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>,
@ -107,6 +110,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_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>,
 <citerefentry><refentrytitle>sd_bus_slot_get_current_handler</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
--- a/man/sd_bus_add_object.xml
+++ b/man/sd_bus_add_object.xml
@ -21,6 +21,7 @@
    <refname>sd_bus_add_fallback</refname>
    <refname>sd_bus_add_object_vtable</refname>
    <refname>sd_bus_add_fallback_vtable</refname>
+    <refname>sd_bus_add_filter</refname>
    <refname>SD_BUS_VTABLE_START</refname>
    <refname>SD_BUS_VTABLE_END</refname>
    <refname>SD_BUS_METHOD_WITH_NAMES_OFFSET</refname>
@ -117,6 +118,14 @@
        <paramdef>void *<parameter>userdata</parameter></paramdef>
      </funcprototype>

+      <funcprototype>
+        <funcdef>int <function>sd_bus_add_filter</function></funcdef>
+        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
+        <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
+        <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
+        <paramdef>void *<parameter>userdata</parameter></paramdef>
+      </funcprototype>
+
      <para>
        <constant>SD_BUS_VTABLE_START(<replaceable>flags</replaceable>)</constant>
      </para>
@ -246,9 +255,14 @@
    <function>sd_bus_add_fallback()</function> is similar to
    <function>sd_bus_add_object()</function> but applies to fallback paths instead.</para>

+    <para><function>sd_bus_add_filter()</function> installs a callback that is invoked for each
+    incoming D-Bus message. Filters can be used to handle logic common to all messages received by
+    a service (e.g. authentication or authorization).</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
+    chance to process the request. Callbacks are called in the following order: first, global
+    callbacks installed with <function>sd_bus_add_filter()</function> are called. Second, 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
--- a/man/sd_bus_add_object_manager.xml
+++ b/man/sd_bus_add_object_manager.xml
@ -0,0 +1,117 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!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_add_object_manager"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_bus_add_object_manager</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_bus_add_object_manager</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_bus_add_object_manager</refname>
+
+    <refpurpose>Add a D-Bus object manager for a D-Bus object sub-tree</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_add_object_manager</function></funcdef>
+        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
+        <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
+        <paramdef>const char *<parameter>path</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_bus_add_object_manager()</function> installs a handler for the given path
+    that implements the <function>GetManagedObjects()</function> method of the
+    <constant>org.freedesktop.DBus.ObjectManager</constant> interface. See
+    <ulink url="https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">
+    org.freedesktop.DBus.ObjectManager</ulink> for more information.</para>
+
+    <para>To implement the <function>InterfacesAdded</function> and
+    <function>InterfacesRemoved</function> signals of the
+    <constant>org.freedesktop.DBus.ObjectManager</constant> interface, call
+    <citerefentry><refentrytitle>sd_bus_emit_interfaces_added</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
+    <citerefentry><refentrytitle>sd_bus_emit_interfaces_removed</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    whenever interfaces are added or removed from the sub-tree, respectively.</para>
+
+    <para>When <function>sd_bus_add_object_manager</function> succeeds, a 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
+    object should be dropped when the object manager is not needed anymore, see
+    <citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>On success, <function>sd_bus_add_object_manager()</function> returns a non-negative
+    integer. On failure, it returns a negative errno-style error code.</para>
+
+    <refsect2>
+      <title>Errors</title>
+
+      <para>Returned errors may indicate the following problems:</para>
+
+      <variablelist>
+        <varlistentry>
+          <term><constant>-EINVAL</constant></term>
+
+          <listitem><para>One of the required parameters is <constant>NULL</constant> or
+          <parameter>path</parameter> is not a valid object path.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-ENOPKG</constant></term>
+
+          <listitem><para>The bus cannot be resolved.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-ECHILD</constant></term>
+
+          <listitem><para>The bus was created in a different process.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-ENOMEM</constant></term>
+
+          <listitem><para>Memory allocation failed.</para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
+  </refsect1>
+
+  <xi:include href="libsystemd-pkgconfig.xml" />
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>busctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_add_object_vtable</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+</refentry>
--- a/man/sd_bus_set_server.xml
+++ b/man/sd_bus_set_server.xml
@ -0,0 +1,121 @@
+<?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_set_server"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_bus_set_server</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_bus_set_server</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_bus_set_server</refname>
+    <refname>sd_bus_get_bus_id</refname>
+
+    <refpurpose>Configure server mode for a bus object</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_set_server</function></funcdef>
+        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
+        <paramdef>int <parameter>b</parameter></paramdef>
+        <paramdef>sd_id128_t <parameter>id</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>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_bus_set_server()</function> configures the bus object as a server for direct
+    D-Bus connections. <parameter>b</parameter> enables/disables the server mode. If zero, the
+    server mode is disabled. Otherwise, the server mode is enabled. Configuring a bus object as a
+    server is required to allow establishing direct connections between two peers without going via
+    the D-Bus daemon. <parameter>id</parameter> must contain a 128-bit integer id for the server. If
+    clients add a guid field to their D-Bus address string, the server id must match this guid or
+    the D-Bus authentication handshake will fail. If no specific id is defined for the server,
+    <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    can be used to generate a random id instead.</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>
+  </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>
+
+    <refsect2>
+      <title>Errors</title>
+
+      <para>Returned errors may indicate the following problems:</para>
+
+      <variablelist>
+        <varlistentry>
+          <term><constant>-ECHILD</constant></term>
+
+          <listitem><para>The bus connection has been created in a different process.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-EPERM</constant></term>
+
+          <listitem><para>The bus connection has already been started.</para></listitem>
+        </varlistentry>
+
+         <varlistentry>
+          <term><constant>-ENOPKG</constant></term>
+
+          <listitem><para>The bus cannot be resolved.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-EINVAL</constant></term>
+
+          <listitem><para>A required parameter was <constant>NULL</constant> or
+          <parameter>b</parameter> was zero and <parameter>id</parameter> did not equal
+          <constant>SD_ID128_NULL</constant>.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-ENOTCONN</constant></term>
+
+          <listitem><para>The bus is not connected.</para></listitem>
+        </varlistentry>
+      </variablelist>
+    </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>
+    </para>
+  </refsect1>
+
+</refentry>
Author	SHA1	Message	Date
Daan De Meyer	c40bd28419	sd-bus: Add sd_bus_set_server, sd_bus_get_bus_id docs	2020-04-19 21:41:03 +02:00
Daan De Meyer	e762fa0392	sd-bus: Add sd_bus_add_object_manager docs	2020-04-19 19:02:11 +02:00
Daan De Meyer	3841fa7916	sd-bus: Add sd_bus_add_filter docs	2020-04-19 19:00:22 +02:00