man/sd_bus_message_new_method_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_message_new_method_call"
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>sd_bus_message_new_method_call</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>sd_bus_message_new_method_call</refentrytitle>
  16     <manvolnum>3</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>sd_bus_message_new_method_call</refname>
  21     <refname>sd_bus_message_new_method_return</refname>
  22
  23     <refpurpose>Create a method call message</refpurpose>
  24   </refnamediv>
  25
  26   <refsynopsisdiv>
  27     <funcsynopsis>
  28       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  29
  30       <funcprototype>
  31         <funcdef>int sd_bus_message_new_method_call</funcdef>
  32         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  33         <paramdef>sd_bus_message **<parameter>m</parameter></paramdef>
  34         <paramdef>const char *<parameter>destination</parameter></paramdef>
  35         <paramdef>const char *<parameter>path</parameter></paramdef>
  36         <paramdef>const char *<parameter>interface</parameter></paramdef>
  37         <paramdef>const char *<parameter>member</parameter></paramdef>
  38       </funcprototype>
  39
  40       <funcprototype>
  41         <funcdef>int sd_bus_message_new_method_return</funcdef>
  42         <paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
  43         <paramdef>sd_bus_message **<parameter>m</parameter></paramdef>
  44       </funcprototype>
  45     </funcsynopsis>
  46   </refsynopsisdiv>
  47
  48   <refsect1>
  49     <title>Description</title>
  50
  51     <para>The <function>sd_bus_message_new_method_call()</function> function creates a new bus
  52     message object that encapsulates a D-Bus method call, and returns it in the
  53     <parameter>m</parameter> output parameter. The call will be made on the destination
  54     <parameter>destination</parameter>, path <parameter>path</parameter>, on the interface
  55     <parameter>interface</parameter>, member <parameter>member</parameter>.</para>
  56
  57     <para>Briefly, the <emphasis>destination</emphasis> is a dot-separated name that identifies a
  58     service connected to the bus. The <emphasis>path</emphasis> is a slash-separated identifier of
  59     an object within the destination that resembles a file system path. The meaning of this path is
  60     defined by the destination. The <emphasis>interface</emphasis> is a dot-separated name that
  61     resembles a Java interface name that identifies a group of methods and signals supported by the
  62     object identified by path. Methods and signals are collectively called
  63     <emphasis>members</emphasis> and are identified by a simple name composed of ASCII letters,
  64     numbers, and underscores. See the <ulink
  65     url="https://dbus.freedesktop.org/doc/dbus-tutorial.html#concepts">D-Bus Tutorial</ulink> for an
  66     in-depth explanation.</para>
  67
  68     <para>The <parameter>destination</parameter> parameter may be <constant>NULL</constant>. The
  69     <parameter>interface</parameter> parameter may be <constant>NULL</constant>, if the destination
  70     has only a single member with the given name and there is no ambiguity if the interface name is
  71     omitted.</para>
  72
  73     <para>The <function>sd_bus_message_new_method_call()</function> function creates a new bus
  74     message object that is a reply to the method call <parameter>call</parameter> and returns it in
  75     the <parameter>m</parameter> output parameter. The <parameter>call</parameter> parameter must be
  76     a method call message. The sender of <parameter>call</parameter> is used as the destination.
  77     </para>
  78   </refsect1>
  79
  80   <refsect1>
  81     <title>Return Value</title>
  82
  83     <para>This function returns 0 if the message object was successfully created, and a negative
  84     errno-style error code otherwise.</para>
  85
  86     <refsect2 id='errors'>
  87       <title>Errors</title>
  88
  89       <para>Returned errors may indicate the following problems:</para>
  90
  91       <variablelist>
  92         <varlistentry>
  93           <term><constant>-EINVAL</constant></term>
  94
  95           <listitem><para>The output parameter <parameter>m</parameter> is
  96           <constant>NULL</constant>.</para>
  97
  98           <para>The <parameter>destination</parameter> parameter is non-null and is not a valid D-Bus
  99           service name (<literal>org.somewhere.Something</literal>), the <parameter>path</parameter>
 100           parameter is not a valid D-Bus path (<literal>/an/object/path</literal>), the
 101           <parameter>interface</parameter> parameter is non-null and is not a valid D-Bus interface
 102           name (<literal>an.interface.name</literal>), or the <parameter>member</parameter> parameter
 103           is not a valid D-Bus member (<literal>Name</literal>).</para>
 104
 105           <para>The <parameter>call</parameter> parameter is not a method call object.</para>
 106           </listitem>
 107         </varlistentry>
 108
 109         <varlistentry>
 110           <term><constant>-ENOTCONN</constant></term>
 111
 112           <listitem><para>The bus parameter <parameter>bus</parameter> is <constant>NULL</constant> or
 113           the bus is not connected.</para></listitem>
 114         </varlistentry>
 115
 116         <varlistentry>
 117           <term><constant>-ENOMEM</constant></term>
 118
 119           <listitem><para>Memory allocation failed.</para></listitem>
 120         </varlistentry>
 121
 122         <varlistentry>
 123           <term><constant>-EPERM</constant></term>
 124
 125           <listitem>
 126             <para>The <parameter>call</parameter> parameter is not sealed.</para>
 127           </listitem>
 128         </varlistentry>
 129
 130         <varlistentry>
 131           <term><constant>-EOPNOTSUPP</constant></term>
 132
 133           <listitem>
 134             <para>The <parameter>call</parameter> message does not have a cookie.</para>
 135           </listitem>
 136         </varlistentry>
 137       </variablelist>
 138     </refsect2>
 139   </refsect1>
 140
 141   <xi:include href="libsystemd-pkgconfig.xml" />
 142
 143   <refsect1>
 144     <title>Examples</title>
 145
 146     <example>
 147       <title>Make a call to a D-Bus method that takes a single parameter</title>
 148
 149       <programlisting><xi:include href="print-unit-path.c" parse="text" /></programlisting>
 150       <para>This defines a minimally useful program that will open a connection to the bus, create a
 151       message object, send it, wait for the reply, and finally extract and print the answer. It does
 152       error handling and proper memory management.</para>
 153     </example>
 154   </refsect1>
 155
 156   <refsect1>
 157     <title>See Also</title>
 158
 159     <para>
 160       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 161       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 162       <citerefentry><refentrytitle>sd_bus_path_encode</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 163     </para>
 164   </refsect1>
 165
 166 </refentry>