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+ -->
   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:</para>
 108
 109       <variablelist>
 110         <varlistentry>
 111           <term><constant>-EINVAL</constant></term>
 112
 113           <listitem><para>The input parameter <parameter>m</parameter> is <constant>NULL</constant>.
 114           </para></listitem>
 115
 116           <listitem><para>The input parameter <parameter>m</parameter> is not a D-Bus method call.
 117           To create a new D-Bus method call, use
 118           <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 119           </para></listitem>
 120
 121           <listitem><para>The input parameter <parameter>m</parameter> has the
 122           <constant>BUS_MESSAGE_NO_REPLY_EXPECTED</constant> flag set.</para></listitem>
 123
 124           <listitem><para>The input parameter <parameter>error</parameter> is
 125           non-<constant>NULL</constant> but was not set to <constant>SD_BUS_ERROR_NULL</constant>.
 126           </para></listitem>
 127         </varlistentry>
 128
 129         <varlistentry>
 130           <term><constant>-ECHILD</constant></term>
 131
 132           <listitem><para>The bus connection was allocated in a parent process and is being reused
 133           in a child process after <function>fork()</function>.</para></listitem>
 134         </varlistentry>
 135
 136         <varlistentry>
 137           <term><constant>-ENOTCONN</constant></term>
 138
 139           <listitem><para>The input parameter <parameter>bus</parameter> is
 140           <constant>NULL</constant> or the bus is not connected.</para></listitem>
 141         </varlistentry>
 142
 143         <varlistentry>
 144           <term><constant>-ECONNRESET</constant></term>
 145
 146           <listitem><para>The bus connection was closed while waiting for the response.
 147           </para></listitem>
 148         </varlistentry>
 149
 150         <varlistentry>
 151           <term><constant>-ETIMEDOUT</constant></term>
 152
 153           <listitem><para>A response was not received within the given timeout.</para></listitem>
 154         </varlistentry>
 155
 156         <varlistentry>
 157           <term><constant>-ELOOP</constant></term>
 158
 159           <listitem><para>The message <parameter>m</parameter> is addressed to its own client.
 160           </para></listitem>
 161         </varlistentry>
 162
 163         <varlistentry>
 164           <term><constant>-ENOMEM</constant></term>
 165
 166           <listitem><para>Memory allocation failed.</para></listitem>
 167         </varlistentry>
 168       </variablelist>
 169     </refsect2>
 170   </refsect1>
 171
 172   <xi:include href="libsystemd-pkgconfig.xml" />
 173
 174   <refsect1>
 175     <title>See Also</title>
 176
 177     <para>
 178       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 179       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 180       <citerefentry><refentrytitle>sd_bus_call_method</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 181       <citerefentry><refentrytitle>sd_bus_call_method_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 182       <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 183       <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 184     </para>
 185   </refsect1>
 186
 187 </refentry>