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-or-later --> 4 5<refentry id="sd_bus_message_set_destination" xmlns:xi="http://www.w3.org/2001/XInclude"> 6 <refentryinfo> 7 <title>sd_bus_message_set_destination</title> 8 <productname>systemd</productname> 9 </refentryinfo> 10 11 <refmeta> 12 <refentrytitle>sd_bus_message_set_destination</refentrytitle> 13 <manvolnum>3</manvolnum> 14 </refmeta> 15 16 <refnamediv> 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> 24 25 <refpurpose>Set and query bus message addressing information</refpurpose> 26 </refnamediv> 27 28 <refsynopsisdiv> 29 <funcsynopsis> 30 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> 31 32 <funcprototype> 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> 36 </funcprototype> 37 38 <funcprototype> 39 <funcdef>const char* <function>sd_bus_message_get_destination</function></funcdef> 40 <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> 41 </funcprototype> 42 43 <funcprototype> 44 <funcdef>const char* <function>sd_bus_message_get_path</function></funcdef> 45 <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> 46 </funcprototype> 47 48 <funcprototype> 49 <funcdef>const char* <function>sd_bus_message_get_interface</function></funcdef> 50 <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> 51 </funcprototype> 52 53 <funcprototype> 54 <funcdef>const char* <function>sd_bus_message_get_member</function></funcdef> 55 <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> 56 </funcprototype> 57 58 <funcprototype> 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> 62 </funcprototype> 63 64 <funcprototype> 65 <funcdef>const char* <function>sd_bus_message_get_sender</function></funcdef> 66 <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> 67 </funcprototype> 68 </funcsynopsis> 69 </refsynopsisdiv> 70 71 <refsect1> 72 <title>Description</title> 73 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 76 service name.</para> 77 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> and 86 <citerefentry><refentrytitle>sd_bus_message_set_destination</refentrytitle><manvolnum>3</manvolnum></citerefentry> 87 for more discussion of those values.</para> 88 89 <para><function>sd_bus_message_set_sender()</function> sets the sender service name for the specified bus message 90 object. The specified name must be a valid unique or well-known service name. This function is useful only for 91 messages to send on direct connections as for connections to bus brokers the broker will fill in the destination 92 field anyway, and the sender field set by original sender is ignored.</para> 93 94 <para><function>sd_bus_message_get_sender()</function> returns the sender field from 95 <parameter>message</parameter>.</para> 96 97 <para>When a string is returned, it is a pointer to internal storage, and may not be modified or 98 freed. It is only valid as long as the <parameter>message</parameter> remains referenced and 99 this field hasn't been changed by a different call.</para> 100 </refsect1> 101 102 <refsect1> 103 <title>Return Value</title> 104 105 <para>On success, these calls return 0 or a positive integer. On failure, these calls return a 106 negative errno-style error code.</para> 107 108 <refsect2> 109 <title>Errors</title> 110 111 <para>Returned errors may indicate the following problems:</para> 112 113 <variablelist> 114 <varlistentry> 115 <term><constant>-EINVAL</constant></term> 116 117 <listitem><para>The <parameter>message</parameter> parameter or the output parameter are 118 <constant>NULL</constant>.</para></listitem> 119 </varlistentry> 120 121 <varlistentry> 122 <term><constant>-EPERM</constant></term> 123 124 <listitem><para>For <function>sd_bus_message_set_destination()</function> and 125 <function>sd_bus_message_set_sender()</function>, the message is already sealed.</para> 126 </listitem> 127 </varlistentry> 128 129 <varlistentry> 130 <term><constant>-EEXIST</constant></term> 131 132 <listitem><para>The message already has a destination or sender field set.</para></listitem> 133 </varlistentry> 134 </variablelist> 135 </refsect2> 136 </refsect1> 137 138 <xi:include href="libsystemd-pkgconfig.xml" /> 139 140 <refsect1> 141 <title>See Also</title> 142 143 <para> 144 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 145 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 146 <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 147 <citerefentry><refentrytitle>sd_bus_set_sender</refentrytitle><manvolnum>3</manvolnum></citerefentry> 148 </para> 149 </refsect1> 150 151</refentry> 152