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+ -->
   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>
  86     and
  87     <citerefentry><refentrytitle>sd_bus_message_set_destination</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  88     for more discussion of those values.</para>
  89
  90
  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>
  95
  96     <para><function>sd_bus_message_get_sender()</function> returns the sender field from
  97     <parameter>message</parameter>.</para>
  98
  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>
 102   </refsect1>
 103
 104   <refsect1>
 105     <title>Return Value</title>
 106
 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>
 109
 110     <refsect2>
 111       <title>Errors</title>
 112
 113       <para>Returned errors may indicate the following problems:</para>
 114
 115       <variablelist>
 116         <varlistentry>
 117           <term><constant>-EINVAL</constant></term>
 118
 119           <listitem><para>The <parameter>message</parameter> parameter or the output parameter are
 120           <constant>NULL</constant>.</para></listitem>
 121         </varlistentry>
 122
 123         <varlistentry>
 124           <term><constant>-EPERM</constant></term>
 125
 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>
 129         </varlistentry>
 130
 131         <varlistentry>
 132           <term><constant>-EEXIST</constant></term>
 133
 134           <listitem><para>The message already has a destination or sender field set.</para></listitem>
 135         </varlistentry>
 136       </variablelist>
 137     </refsect2>
 138   </refsect1>
 139
 140   <xi:include href="libsystemd-pkgconfig.xml" />
 141
 142   <refsect1>
 143     <title>See Also</title>
 144
 145     <para>
 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>
 150     </para>
 151   </refsect1>
 152
 153 </refentry>