diff options
author | Lennart Poettering <lennart@poettering.net> | 2020-05-19 19:06:22 +0200 |
---|---|---|
committer | Lennart Poettering <lennart@poettering.net> | 2020-05-20 15:56:48 +0200 |
commit | 2efa512a1add815bf5a6a715fbb6856f155542c1 (patch) | |
tree | 2d2e7a1b8aa48acef2dab04e0b9a41eae13e921c /man/sd_bus_call.xml | |
parent | af955f917f2930957fd6fd564386aa8e541504a1 (diff) | |
download | systemd-2efa512a1add815bf5a6a715fbb6856f155542c1.tar.gz |
man: let's document explicitly that method reply handlers won't get ret_error set to method error
Fixes: #8108
Diffstat (limited to 'man/sd_bus_call.xml')
-rw-r--r-- | man/sd_bus_call.xml | 41 |
1 files changed, 21 insertions, 20 deletions
diff --git a/man/sd_bus_call.xml b/man/sd_bus_call.xml index b93efb2622..f47f9c8526 100644 --- a/man/sd_bus_call.xml +++ b/man/sd_bus_call.xml @@ -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>. |