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       <funcprototype>
  31         <funcdef>int <function>sd_bus_call</function></funcdef>
  32         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  33         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  34         <paramdef>uint64_t <parameter>usec</parameter></paramdef>
  35         <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef>
  36         <paramdef>sd_bus_message **<parameter>reply</parameter></paramdef>
  37       </funcprototype>
  38
  39       <funcprototype>
  40         <funcdef>int <function>sd_bus_call_async</function></funcdef>
  41         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  42         <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
  43         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  44         <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
  45         <paramdef>void *<parameter>userdata</parameter></paramdef>
  46         <paramdef>uint64_t <parameter>usec</parameter></paramdef>
  47       </funcprototype>
  48     </funcsynopsis>
  49   </refsynopsisdiv>
  50
  51   <refsect1>
  52     <title>Description</title>
  53
  54     <para><function>sd_bus_call()</function> takes a complete bus message object and calls the
  55     corresponding D-Bus method. The response is stored in <parameter>reply</parameter>.
  56     <parameter>usec</parameter> indicates the timeout in microseconds. If
  57     <parameter>ret_error</parameter> is not <constant>NULL</constant> and
  58     <function>sd_bus_call()</function> returns an error, <parameter>ret_error</parameter> is
  59     initialized to an instance of <structname>sd_bus_error</structname> describing the error.</para>
  60
  61     <para><function>sd_bus_call_async()</function> is like <function>sd_bus_call()</function> but
  62     works asynchronously. The <parameter>callback</parameter> shall reference a function to call
  63     when the event source is triggered. The <parameter>userdata</parameter> pointer will be passed
  64     to the callback function, and may be chosen freely by the caller. If <parameter>slot</parameter>
  65     is not <constant>NULL</constant> and <function>sd_bus_call_async()</function> succeeds,
  66     <parameter>slot</parameter> is set to a slot object which can be used to cancel the method call
  67     at a later time using
  68     <citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  69     If <parameter>slot</parameter> is <constant>NULL</constant>, the lifetime of the method call is
  70     bound to the lifetime of the bus object itself, and it cannot be cancelled independently. See
  71     <citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  72     for details. The <parameter>callback</parameter> function is called when the response arrives
  73     and receives the response, <parameter>userdata</parameter> and a
  74     <structname>sd_bus_error</structname> object as its arguments. The
  75     <structname>sd_bus_error</structname> object is unused here and should be ignored. If
  76     <parameter>callback</parameter> returns a non-negative integer when called, a debug message is
  77     logged along with details about the response.</para>
  78
  79     <para>To determine whether the method call succeeded, use
  80     <citerefentry><refentrytitle>sd_bus_message_is_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  81     on the reply object returned by <function>sd_bus_call()</function> or passed to the callback of
  82     <function>sd_bus_call_async()</function>.</para>
  83
  84     <para>If <parameter>usec</parameter> is zero, the timeout set using
  85     <citerefentry><refentrytitle>sd_bus_set_method_call_timeout</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  86     is used. If no method call timeout was set, the timeout is read from the
  87     <varname>$SYSTEMD_BUS_TIMEOUT</varname> environment variable. If this environment variable is
  88     unset or does not contain a valid timeout, the implementation falls back to a predefined method
  89     call timeout of 25 seconds. Note that <varname>$SYSTEMD_BUS_TIMEOUT</varname> is read once and
  90     cached so callers should not rely on being able to change the default method call timeout at
  91     runtime by changing the value of <varname>$SYSTEMD_BUS_TIMEOUT</varname>. Instead, call
  92     <function>sd_bus_set_method_call_timeout()</function> to change the default method call timeout.
  93     </para>
  94
  95   </refsect1>
  96
  97   <refsect1>
  98     <title>Return Value</title>
  99
 100     <para>On success, these functions return a non-negative integer. On failure, they return a
 101     negative errno-style error code.</para>
 102
 103     <refsect2 id='errors'>
 104       <title>Errors</title>
 105
 106       <para>Returned errors may indicate the following problems:</para>
 107
 108       <variablelist>
 109         <varlistentry>
 110           <term><constant>-EINVAL</constant></term>
 111
 112           <listitem><para>The input parameter <parameter>m</parameter> is <constant>NULL</constant>.
 113           </para></listitem>
 114
 115           <listitem><para>The input parameter <parameter>m</parameter> is not a D-Bus method call.
 116           To create a new D-Bus method call, use
 117           <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 118           </para></listitem>
 119
 120           <listitem><para>The input parameter <parameter>m</parameter> has the
 121           <constant>BUS_MESSAGE_NO_REPLY_EXPECTED</constant> flag set.</para></listitem>
 122
 123           <listitem><para>The input parameter <parameter>error</parameter> is
 124           non-<constant>NULL</constant> but was not set to <constant>SD_BUS_ERROR_NULL</constant>.
 125           </para></listitem>
 126         </varlistentry>
 127
 128         <varlistentry>
 129           <term><constant>-ECHILD</constant></term>
 130
 131           <listitem><para>The bus connection was allocated in a parent process and is being reused
 132           in a child process after <function>fork()</function>.</para></listitem>
 133         </varlistentry>
 134
 135         <varlistentry>
 136           <term><constant>-ENOTCONN</constant></term>
 137
 138           <listitem><para>The bus parameter <parameter>bus</parameter> is <constant>NULL</constant>
 139           or the bus is not connected.</para></listitem>
 140         </varlistentry>
 141
 142         <varlistentry>
 143           <term><constant>-ECONNRESET</constant></term>
 144
 145           <listitem><para>The client was disconnected while waiting for the response.
 146           </para></listitem>
 147         </varlistentry>
 148
 149         <varlistentry>
 150           <term><constant>-ETIMEDOUT</constant></term>
 151
 152           <listitem><para>A response was not received within the given timeout.</para></listitem>
 153         </varlistentry>
 154
 155         <varlistentry>
 156           <term><constant>-ELOOP</constant></term>
 157
 158           <listitem><para>The message <parameter>m</parameter> is addressed to its own client.
 159           </para></listitem>
 160         </varlistentry>
 161
 162         <varlistentry>
 163           <term><constant>-ENOMEM</constant></term>
 164
 165           <listitem><para>Memory allocation failed.</para></listitem>
 166         </varlistentry>
 167       </variablelist>
 168     </refsect2>
 169   </refsect1>
 170
 171   <xi:include href="libsystemd-pkgconfig.xml" />
 172
 173   <refsect1>
 174     <title>See Also</title>
 175
 176     <para>
 177       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 178       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 179       <citerefentry><refentrytitle>sd_bus_call_method</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 180       <citerefentry><refentrytitle>sd_bus_call_method_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 181       <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 182       <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 183     </para>
 184   </refsect1>
 185
 186 </refentry>