man/sd_bus_message_set_destination.xml

   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 &lt;systemd/sd-bus.h&gt;</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>History</title>
 142     <para><function>sd_bus_message_set_destination()</function> and
 143     <function>sd_bus_message_set_sender()</function> were added in version 237.</para>
 144     <para><function>sd_bus_message_get_destination()</function>,
 145     <function>sd_bus_message_get_path()</function>,
 146     <function>sd_bus_message_get_interface()</function>,
 147     <function>sd_bus_message_get_member()</function>, and
 148     <function>sd_bus_message_get_sender()</function> were added in version 240.</para>
 149   </refsect1>
 150
 151   <refsect1>
 152     <title>See Also</title>
 153
 154     <para>
 155       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 156       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 157       <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 158       <citerefentry><refentrytitle>sd_bus_set_sender</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 159     </para>
 160   </refsect1>
 161
 162 </refentry>