1 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
2 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
5 <refentry id=
"sd_bus_message_set_destination" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
7 <title>sd_bus_message_set_destination
</title>
8 <productname>systemd
</productname>
12 <refentrytitle>sd_bus_message_set_destination
</refentrytitle>
13 <manvolnum>3</manvolnum>
17 <refname>sd_bus_message_set_destination
</refname>
18 <refname>sd_bus_message_get_destination
</refname>
19 <refname>sd_bus_message_get_path
</refname>
20 <refname>sd_bus_message_get_interface
</refname>
21 <refname>sd_bus_message_get_member
</refname>
22 <refname>sd_bus_message_set_sender
</refname>
23 <refname>sd_bus_message_get_sender
</refname>
25 <refpurpose>Set and query bus message addressing information
</refpurpose>
30 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
33 <funcdef>int
<function>sd_bus_message_set_destination
</function></funcdef>
34 <paramdef>sd_bus_message *
<parameter>message
</parameter></paramdef>
35 <paramdef>const char *
<parameter>destination
</parameter></paramdef>
39 <funcdef>const char*
<function>sd_bus_message_get_destination
</function></funcdef>
40 <paramdef>sd_bus_message *
<parameter>message
</parameter></paramdef>
44 <funcdef>const char*
<function>sd_bus_message_get_path
</function></funcdef>
45 <paramdef>sd_bus_message *
<parameter>message
</parameter></paramdef>
49 <funcdef>const char*
<function>sd_bus_message_get_interface
</function></funcdef>
50 <paramdef>sd_bus_message *
<parameter>message
</parameter></paramdef>
54 <funcdef>const char*
<function>sd_bus_message_get_member
</function></funcdef>
55 <paramdef>sd_bus_message *
<parameter>message
</parameter></paramdef>
59 <funcdef>int
<function>sd_bus_message_set_sender
</function></funcdef>
60 <paramdef>sd_bus_message *
<parameter>message
</parameter></paramdef>
61 <paramdef>const char *
<parameter>sender
</parameter></paramdef>
65 <funcdef>const char*
<function>sd_bus_message_get_sender
</function></funcdef>
66 <paramdef>sd_bus_message *
<parameter>message
</parameter></paramdef>
72 <title>Description
</title>
74 <para><function>sd_bus_message_set_destination()
</function> sets the destination service name
75 for the specified bus message object. The specified name must be a valid unique or well-known
78 <para><function>sd_bus_message_get_destination()
</function>,
79 <function>sd_bus_message_get_path()
</function>,
80 <function>sd_bus_message_get_interface()
</function>, and
81 <function>sd_bus_message_get_member()
</function> return the destination, path, interface, and
82 member fields from
<parameter>message
</parameter> header. The return value will be
83 <constant>NULL
</constant> is
<parameter>message
</parameter> is
<constant>NULL
</constant> or the
84 message is of a type that doesn't use those fields or the message doesn't have them set. See
85 <citerefentry><refentrytitle>sd_bus_message_new_method_call
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
87 <citerefentry><refentrytitle>sd_bus_message_set_destination
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
88 for more discussion of those values.
</para>
91 <para><function>sd_bus_message_set_sender()
</function> sets the sender service name for the specified bus message
92 object. The specified name must be a valid unique or well-known service name. This function is useful only for
93 messages to send on direct connections as for connections to bus brokers the broker will fill in the destination
94 field anyway, and the sender field set by original sender is ignored.
</para>
96 <para><function>sd_bus_message_get_sender()
</function> returns the sender field from
97 <parameter>message
</parameter>.
</para>
99 <para>When a string is returned, it is a pointer to internal storage, and may not be modified or
100 freed. It is only valid as long as the
<parameter>message
</parameter> remains referenced and
101 this field hasn't been changed by a different call.
</para>
105 <title>Return Value
</title>
107 <para>On success, these calls return
0 or a positive integer. On failure, these calls return a
108 negative errno-style error code.
</para>
111 <title>Errors
</title>
113 <para>Returned errors may indicate the following problems:
</para>
117 <term><constant>-EINVAL
</constant></term>
119 <listitem><para>The
<parameter>message
</parameter> parameter or the output parameter are
120 <constant>NULL
</constant>.
</para></listitem>
124 <term><constant>-EPERM
</constant></term>
126 <listitem><para>For
<function>sd_bus_message_set_destination
</function> or
127 <function>sd_bus_message_set_sender
</function>, the message is already
128 sealed.
</para></listitem>
132 <term><constant>-EEXIST
</constant></term>
134 <listitem><para>The message already has a destination or sender field set.
</para></listitem>
140 <xi:include href=
"libsystemd-pkgconfig.xml" />
143 <title>See Also
</title>
146 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
147 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
148 <citerefentry><refentrytitle>sd_bus_new
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
149 <citerefentry><refentrytitle>sd_bus_set_sender
</refentrytitle><manvolnum>3</manvolnum></citerefentry>