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_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>
  26
  27     <refpurpose>Set and query bus message addressing information</refpurpose>
  28   </refnamediv>
  29
  30   <refsynopsisdiv>
  31     <funcsynopsis>
  32       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  33
  34       <funcprototype>
  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>
  38       </funcprototype>
  39
  40       <funcprototype>
  41         <funcdef>const char* <function>sd_bus_message_get_destination</function></funcdef>
  42         <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
  43       </funcprototype>
  44
  45       <funcprototype>
  46         <funcdef>const char* <function>sd_bus_message_get_path</function></funcdef>
  47         <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
  48       </funcprototype>
  49
  50       <funcprototype>
  51         <funcdef>const char* <function>sd_bus_message_get_interface</function></funcdef>
  52         <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
  53       </funcprototype>
  54
  55       <funcprototype>
  56         <funcdef>const char* <function>sd_bus_message_get_member</function></funcdef>
  57         <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
  58       </funcprototype>
  59
  60       <funcprototype>
  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>
  64       </funcprototype>
  65
  66       <funcprototype>
  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>
  70       </funcprototype>
  71
  72       <funcprototype>
  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>
  76       </funcprototype>
  77
  78       <funcprototype>
  79         <funcdef>const char* <function>sd_bus_message_get_sender</function></funcdef>
  80         <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
  81       </funcprototype>
  82     </funcsynopsis>
  83   </refsynopsisdiv>
  84
  85   <refsect1>
  86     <title>Description</title>
  87
  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
  90     service name.</para>
  91
  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>
 102
 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>
 106
 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>
 111
 112     <para><function>sd_bus_message_get_sender()</function> returns the sender field from
 113     <parameter>message</parameter>.</para>
 114
 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>
 118   </refsect1>
 119
 120   <refsect1>
 121     <title>Return Value</title>
 122
 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>
 125
 126     <refsect2>
 127       <title>Errors</title>
 128
 129       <para>Returned errors may indicate the following problems:</para>
 130
 131       <variablelist>
 132         <varlistentry>
 133           <term><constant>-EINVAL</constant></term>
 134
 135           <listitem><para>The <parameter>message</parameter> parameter or the output parameter are
 136           <constant>NULL</constant>.</para></listitem>
 137         </varlistentry>
 138
 139         <varlistentry>
 140           <term><constant>-EPERM</constant></term>
 141
 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>
 145           </listitem>
 146         </varlistentry>
 147
 148         <varlistentry>
 149           <term><constant>-EEXIST</constant></term>
 150
 151           <listitem><para>The message already has a destination or sender field set.</para></listitem>
 152         </varlistentry>
 153       </variablelist>
 154     </refsect2>
 155   </refsect1>
 156
 157   <xi:include href="libsystemd-pkgconfig.xml" />
 158
 159   <refsect1>
 160     <title>See Also</title>
 161
 162     <para>
 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>
 167     </para>
 168   </refsect1>
 169
 170 </refentry>