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 elogind.
   9
  10   Copyright 2017 Lennart Poettering
  11
  12   elogind is free software; you can redistribute it and/or modify it
  13   under the terms of the GNU Lesser General Public License as published by
  14   the Free Software Foundation; either version 2.1 of the License, or
  15   (at your option) any later version.
  16
  17   elogind is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public License
  23   along with elogind; If not, see <http://www.gnu.org/licenses/>.
  24 -->
  25
  26 <refentry id="sd_bus_set_sender">
  27
  28   <refentryinfo>
  29     <title>sd_bus_set_sender</title>
  30     <productname>elogind</productname>
  31
  32     <authorgroup>
  33       <author>
  34         <contrib>Developer</contrib>
  35         <firstname>Lennart</firstname>
  36         <surname>Poettering</surname>
  37         <email>lennart@poettering.net</email>
  38       </author>
  39     </authorgroup>
  40   </refentryinfo>
  41
  42   <refmeta>
  43     <refentrytitle>sd_bus_set_sender</refentrytitle>
  44     <manvolnum>3</manvolnum>
  45   </refmeta>
  46
  47   <refnamediv>
  48     <refname>sd_bus_set_sender</refname>
  49     <refname>sd_bus_get_sender</refname>
  50
  51     <refpurpose>Configure default sender for outgoing messages</refpurpose>
  52   </refnamediv>
  53
  54   <refsynopsisdiv>
  55     <funcsynopsis>
  56       <funcsynopsisinfo>#include &lt;elogind/sd-bus.h&gt;</funcsynopsisinfo>
  57
  58       <funcprototype>
  59         <funcdef>int <function>sd_bus_set_sender</function></funcdef>
  60         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  61         <paramdef>const char* <parameter>name</parameter></paramdef>
  62       </funcprototype>
  63
  64       <funcprototype>
  65         <funcdef>int <function>sd_bus_get_sender</function></funcdef>
  66         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  67         <paramdef>const char** <parameter>name</parameter></paramdef>
  68       </funcprototype>
  69
  70     </funcsynopsis>
  71   </refsynopsisdiv>
  72
  73   <refsect1>
  74     <title>Description</title>
  75
  76     <para><function>sd_bus_set_sender()</function> configures the default sender service name to use for outgoing
  77     messages. The service name specified in the <parameter>name</parameter> parameter is set on all outgoing messages
  78     that are sent on the connection and have no sender set yet, for example through
  79     <citerefentry><refentrytitle>sd_bus_message_set_sender</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Note
  80     that this function is only supported on direct connections, i.e. not on connections to a bus broker as the broker
  81     will fill in the sender service name automatically anyway. By default no sender name is configured, and hence
  82     messages are sent without sender field set. If the <parameter>name</parameter> parameter is specified as
  83     <constant>NULL</constant> the default sender service name is cleared, returning to the default state if a default
  84     sender service name was set before. If passed as non-<constant>NULL</constant> the specified name must be a valid
  85     unique or well-known service name.</para>
  86
  87     <para><function>sd_bus_get_sender()</function> may be used to query the current default service name for outgoing
  88     messages.</para>
  89   </refsect1>
  90
  91   <refsect1>
  92     <title>Return Value</title>
  93
  94     <para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style
  95     error code.</para>
  96   </refsect1>
  97
  98   <refsect1>
  99     <title>Errors</title>
 100
 101     <para>Returned errors may indicate the following problems:</para>
 102
 103     <variablelist>
 104       <varlistentry>
 105         <term><constant>-ECHILD</constant></term>
 106
 107         <listitem><para>The bus connection has been created in a different process.</para></listitem>
 108       </varlistentry>
 109
 110       <varlistentry>
 111         <term><constant>-EPERM</constant></term>
 112
 113         <listitem><para>The specified bus connection object is a not a direct but a brokered connection.</para></listitem>
 114       </varlistentry>
 115     </variablelist>
 116   </refsect1>
 117
 118   <refsect1>
 119     <title>Notes</title>
 120
 121     <para><function>sd_bus_set_sender()</function> and <function>sd_bus_get_sender()</function> are available as
 122     a shared library, which can be compiled and linked to with the <constant>libelogind</constant> <citerefentry
 123     project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para>
 124   </refsect1>
 125
 126   <refsect1>
 127     <title>See Also</title>
 128
 129     <para>
 130       <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 131       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 132       <citerefentry><refentrytitle>sd_bus_message_set_sender</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 133     </para>
 134   </refsect1>
 135
 136 </refentry>