2018-07-26 21:00:36 +03:00
<?xml version='1.0'?>
2019-03-14 16:40:58 +03:00
< !DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
2023-12-25 17:48:33 +03:00
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
2020-11-09 07:23:58 +03:00
<!-- SPDX - License - Identifier: LGPL - 2.1 - or - later -->
2018-07-26 21:00:36 +03:00
<refentry id= "sd_bus_message_new_method_call"
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo >
<title > sd_bus_message_new_method_call</title>
<productname > systemd</productname>
</refentryinfo>
<refmeta >
<refentrytitle > sd_bus_message_new_method_call</refentrytitle>
<manvolnum > 3</manvolnum>
</refmeta>
<refnamediv >
<refname > sd_bus_message_new_method_call</refname>
2018-07-27 15:07:02 +03:00
<refname > sd_bus_message_new_method_return</refname>
2018-07-26 21:00:36 +03:00
<refpurpose > Create a method call message</refpurpose>
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcsynopsisinfo > #include < systemd/sd-bus.h> </funcsynopsisinfo>
<funcprototype >
2020-03-16 22:41:57 +03:00
<funcdef > int <function > sd_bus_message_new_method_call</function> </funcdef>
2018-07-26 21:00:36 +03:00
<paramdef > sd_bus *<parameter > bus</parameter> </paramdef>
<paramdef > sd_bus_message **<parameter > m</parameter> </paramdef>
<paramdef > const char *<parameter > destination</parameter> </paramdef>
<paramdef > const char *<parameter > path</parameter> </paramdef>
<paramdef > const char *<parameter > interface</parameter> </paramdef>
<paramdef > const char *<parameter > member</parameter> </paramdef>
</funcprototype>
2018-07-27 15:07:02 +03:00
<funcprototype >
2020-03-16 22:41:57 +03:00
<funcdef > int <function > sd_bus_message_new_method_return</function> </funcdef>
2018-07-27 15:07:02 +03:00
<paramdef > sd_bus_message *<parameter > call</parameter> </paramdef>
<paramdef > sd_bus_message **<parameter > m</parameter> </paramdef>
</funcprototype>
2018-07-26 21:00:36 +03:00
</funcsynopsis>
</refsynopsisdiv>
<refsect1 >
<title > Description</title>
<para > The <function > sd_bus_message_new_method_call()</function> function creates a new bus
message object that encapsulates a D-Bus method call, and returns it in the
<parameter > m</parameter> output parameter. The call will be made on the destination
<parameter > destination</parameter> , path <parameter > path</parameter> , on the interface
<parameter > interface</parameter> , member <parameter > member</parameter> .</para>
<para > Briefly, the <emphasis > destination</emphasis> is a dot-separated name that identifies a
service connected to the bus. The <emphasis > path</emphasis> is a slash-separated identifier of
an object within the destination that resembles a file system path. The meaning of this path is
defined by the destination. The <emphasis > interface</emphasis> is a dot-separated name that
resembles a Java interface name that identifies a group of methods and signals supported by the
object identified by path. Methods and signals are collectively called
<emphasis > members</emphasis> and are identified by a simple name composed of ASCII letters,
numbers, and underscores. See the <ulink
url="https://dbus.freedesktop.org/doc/dbus-tutorial.html#concepts">D-Bus Tutorial</ulink> for an
in-depth explanation.</para>
<para > The <parameter > destination</parameter> parameter may be <constant > NULL</constant> . The
<parameter > interface</parameter> parameter may be <constant > NULL</constant> , if the destination
has only a single member with the given name and there is no ambiguity if the interface name is
omitted.</para>
2018-07-27 15:07:02 +03:00
2020-03-16 22:41:57 +03:00
<para > Note that this is a low level interface. See
<citerefentry > <refentrytitle > sd_bus_call_method</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
for a more convenient way of calling D-Bus methods.</para>
<para > The <function > sd_bus_message_new_method_return()</function> function creates a new bus
2018-07-27 15:07:02 +03:00
message object that is a reply to the method call <parameter > call</parameter> and returns it in
the <parameter > m</parameter> output parameter. The <parameter > call</parameter> parameter must be
a method call message. The sender of <parameter > call</parameter> is used as the destination.
</para>
2018-07-26 21:00:36 +03:00
</refsect1>
<refsect1 >
<title > Return Value</title>
2020-03-17 23:52:30 +03:00
<para > On success, these functions return a non-negative integer. On failure, they return a
2020-03-16 22:41:57 +03:00
negative errno-style error code.</para>
2018-07-26 21:00:36 +03:00
2019-03-21 16:53:00 +03:00
<refsect2 id= 'errors' >
<title > Errors</title>
2018-07-26 21:00:36 +03:00
2019-03-21 16:53:00 +03:00
<para > Returned errors may indicate the following problems:</para>
2018-07-26 21:00:36 +03:00
2019-03-21 16:53:00 +03:00
<variablelist >
<varlistentry >
<term > <constant > -EINVAL</constant> </term>
2018-07-26 21:00:36 +03:00
2019-03-21 16:53:00 +03:00
<listitem > <para > The output parameter <parameter > m</parameter> is
<constant > NULL</constant> .</para>
2018-07-26 21:00:36 +03:00
2019-03-21 16:53:00 +03:00
<para > The <parameter > destination</parameter> parameter is non-null and is not a valid D-Bus
service name (<literal > org.somewhere.Something</literal> ), the <parameter > path</parameter>
parameter is not a valid D-Bus path (<literal > /an/object/path</literal> ), the
<parameter > interface</parameter> parameter is non-null and is not a valid D-Bus interface
name (<literal > an.interface.name</literal> ), or the <parameter > member</parameter> parameter
is not a valid D-Bus member (<literal > Name</literal> ).</para>
2018-07-27 15:07:02 +03:00
2019-03-21 16:53:00 +03:00
<para > The <parameter > call</parameter> parameter is not a method call object.</para>
</listitem>
</varlistentry>
2018-07-26 21:00:36 +03:00
2019-03-21 16:53:00 +03:00
<varlistentry >
<term > <constant > -ENOTCONN</constant> </term>
2018-07-26 21:00:36 +03:00
2019-03-21 16:53:00 +03:00
<listitem > <para > The bus parameter <parameter > bus</parameter> is <constant > NULL</constant> or
the bus is not connected.</para> </listitem>
</varlistentry>
2018-07-26 21:00:36 +03:00
2019-03-21 16:53:00 +03:00
<varlistentry >
<term > <constant > -ENOMEM</constant> </term>
2018-07-26 21:00:36 +03:00
2019-03-21 16:53:00 +03:00
<listitem > <para > Memory allocation failed.</para> </listitem>
</varlistentry>
2018-07-27 15:07:02 +03:00
2019-03-21 16:53:00 +03:00
<varlistentry >
<term > <constant > -EPERM</constant> </term>
2018-07-27 15:07:02 +03:00
2019-03-21 16:53:00 +03:00
<listitem >
<para > The <parameter > call</parameter> parameter is not sealed.</para>
</listitem>
</varlistentry>
2018-07-27 15:07:02 +03:00
2019-03-21 16:53:00 +03:00
<varlistentry >
<term > <constant > -EOPNOTSUPP</constant> </term>
2018-07-27 15:07:02 +03:00
2019-03-21 16:53:00 +03:00
<listitem >
<para > The <parameter > call</parameter> message does not have a cookie.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
2018-07-26 21:00:36 +03:00
</refsect1>
<xi:include href= "libsystemd-pkgconfig.xml" />
<refsect1 >
<title > Examples</title>
<example >
<title > Make a call to a D-Bus method that takes a single parameter</title>
<programlisting > <xi:include href= "print-unit-path.c" parse= "text" /> </programlisting>
<para > This defines a minimally useful program that will open a connection to the bus, create a
message object, send it, wait for the reply, and finally extract and print the answer. It does
error handling and proper memory management.</para>
</example>
</refsect1>
2023-09-04 15:46:35 +03:00
<refsect1 >
<title > History</title>
2023-09-18 19:44:26 +03:00
<para > <function > sd_bus_message_new_method_call()</function> and
<function > sd_bus_message_new_method_return()</function> were added in version 246.</para>
2023-09-04 15:46:35 +03:00
</refsect1>
2018-07-26 21:00:36 +03:00
<refsect1 >
<title > See Also</title>
2023-12-22 21:09:32 +03:00
<para > <simplelist type= "inline" >
<member > <citerefentry > <refentrytitle > systemd</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > sd-bus</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > sd_bus_call</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > sd_bus_call_method</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > sd_bus_path_encode</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> </member>
</simplelist> </para>
2018-07-26 21:00:36 +03:00
</refsect1>
</refentry>