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   </refsect1>
 110
 111   <refsect1>
 112     <title>Errors</title>
 113
 114     <para>Returned errors may indicate the following problems:</para>
 115
 116     <variablelist>
 117       <varlistentry>
 118         <term><constant>-EINVAL</constant></term>
 119
 120         <listitem><para>The <parameter>message</parameter> parameter or the output parameter are
 121         <constant>NULL</constant>.</para></listitem>
 122       </varlistentry>
 123
 124       <varlistentry>
 125         <term><constant>-EPERM</constant></term>
 126
 127         <listitem><para>For <function>sd_bus_message_set_destination</function> or
 128         <function>sd_bus_message_set_sender</function>, the message is already
 129         sealed.</para></listitem>
 130       </varlistentry>
 131
 132       <varlistentry>
 133         <term><constant>-EEXIST</constant></term>
 134
 135         <listitem><para>The message already has a destination or sender field set.</para></listitem>
 136       </varlistentry>
 137     </variablelist>
 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>