2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
6 <refentry id=
"sd_bus_message_new_method_call"
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
10 <title>sd_bus_message_new_method_call
</title>
11 <productname>systemd
</productname>
15 <refentrytitle>sd_bus_message_new_method_call
</refentrytitle>
16 <manvolnum>3</manvolnum>
20 <refname>sd_bus_message_new_method_call
</refname>
21 <refname>sd_bus_message_new_method_return
</refname>
23 <refpurpose>Create a method call message
</refpurpose>
28 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
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>
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>
49 <title>Description
</title>
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>
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>
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
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.
81 <title>Return Value
</title>
83 <para>This function returns
0 if the message object was successfully created, and a negative
84 errno-style error code otherwise.
</para>
87 <refsect1 id='errors'
>
90 <para>Returned errors may indicate the following problems:
</para>
94 <term><constant>-EINVAL
</constant></term>
96 <listitem><para>The output parameter
<parameter>m
</parameter> is
97 <constant>NULL
</constant>.
</para>
99 <para>The
<parameter>destination
</parameter> parameter is non-null and is not a valid D-Bus
100 service name (
<literal>org.somewhere.Something
</literal>), the
<parameter>path
</parameter>
101 parameter is not a valid D-Bus path (
<literal>/an/object/path
</literal>), the
102 <parameter>interface
</parameter> parameter is non-null and is not a valid D-Bus interface
103 name (
<literal>an.interface.name
</literal>), or the
<parameter>member
</parameter> parameter
104 is not a valid D-Bus member (
<literal>Name
</literal>).
</para>
106 <para>The
<parameter>call
</parameter> parameter is not a method call object.
</para>
111 <term><constant>-ENOTCONN
</constant></term>
113 <listitem><para>The bus parameter
<parameter>bus
</parameter> is
<constant>NULL
</constant> or
114 the bus is not connected.
</para></listitem>
118 <term><constant>-ENOMEM
</constant></term>
120 <listitem><para>Memory allocation failed.
</para></listitem>
124 <term><constant>-EPERM
</constant></term>
127 <para>The
<parameter>call
</parameter> parameter is not sealed.
</para>
132 <term><constant>-EOPNOTSUPP
</constant></term>
135 <para>The
<parameter>call
</parameter> message does not have a cookie.
</para>
141 <xi:include href=
"libsystemd-pkgconfig.xml" />
144 <title>Examples
</title>
147 <title>Make a call to a D-Bus method that takes a single parameter
</title>
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>
157 <title>See Also
</title>
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>