shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2025-01-11 09:18:07 +03:00
Code

man: let's document explicitly that method reply handlers won't get ret_error set to method error

Browse Source 
Fixes: #8108
This commit is contained in:
Lennart Poettering 2020-05-19 19:06:22 +02:00
parent af955f917f
commit 2efa512a1a
1 changed files with 21 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
man/sd_bus_call.xml
View File

@ -61,32 +61,33 @@
received a D-Bus error reply), <parameter>ret_error</parameter> is initialized to an instance of
<structname>sd_bus_error</structname> describing the error.</para>
<para><function>sd_bus_call_async()</function> is like <function>sd_bus_call()</function> but
works asynchronously. The <parameter>callback</parameter> indicates the function to call when
the response arrives. The <parameter>userdata</parameter> pointer will be passed to the callback
function, and may be chosen freely by the caller. If <parameter>slot</parameter> is not
<constant>NULL</constant> and <function>sd_bus_call_async()</function> succeeds,
<parameter>slot</parameter> is set to a slot object which can be used to cancel the method call
at a later time using
<para><function>sd_bus_call_async()</function> is like <function>sd_bus_call()</function> but works
asynchronously. The <parameter>callback</parameter> indicates the function to call when the response
arrives. The <parameter>userdata</parameter> pointer will be passed to the callback function, and may be
chosen freely by the caller. If <parameter>slot</parameter> is not <constant>NULL</constant> and
<function>sd_bus_call_async()</function> succeeds, <parameter>slot</parameter> is set to a slot object
which can be used to cancel the method call at a later time using
<citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
If <parameter>slot</parameter> is <constant>NULL</constant>, the lifetime of the method call is
bound to the lifetime of the bus object itself, and it cannot be cancelled independently. See
If <parameter>slot</parameter> is <constant>NULL</constant>, the lifetime of the method call is bound to
the lifetime of the bus object itself, and it cannot be cancelled independently. See
<citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for details. <parameter>callback</parameter> is called when a reply arrives with the reply,
<parameter>userdata</parameter> and an <structname>sd_bus_error</structname> output
parameter as its arguments. Unlike <function>sd_bus_call()</function>, the
<structname>sd_bus_error</structname> output parameter passed to the callback will be empty. To
determine whether the method call succeeded, use
<parameter>userdata</parameter> and an <structname>sd_bus_error</structname> output parameter as its
arguments. Unlike <function>sd_bus_call()</function>, the <structname>sd_bus_error</structname> output
parameter passed to the callback will be empty. To determine whether the method call succeeded, use
<citerefentry><refentrytitle>sd_bus_message_is_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>
on the reply message passed to the callback instead. If the callback returns zero and the
<structname>sd_bus_error</structname> output parameter is still empty when the callback
inishes, other handlers registered with functions such as
<structname>sd_bus_error</structname> output parameter is still empty when the callback finishes, other
handlers registered with functions such as
<citerefentry><refentrytitle>sd_bus_add_filter</refentrytitle><manvolnum>3</manvolnum></citerefentry> or
<citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>
are given a chance to process the message. If the callback returns a non-zero value or the
<structname>sd_bus_error</structname> output parameter is not empty when the callback finishes,
no further processing of the message is done. Generally, you want to return zero from the
callback to give other registered handlers a chance to process the reply as well.</para>
<citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry> are
given a chance to process the message. If the callback returns a non-zero value or the
<structname>sd_bus_error</structname> output parameter is not empty when the callback finishes, no
further processing of the message is done. Generally, you want to return zero from the callback to give
other registered handlers a chance to process the reply as well. (Note that the
<structname>sd_bus_error</structname> parameter is an output parameter of the callback function, not an
input parameter; it can be used to propagate errors from the callback handler, it will not receive any
error that was received as method reply.)</para>
<para>If <parameter>usec</parameter> is zero, the default D-Bus method call timeout is used. See
<citerefentry><refentrytitle>sd_bus_get_method_call_timeout</refentrytitle><manvolnum>3</manvolnum></citerefentry>.