sd-bus: Add sd_bus_add_filter docs

diff --git a/man/rules/meson.build b/man/rules/meson.build
index b828cdfafc16dd1b2e9569bb86cff8f680123347..5fc2b5a9806d09938fa51e7d82d52b97f4ed9412 100644 (file)
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -144,6 +144,7 @@ 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_attach_event', '3', ['sd_bus_detach_event', 'sd_bus_get_event'], ''],

diff --git a/man/sd-bus.xml b/man/sd-bus.xml
index 8c05e335126947bdb4c26a1890e1288a3c774f3e..389ae18b50bb80737b7b3a802fdf8ca3a5891e39 100644 (file)
--- a/man/sd-bus.xml
+++ b/man/sd-bus.xml
@@ -45,6 +45,7 @@
 <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>,

diff --git a/man/sd_bus_add_object.xml b/man/sd_bus_add_object.xml
index 2abe2342f0a6d97b858c7fefe1f42f393759e579..373609f04227ee4266becd1853854a3e2006be7c 100644 (file)
--- 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