man/sd_bus_call.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="sd_bus_call"
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>sd_bus_call</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>sd_bus_call</refentrytitle>
  16     <manvolnum>3</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>sd_bus_call</refname>
  21     <refname>sd_bus_call_async</refname>
  22
  23     <refpurpose>Invoke a D-Bus method call</refpurpose>
  24   </refnamediv>
  25
  26   <refsynopsisdiv>
  27     <funcsynopsis>
  28       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  29
  30       <xi:include href="sd_bus_add_match.xml" xpointer="sd_bus_message_handler_t"/>
  31
  32       <funcprototype>
  33         <funcdef>int <function>sd_bus_call</function></funcdef>
  34         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  35         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  36         <paramdef>uint64_t <parameter>usec</parameter></paramdef>
  37         <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef>
  38         <paramdef>sd_bus_message **<parameter>reply</parameter></paramdef>
  39       </funcprototype>
  40
  41       <funcprototype>
  42         <funcdef>int <function>sd_bus_call_async</function></funcdef>
  43         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  44         <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
  45         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  46         <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
  47         <paramdef>void *<parameter>userdata</parameter></paramdef>
  48         <paramdef>uint64_t <parameter>usec</parameter></paramdef>
  49       </funcprototype>
  50     </funcsynopsis>
  51   </refsynopsisdiv>
  52
  53   <refsect1>
  54     <title>Description</title>
  55
  56     <para><function>sd_bus_call()</function> takes a complete bus message object and calls the
  57     corresponding D-Bus method. On success, the response is stored in <parameter>reply</parameter>.
  58     <parameter>usec</parameter> indicates the timeout in microseconds. If
  59     <parameter>ret_error</parameter> is not <constant>NULL</constant> and
  60     <function>sd_bus_call()</function> fails (either because of an internal error or because it
  61     received a D-Bus error reply), <parameter>ret_error</parameter> is initialized to an instance of
  62     <structname>sd_bus_error</structname> describing the error.</para>
  63
  64     <para><function>sd_bus_call_async()</function> is like <function>sd_bus_call()</function> but works
  65     asynchronously. The <parameter>callback</parameter> indicates the function to call when the response
  66     arrives. The <parameter>userdata</parameter> pointer will be passed to the callback function, and may be
  67     chosen freely by the caller. If <parameter>slot</parameter> is not <constant>NULL</constant> and
  68     <function>sd_bus_call_async()</function> succeeds, <parameter>slot</parameter> is set to a slot object
  69     which can be used to cancel the method call at a later time using
  70     <citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  71     If <parameter>slot</parameter> is <constant>NULL</constant>, the lifetime of the method call is bound to
  72     the lifetime of the bus object itself, and it cannot be cancelled independently. See
  73     <citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  74     for details. <parameter>callback</parameter> is called when a reply arrives with the reply,
  75     <parameter>userdata</parameter> and an <structname>sd_bus_error</structname> output parameter as its
  76     arguments. Unlike <function>sd_bus_call()</function>, the <structname>sd_bus_error</structname> output
  77     parameter passed to the callback will be empty. To determine whether the method call succeeded, use
  78     <citerefentry><refentrytitle>sd_bus_message_is_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  79     on the reply message passed to the callback instead. If the callback returns zero and the
  80     <structname>sd_bus_error</structname> output parameter is still empty when the callback finishes, other
  81     handlers registered with functions such as
  82     <citerefentry><refentrytitle>sd_bus_add_filter</refentrytitle><manvolnum>3</manvolnum></citerefentry> or
  83     <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry> are
  84     given a chance to process the message. If the callback returns a non-zero value or the
  85     <structname>sd_bus_error</structname> output parameter is not empty when the callback finishes, no
  86     further processing of the message is done. Generally, you want to return zero from the callback to give
  87     other registered handlers a chance to process the reply as well. (Note that the
  88     <structname>sd_bus_error</structname> parameter is an output parameter of the callback function, not an
  89     input parameter; it can be used to propagate errors from the callback handler, it will not receive any
  90     error that was received as method reply.)</para>
  91
  92     <para>If <parameter>usec</parameter> is zero, the default D-Bus method call timeout is used. See
  93     <citerefentry><refentrytitle>sd_bus_get_method_call_timeout</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  94     </para>
  95
  96   </refsect1>
  97
  98   <refsect1>
  99     <title>Return Value</title>
 100
 101     <para>On success, these functions return a non-negative integer. On failure, they return a
 102     negative errno-style error code.</para>
 103
 104     <refsect2 id='errors'>
 105       <title>Errors</title>
 106
 107       <para>Returned errors may indicate the following problems. When
 108       <function>sd_bus_call()</function> internally receives a D-Bus error reply, it will set
 109       <parameter>ret_error</parameter> if it is not <constant>NULL</constant>, and will return a
 110       negative value mapped from the error reply. See
 111       <citerefentry><refentrytitle>sd_bus_error_get_errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 112       </para>
 113
 114       <variablelist>
 115         <varlistentry>
 116           <term><constant>-EINVAL</constant></term>
 117
 118           <listitem><para>The input parameter <parameter>m</parameter> is <constant>NULL</constant>.
 119           </para></listitem>
 120
 121           <listitem><para>The input parameter <parameter>m</parameter> is not a D-Bus method call.
 122           To create a new D-Bus method call, use
 123           <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 124           </para></listitem>
 125
 126           <listitem><para>The input parameter <parameter>m</parameter> has the
 127           <constant>BUS_MESSAGE_NO_REPLY_EXPECTED</constant> flag set.</para></listitem>
 128
 129           <listitem><para>The input parameter <parameter>error</parameter> is
 130           non-<constant>NULL</constant> but was not set to <constant>SD_BUS_ERROR_NULL</constant>.
 131           </para></listitem>
 132         </varlistentry>
 133
 134         <varlistentry>
 135           <term><constant>-ECHILD</constant></term>
 136
 137           <listitem><para>The bus connection was allocated in a parent process and is being reused
 138           in a child process after <function>fork()</function>.</para></listitem>
 139         </varlistentry>
 140
 141         <varlistentry>
 142           <term><constant>-ENOTCONN</constant></term>
 143
 144           <listitem><para>The input parameter <parameter>bus</parameter> is
 145           <constant>NULL</constant> or the bus is not connected.</para></listitem>
 146         </varlistentry>
 147
 148         <varlistentry>
 149           <term><constant>-ECONNRESET</constant></term>
 150
 151           <listitem><para>The bus connection was closed while waiting for the response.
 152           </para></listitem>
 153         </varlistentry>
 154
 155         <varlistentry>
 156           <term><constant>-ETIMEDOUT</constant></term>
 157
 158           <listitem><para>A response was not received within the given timeout.</para></listitem>
 159         </varlistentry>
 160
 161         <varlistentry>
 162           <term><constant>-ELOOP</constant></term>
 163
 164           <listitem><para>The message <parameter>m</parameter> is addressed to its own client.
 165           </para></listitem>
 166         </varlistentry>
 167
 168         <varlistentry>
 169           <term><constant>-ENOMEM</constant></term>
 170
 171           <listitem><para>Memory allocation failed.</para></listitem>
 172         </varlistentry>
 173       </variablelist>
 174     </refsect2>
 175   </refsect1>
 176
 177   <xi:include href="libsystemd-pkgconfig.xml" />
 178
 179   <refsect1>
 180     <title>See Also</title>
 181
 182     <para>
 183       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 184       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 185       <citerefentry><refentrytitle>sd_bus_call_method</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 186       <citerefentry><refentrytitle>sd_bus_call_method_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 187       <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 188       <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 189       <citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 190     </para>
 191   </refsect1>
 192
 193 </refentry>