<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>
<funcsynopsis>
<funcsynopsisinfo>#include <systemd/sd-bus-vtable.h></funcsynopsisinfo>
- <funcprototype>
- <funcdef>typedef int (*<function>sd_bus_message_handler_t</function>)</funcdef>
- <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
- <paramdef>void *<parameter>userdata</parameter></paramdef>
- <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef>
- </funcprototype>
+ <xi:include href="sd_bus_add_match.xml" xpointer="sd_bus_message_handler_t"/>
<funcprototype>
<funcdef>typedef int (*<function>sd_bus_property_get_t</function>)</funcdef>
<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>
<para>
<constant>SD_BUS_VTABLE_END</constant>
</para>
+ <para>
+ <constant>SD_BUS_METHOD_WITH_ARGS_OFFSET(
+ <replaceable>member</replaceable>,
+ <replaceable>args</replaceable>,
+ <replaceable>result</replaceable>,
+ <replaceable>handler</replaceable>,
+ <replaceable>offset</replaceable>,
+ <replaceable>flags</replaceable>)
+ </constant>
+ </para>
+ <para>
+ <constant>SD_BUS_METHOD_WITH_ARGS(
+ <replaceable>member</replaceable>,
+ <replaceable>args</replaceable>,
+ <replaceable>result</replaceable>,
+ <replaceable>handler</replaceable>,
+ <replaceable>flags</replaceable>)
+ </constant>
+ </para>
<para>
<constant>SD_BUS_METHOD_WITH_NAMES_OFFSET(
<replaceable>member</replaceable>,
<replaceable>flags</replaceable>)
</constant>
</para>
+ <para>
+ <constant>SD_BUS_SIGNAL_WITH_ARGS(
+ <replaceable>member</replaceable>,
+ <replaceable>args</replaceable>,
+ <replaceable>flags</replaceable>)
+ </constant>
+ </para>
<para>
<constant>SD_BUS_SIGNAL_WITH_NAMES(
<replaceable>member</replaceable>,
</para>
<para>
<constant>SD_BUS_PARAM(<replaceable>name</replaceable>)</constant>
+ <constant>SD_BUS_ARGS(<replaceable>...</replaceable>)</constant>
+ <constant>SD_BUS_RESULT(<replaceable>...</replaceable>)</constant>
+ <constant>SD_BUS_NO_ARGS</constant>
+ <constant>SD_BUS_NO_RESULT</constant>
</para>
</funcsynopsis>
</refsynopsisdiv>
<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
<listitem><para>Those must always be the first and last element.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><constant>SD_BUS_METHOD_WITH_ARGS_OFFSET()</constant></term>
+ <term><constant>SD_BUS_METHOD_WITH_ARGS()</constant></term>
+
+ <listitem><para>Declare a D-Bus method with the name <replaceable>member</replaceable>,
+ arguments <replaceable>args</replaceable> and result <replaceable>result</replaceable>.
+ <replaceable>args</replaceable> expects a sequence of argument type/name pairs wrapped in the
+ <constant>SD_BUS_ARGS()</constant> macro. The elements at even indices in this list describe the
+ types of the method's arguments. The method's parameter signature is the concatenation of all the
+ string literals at even indices in <replaceable>args</replaceable>. If a method has no parameters,
+ pass <constant>SD_BUS_NO_ARGS</constant> to <replaceable>args</replaceable>. The elements at uneven
+ indices describe the names of the method's arguments. <replaceable>result</replaceable> expects a
+ sequence of type/name pairs wrapped in the <constant>SD_BUS_RESULT()</constant> macro in the same
+ format as <constant>SD_BUS_ARGS()</constant>. The method's result signature is the concatenation of
+ all the string literals at even indices in <replaceable>result</replaceable>. If a method has no
+ result, pass <constant>SD_BUS_NO_RESULT</constant> to <replaceable>result</replaceable>. Note that
+ argument types are expected to be quoted string literals and argument names are expected to be
+ unquoted string literals. See below for a complete example.</para>
+
+ <para>The handler function <replaceable>handler</replaceable> must be of type
+ <function>sd_bus_message_handler_t</function>. It will be called to handle the incoming 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. 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. Parameter <replaceable>flags</replaceable> is a
+ combination of flags, see below.</para>
+
+ <constant>SD_BUS_METHOD_WITH_ARGS()</constant> is a shorthand for calling
+ <constant>SD_BUS_METHOD_WITH_ARGS_OFFSET()</constant> with an offset of zero.
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><constant>SD_BUS_METHOD_WITH_NAMES_OFFSET()</constant></term>
<term><constant>SD_BUS_METHOD_WITH_NAMES()</constant></term>
parameter signature <replaceable>signature</replaceable>, result signature
<replaceable>result</replaceable>. Parameters <replaceable>in_names</replaceable> and
<replaceable>out_names</replaceable> specify the argument names of the input and output
- arguments in the function signature. The handler function
- <replaceable>handler</replaceable> must be of type
- <function>sd_bus_message_handler_t</function>. It will be called to handle the incoming
- 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. 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
+ arguments in the function signature. <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>
+ <constant>SD_BUS_PARAM()</constant> macro, see below. In all other regards, this macro behaves
+ exactly the same as <constant>SD_BUS_METHOD_WITH_ARGS_OFFSET()</constant>.</para>
<para><constant>SD_BUS_METHOD_WITH_NAMES()</constant>,
<constant>SD_BUS_METHOD_WITH_OFFSET()</constant>, and <constant>SD_BUS_METHOD()</constant>
are variants which specify zero offset (<replaceable>userdata</replaceable> parameter is
passed with no change), leave the names unset (i.e. no parameter names), or both.</para>
+
+ <para>Prefer using <constant>SD_BUS_METHOD_WITH_ARGS_OFFSET()</constant> and
+ <constant>SD_BUS_METHOD_WITH_ARGS()</constant> over these macros as they allow specifying argument
+ types and names next to each other which is less error-prone than first specifying all argument
+ types followed by specifying all argument names.</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><constant>SD_BUS_SIGNAL_WITH_ARGS()</constant></term>
+
+ <listitem><para>>Declare a D-Bus signal with the name <replaceable>member</replaceable> and
+ arguments <replaceable>args</replaceable>. <replaceable>args</replaceable> expects a sequence of
+ argument type/name pairs wrapped in the <constant>SD_BUS_ARGS()</constant> macro. The elements at
+ even indices in this list describe the types of the signal's arguments. The signal's parameter
+ signature is the concatenation of all the string literals at even indices in
+ <replaceable>args</replaceable>. If a signal has no parameters, pass
+ <constant>SD_BUS_NO_ARGS</constant> to <replaceable>args</replaceable>. The elements at uneven
+ indices describe the names of the signal's arguments. Parameter <replaceable>flags</replaceable> is
+ a combination of flags. See below for a complete example.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><constant>SD_BUS_SIGNAL_WITH_NAMES()</constant></term>
<term><constant>SD_BUS_SIGNAL()</constant></term>
Parameter <replaceable>flags</replaceable> is a combination of flags, see below.
</para>
- <para>Equivalent to <constant>SD_BUS_SIGNAL_WITH_NAMES()</constant> with the
- <replaceable>names</replaceable> parameter unset (i.e. no parameter names).</para>
+ <para><constant>SD_BUS_SIGNAL()</constant> is equivalent to
+ <constant>SD_BUS_SIGNAL_WITH_NAMES()</constant> with the <replaceable>names</replaceable> parameter
+ unset (i.e. no parameter names).</para>
+
+ <para>Prefer using <constant>SD_BUS_SIGNAL_WITH_ARGS()</constant> over these macros as it allows
+ specifying argument types and names next to each other which is less error-prone than first
+ specifying all argument types followed by specifying all argument names.</para>
</listitem>
</varlistentry>
This corresponds to the <constant>org.freedesktop.systemd1.Explicit</constant> annotation
in introspection data.</para></listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><constant>SD_BUS_VTABLE_SENSITIVE</constant></term>
+
+ <listitem><para>Mark this vtable method entry as processing sensitive data. When set,
+ incoming method call messages and their outgoing reply messages are marked as sensitive using
+ <citerefentry><refentrytitle>sd_bus_message_sensitive</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ so that they are erased from memory when freed.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>SD_BUS_VTABLE_ABSOLUTE_OFFSET</constant></term>
+
+ <listitem><para>Mark this vtable method or property entry so that the user data pointer passed to
+ its associated handler functions is determined slightly differently: instead of adding the offset
+ parameter of the entry to the user data pointer specified during vtable registration, the offset is
+ passed directly, converted to a pointer, without taking the user data pointer specified during
+ vtable registration into account.</para></listitem>
+ </varlistentry>
</variablelist>
</refsect2>
</refsect1>
<refsect1>
<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
+ <para>On success, <function>sd_bus_add_object_vtable()</function> and
+ <function>sd_bus_add_fallback_vtable()</function> return a non-negative integer. On
failure, they return a negative errno-style error code.</para>
<refsect2>
<para>
<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>busctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>busctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_bus_emit_properties_changed</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_bus_emit_object_added</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>
projects / thirdparty / systemd.git / blobdiff