man/sd_bus_message_set_destination.xml

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