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_priority
</refname>
23 <refname>sd_bus_message_get_priority
</refname>
24 <refname>sd_bus_message_set_sender
</refname>
25 <refname>sd_bus_message_get_sender
</refname>
27 <refpurpose>Set and query bus message addressing information
</refpurpose>
32 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
35 <funcdef>int
<function>sd_bus_message_set_destination
</function></funcdef>
36 <paramdef>sd_bus_message *
<parameter>message
</parameter></paramdef>
37 <paramdef>const char *
<parameter>destination
</parameter></paramdef>
41 <funcdef>const char*
<function>sd_bus_message_get_destination
</function></funcdef>
42 <paramdef>sd_bus_message *
<parameter>message
</parameter></paramdef>
46 <funcdef>const char*
<function>sd_bus_message_get_path
</function></funcdef>
47 <paramdef>sd_bus_message *
<parameter>message
</parameter></paramdef>
51 <funcdef>const char*
<function>sd_bus_message_get_interface
</function></funcdef>
52 <paramdef>sd_bus_message *
<parameter>message
</parameter></paramdef>
56 <funcdef>const char*
<function>sd_bus_message_get_member
</function></funcdef>
57 <paramdef>sd_bus_message *
<parameter>message
</parameter></paramdef>
61 <funcdef>int
<function>sd_bus_message_set_priority
</function></funcdef>
62 <paramdef>sd_bus_message *
<parameter>message
</parameter></paramdef>
63 <paramdef>int64_t
<parameter>priority
</parameter></paramdef>
67 <funcdef>int
<function>sd_bus_message_get_priority
</function></funcdef>
68 <paramdef>sd_bus_message *
<parameter>message
</parameter></paramdef>
69 <paramdef>int64_t *
<parameter>priority
</parameter></paramdef>
73 <funcdef>int
<function>sd_bus_message_set_sender
</function></funcdef>
74 <paramdef>sd_bus_message *
<parameter>message
</parameter></paramdef>
75 <paramdef>const char *
<parameter>sender
</parameter></paramdef>
79 <funcdef>const char*
<function>sd_bus_message_get_sender
</function></funcdef>
80 <paramdef>sd_bus_message *
<parameter>message
</parameter></paramdef>
86 <title>Description
</title>
88 <para><function>sd_bus_message_set_destination()
</function> sets the destination service name
89 for the specified bus message object. The specified name must be a valid unique or well-known
92 <para><function>sd_bus_message_get_destination()
</function>,
93 <function>sd_bus_message_get_path()
</function>,
94 <function>sd_bus_message_get_interface()
</function>, and
95 <function>sd_bus_message_get_member()
</function> return the destination, path, interface, and
96 member fields from
<parameter>message
</parameter> header. The return value will be
97 <constant>NULL
</constant> is
<parameter>message
</parameter> is
<constant>NULL
</constant> or the
98 message is of a type that doesn't use those fields or the message doesn't have them set. See
99 <citerefentry><refentrytitle>sd_bus_message_new_method_call
</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
100 <citerefentry><refentrytitle>sd_bus_message_set_destination
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
101 for more discussion of those values.
</para>
103 <para><function>sd_bus_message_set_priority()
</function> and
104 <function>sd_bus_message_get_priority()
</function> modify and query a message's priority
105 respectively. sd-bus currently doesn't make use of a message's priority.
</para>
107 <para><function>sd_bus_message_set_sender()
</function> sets the sender service name for the specified bus message
108 object. The specified name must be a valid unique or well-known service name. This function is useful only for
109 messages to send on direct connections as for connections to bus brokers the broker will fill in the destination
110 field anyway, and the sender field set by original sender is ignored.
</para>
112 <para><function>sd_bus_message_get_sender()
</function> returns the sender field from
113 <parameter>message
</parameter>.
</para>
115 <para>When a string is returned, it is a pointer to internal storage, and may not be modified or
116 freed. It is only valid as long as the
<parameter>message
</parameter> remains referenced and
117 this field hasn't been changed by a different call.
</para>
121 <title>Return Value
</title>
123 <para>On success, these calls return
0 or a positive integer. On failure, these calls return a
124 negative errno-style error code.
</para>
127 <title>Errors
</title>
129 <para>Returned errors may indicate the following problems:
</para>
133 <term><constant>-EINVAL
</constant></term>
135 <listitem><para>The
<parameter>message
</parameter> parameter or the output parameter are
136 <constant>NULL
</constant>.
</para></listitem>
140 <term><constant>-EPERM
</constant></term>
142 <listitem><para>For
<function>sd_bus_message_set_destination()
</function>,
143 <function>sd_bus_message_set_sender()
</function> and
144 <function>sd_bus_message_set_priority()
</function>, the message is already sealed.
</para>
149 <term><constant>-EEXIST
</constant></term>
151 <listitem><para>The message already has a destination or sender field set.
</para></listitem>
157 <xi:include href=
"libsystemd-pkgconfig.xml" />
160 <title>See Also
</title>
163 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
164 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
165 <citerefentry><refentrytitle>sd_bus_new
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
166 <citerefentry><refentrytitle>sd_bus_set_sender
</refentrytitle><manvolnum>3</manvolnum></citerefentry>