picnoir
/
Systemd
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

sd-bus: sd_bus_call docs improvements

This commit is contained in:
Daan De Meyer 2020-03-31 19:50:53 +02:00 committed by Zbigniew Jędrzejewski-Szmek
parent e3e5a6eebd
commit 47203ed085
1 changed files with 22 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
man/sd_bus_call.xml
View File

@ -52,34 +52,39 @@
<title>Description</title> <title>Description</title>
<para><function>sd_bus_call()</function> takes a complete bus message object and calls the <para><function>sd_bus_call()</function> takes a complete bus message object and calls the
corresponding D-Bus method. The response is stored in <parameter>reply</parameter>. corresponding D-Bus method. On success, the response is stored in <parameter>reply</parameter>.
<parameter>usec</parameter> indicates the timeout in microseconds. If <parameter>usec</parameter> indicates the timeout in microseconds. If
<parameter>ret_error</parameter> is not <constant>NULL</constant> and <parameter>ret_error</parameter> is not <constant>NULL</constant> and
<function>sd_bus_call()</function> returns an error, <parameter>ret_error</parameter> is <function>sd_bus_call()</function> fails (either because of an internal error or because it
initialized to an instance of <structname>sd_bus_error</structname> describing the error.</para> 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 <para><function>sd_bus_call_async()</function> is like <function>sd_bus_call()</function> but
works asynchronously. The <parameter>callback</parameter> shall reference a function to call works asynchronously. The <parameter>callback</parameter> indicates the function to call when
when the event source is triggered. The <parameter>userdata</parameter> pointer will be passed the response arrives. The <parameter>userdata</parameter> pointer will be passed to the callback
to the callback function, and may be chosen freely by the caller. If <parameter>slot</parameter> function, and may be chosen freely by the caller. If <parameter>slot</parameter> is not
is not <constant>NULL</constant> and <function>sd_bus_call_async()</function> succeeds, <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 <parameter>slot</parameter> is set to a slot object which can be used to cancel the method call
at a later time using at a later time using
<citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>. <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 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 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> <citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for details. The <parameter>callback</parameter> function is called when the response arrives for details. <parameter>callback</parameter> is called when a reply arrives with the reply,
and receives the response, <parameter>userdata</parameter> and a <parameter>userdata</parameter> and an <structname>sd_bus_error</structname> output
<structname>sd_bus_error</structname> object as its arguments. The parameter as its arguments. Unlike <function>sd_bus_call()</function>, the
<structname>sd_bus_error</structname> object is unused here and should be ignored. If <structname>sd_bus_error</structname> output parameter passed to the callback will be empty. To
<parameter>callback</parameter> returns a non-negative integer when called, a debug message is determine whether the method call succeeded, use
logged along with details about the response.</para>
<para>To determine whether the method call succeeded, use
<citerefentry><refentrytitle>sd_bus_message_is_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry> <citerefentry><refentrytitle>sd_bus_message_is_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>
on the reply object returned by <function>sd_bus_call()</function> or passed to the callback of on the reply message passed to the callback instead. If the callback returns zero and the
<function>sd_bus_call_async()</function>.</para> <structname>sd_bus_error</structname> output parameter is still empty when the callback
inishes, 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>
<para>If <parameter>usec</parameter> is zero, the default D-Bus method call timeout is used. See <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>. <citerefentry><refentrytitle>sd_bus_get_method_call_timeout</refentrytitle><manvolnum>3</manvolnum></citerefentry>.