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>The message <parameter>m</parameter> passed to the callback is only borrowed, that is, the callback should
  93     not call <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  94     on it. If the callback wants to hold on to the message beyond the lifetime of the callback, it needs to call
  95     <citerefentry><refentrytitle>sd_bus_message_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry> to create a
  96     new reference.</para>
  97
  98     <para>If <parameter>usec</parameter> is zero, the default D-Bus method call timeout is used. See
  99     <citerefentry><refentrytitle>sd_bus_get_method_call_timeout</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 100     </para>
 101
 102   </refsect1>
 103
 104   <refsect1>
 105     <title>Return Value</title>
 106
 107     <para>On success, these functions return a non-negative integer. On failure, they return a
 108     negative errno-style error code.</para>
 109
 110     <refsect2 id='errors'>
 111       <title>Errors</title>
 112
 113       <para>When <function>sd_bus_call()</function> internally receives a D-Bus error reply, it will set
 114       <parameter>ret_error</parameter> if it is not <constant>NULL</constant>, and will return a negative
 115       value mapped from the error reply, see
 116       <citerefentry><refentrytitle>sd_bus_error_get_errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 117       </para>
 118
 119       <para>Returned errors may indicate the following problems:</para>
 120
 121       <variablelist>
 122         <varlistentry>
 123           <term><constant>-EINVAL</constant></term>
 124
 125           <listitem><para>The input parameter <parameter>m</parameter> is <constant>NULL</constant>.
 126           </para>
 127
 128           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 129
 130           <listitem><para>The input parameter <parameter>m</parameter> is not a D-Bus method call.
 131           To create a new D-Bus method call, use
 132           <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 133           </para></listitem>
 134
 135           <listitem><para>The input parameter <parameter>m</parameter> has the
 136           <constant>BUS_MESSAGE_NO_REPLY_EXPECTED</constant> flag set.</para></listitem>
 137
 138           <listitem><para>The input parameter <parameter>error</parameter> is
 139           non-<constant>NULL</constant> but was not set to <constant>SD_BUS_ERROR_NULL</constant>.
 140           </para></listitem>
 141         </varlistentry>
 142
 143         <varlistentry>
 144           <term><constant>-ECHILD</constant></term>
 145
 146           <listitem><para>The bus connection was allocated in a parent process and is being reused
 147           in a child process after <function>fork()</function>.</para>
 148
 149           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 150         </varlistentry>
 151
 152         <varlistentry>
 153           <term><constant>-ENOTCONN</constant></term>
 154
 155           <listitem><para>The input parameter <parameter>bus</parameter> is
 156           <constant>NULL</constant> or the bus is not connected.</para>
 157
 158           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 159         </varlistentry>
 160
 161         <varlistentry>
 162           <term><constant>-ECONNRESET</constant></term>
 163
 164           <listitem><para>The bus connection was closed while waiting for the response.
 165           </para>
 166
 167           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 168         </varlistentry>
 169
 170         <varlistentry>
 171           <term><constant>-ETIMEDOUT</constant></term>
 172
 173           <listitem><para>A response was not received within the given timeout.</para>
 174
 175           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 176         </varlistentry>
 177
 178         <varlistentry>
 179           <term><constant>-ELOOP</constant></term>
 180
 181           <listitem><para>The message <parameter>m</parameter> is addressed to its own client.
 182           </para>
 183
 184           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 185         </varlistentry>
 186
 187         <varlistentry>
 188           <term><constant>-ENOMEM</constant></term>
 189
 190           <listitem><para>Memory allocation failed.</para>
 191
 192           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 193         </varlistentry>
 194       </variablelist>
 195     </refsect2>
 196   </refsect1>
 197
 198   <xi:include href="libsystemd-pkgconfig.xml" />
 199
 200   <refsect1>
 201     <title>History</title>
 202     <para><function>sd_bus_call()</function> and
 203     <function>sd_bus_call_async()</function> were added in version 246.</para>
 204   </refsect1>
 205
 206   <refsect1>
 207     <title>See Also</title>
 208
 209     <para>
 210       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 211       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 212       <citerefentry><refentrytitle>sd_bus_call_method</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 213       <citerefentry><refentrytitle>sd_bus_call_method_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 214       <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 215       <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 216       <citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 217     </para>
 218   </refsect1>
 219
 220 </refentry>