diff options
Diffstat (limited to 'man/sd_bus_call.xml')
| -rw-r--r-- | man/sd_bus_call.xml | 200 |
1 files changed, 200 insertions, 0 deletions
diff --git a/man/sd_bus_call.xml b/man/sd_bus_call.xml new file mode 100644 index 0000000..1f7dfc2 --- /dev/null +++ b/man/sd_bus_call.xml @@ -0,0 +1,200 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> + +<refentry id="sd_bus_call" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_call</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_call</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_call</refname> + <refname>sd_bus_call_async</refname> + + <refpurpose>Invoke a D-Bus method call</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <xi:include href="sd_bus_add_match.xml" xpointer="sd_bus_message_handler_t"/> + + <funcprototype> + <funcdef>int <function>sd_bus_call</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>uint64_t <parameter>usec</parameter></paramdef> + <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef> + <paramdef>sd_bus_message **<parameter>reply</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_call_async</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + <paramdef>uint64_t <parameter>usec</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_call()</function> takes a complete bus message object and calls the + corresponding D-Bus method. On success, the response is stored in <parameter>reply</parameter>. + <parameter>usec</parameter> indicates the timeout in microseconds. If + <parameter>ret_error</parameter> is not <constant>NULL</constant> and + <function>sd_bus_call()</function> fails (either because of an internal error or because it + 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 + <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 + <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 + <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 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. (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>The message <parameter>m</parameter> passed to the callback is only borrowed, that is, the callback should + not call <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> + on it. If the callback wants to hold on to the message beyond the lifetime of the callback, it needs to call + <citerefentry><refentrytitle>sd_bus_message_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry> to create a + new reference.</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>. + </para> + + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these functions return a non-negative integer. On failure, they return a + negative errno-style error code.</para> + + <refsect2 id='errors'> + <title>Errors</title> + + <para>When <function>sd_bus_call()</function> internally receives a D-Bus error reply, it will set + <parameter>ret_error</parameter> if it is not <constant>NULL</constant>, and will return a negative + value mapped from the error reply, see + <citerefentry><refentrytitle>sd_bus_error_get_errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>The input parameter <parameter>m</parameter> is <constant>NULL</constant>. + </para></listitem> + + <listitem><para>The input parameter <parameter>m</parameter> is not a D-Bus method call. + To create a new D-Bus method call, use + <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para></listitem> + + <listitem><para>The input parameter <parameter>m</parameter> has the + <constant>BUS_MESSAGE_NO_REPLY_EXPECTED</constant> flag set.</para></listitem> + + <listitem><para>The input parameter <parameter>error</parameter> is + non-<constant>NULL</constant> but was not set to <constant>SD_BUS_ERROR_NULL</constant>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The bus connection was allocated in a parent process and is being reused + in a child process after <function>fork()</function>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOTCONN</constant></term> + + <listitem><para>The input parameter <parameter>bus</parameter> is + <constant>NULL</constant> or the bus is not connected.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ECONNRESET</constant></term> + + <listitem><para>The bus connection was closed while waiting for the response. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ETIMEDOUT</constant></term> + + <listitem><para>A response was not received within the given timeout.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ELOOP</constant></term> + + <listitem><para>The message <parameter>m</parameter> is addressed to its own client. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_call_method</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_call_method_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |