man/sd_bus_set_sender.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7
   8   This file is part of systemd.
   9
  10   Copyright 2017 Lennart Poettering
  11 -->
  12
  13 <refentry id="sd_bus_set_sender">
  14
  15   <refentryinfo>
  16     <title>sd_bus_set_sender</title>
  17     <productname>systemd</productname>
  18
  19     <authorgroup>
  20       <author>
  21         <contrib>Developer</contrib>
  22         <firstname>Lennart</firstname>
  23         <surname>Poettering</surname>
  24         <email>lennart@poettering.net</email>
  25       </author>
  26     </authorgroup>
  27   </refentryinfo>
  28
  29   <refmeta>
  30     <refentrytitle>sd_bus_set_sender</refentrytitle>
  31     <manvolnum>3</manvolnum>
  32   </refmeta>
  33
  34   <refnamediv>
  35     <refname>sd_bus_set_sender</refname>
  36     <refname>sd_bus_get_sender</refname>
  37
  38     <refpurpose>Configure default sender for outgoing messages</refpurpose>
  39   </refnamediv>
  40
  41   <refsynopsisdiv>
  42     <funcsynopsis>
  43       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  44
  45       <funcprototype>
  46         <funcdef>int <function>sd_bus_set_sender</function></funcdef>
  47         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  48         <paramdef>const char* <parameter>name</parameter></paramdef>
  49       </funcprototype>
  50
  51       <funcprototype>
  52         <funcdef>int <function>sd_bus_get_sender</function></funcdef>
  53         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  54         <paramdef>const char** <parameter>name</parameter></paramdef>
  55       </funcprototype>
  56
  57     </funcsynopsis>
  58   </refsynopsisdiv>
  59
  60   <refsect1>
  61     <title>Description</title>
  62
  63     <para><function>sd_bus_set_sender()</function> configures the default sender service name to use for outgoing
  64     messages. The service name specified in the <parameter>name</parameter> parameter is set on all outgoing messages
  65     that are sent on the connection and have no sender set yet, for example through
  66     <citerefentry><refentrytitle>sd_bus_message_set_sender</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Note
  67     that this function is only supported on direct connections, i.e. not on connections to a bus broker as the broker
  68     will fill in the sender service name automatically anyway. By default no sender name is configured, and hence
  69     messages are sent without sender field set. If the <parameter>name</parameter> parameter is specified as
  70     <constant>NULL</constant> the default sender service name is cleared, returning to the default state if a default
  71     sender service name was set before. If passed as non-<constant>NULL</constant> the specified name must be a valid
  72     unique or well-known service name.</para>
  73
  74     <para><function>sd_bus_get_sender()</function> may be used to query the current default service name for outgoing
  75     messages.</para>
  76   </refsect1>
  77
  78   <refsect1>
  79     <title>Return Value</title>
  80
  81     <para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style
  82     error code.</para>
  83   </refsect1>
  84
  85   <refsect1>
  86     <title>Errors</title>
  87
  88     <para>Returned errors may indicate the following problems:</para>
  89
  90     <variablelist>
  91       <varlistentry>
  92         <term><constant>-ECHILD</constant></term>
  93
  94         <listitem><para>The bus connection has been created in a different process.</para></listitem>
  95       </varlistentry>
  96
  97       <varlistentry>
  98         <term><constant>-EPERM</constant></term>
  99
 100         <listitem><para>The specified bus connection object is a not a direct but a brokered connection.</para></listitem>
 101       </varlistentry>
 102     </variablelist>
 103   </refsect1>
 104
 105   <refsect1>
 106     <title>Notes</title>
 107
 108     <para><function>sd_bus_set_sender()</function> and <function>sd_bus_get_sender()</function> are available as
 109     a shared library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry
 110     project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para>
 111   </refsect1>
 112
 113   <refsect1>
 114     <title>See Also</title>
 115
 116     <para>
 117       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 118       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 119       <citerefentry><refentrytitle>sd_bus_message_set_sender</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 120     </para>
 121   </refsect1>
 122
 123 </refentry>