1<?xml version='1.0'?> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="sd_bus_set_property" 7 xmlns:xi="http://www.w3.org/2001/XInclude"> 8 9 <refentryinfo> 10 <title>sd_bus_set_property</title> 11 <productname>systemd</productname> 12 </refentryinfo> 13 14 <refmeta> 15 <refentrytitle>sd_bus_set_property</refentrytitle> 16 <manvolnum>3</manvolnum> 17 </refmeta> 18 19 <refnamediv> 20 <refname>sd_bus_set_property</refname> 21 <refname>sd_bus_set_propertyv</refname> 22 <refname>sd_bus_get_property</refname> 23 <refname>sd_bus_get_property_trivial</refname> 24 <refname>sd_bus_get_property_string</refname> 25 <refname>sd_bus_get_property_strv</refname> 26 27 <refpurpose>Set or query D-Bus service properties</refpurpose> 28 </refnamediv> 29 30 <refsynopsisdiv> 31 <funcsynopsis> 32 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> 33 34 <funcprototype> 35 <funcdef>int <function>sd_bus_set_property</function></funcdef> 36 <paramdef>sd_bus *<parameter>bus</parameter></paramdef> 37 <paramdef>const char *<parameter>destination</parameter></paramdef> 38 <paramdef>const char *<parameter>path</parameter></paramdef> 39 <paramdef>const char *<parameter>interface</parameter></paramdef> 40 <paramdef>const char *<parameter>member</parameter></paramdef> 41 <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef> 42 <paramdef>const char *<parameter>type</parameter></paramdef> 43 <paramdef>...</paramdef> 44 </funcprototype> 45 46 <funcprototype> 47 <funcdef>int <function>sd_bus_set_propertyv</function></funcdef> 48 <paramdef>sd_bus *<parameter>bus</parameter></paramdef> 49 <paramdef>const char *<parameter>destination</parameter></paramdef> 50 <paramdef>const char *<parameter>path</parameter></paramdef> 51 <paramdef>const char *<parameter>interface</parameter></paramdef> 52 <paramdef>const char *<parameter>member</parameter></paramdef> 53 <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef> 54 <paramdef>const char *<parameter>type</parameter></paramdef> 55 <paramdef>va_list <parameter>ap</parameter></paramdef> 56 </funcprototype> 57 58 <funcprototype> 59 <funcdef>int <function>sd_bus_get_property</function></funcdef> 60 <paramdef>sd_bus *<parameter>bus</parameter></paramdef> 61 <paramdef>const char *<parameter>destination</parameter></paramdef> 62 <paramdef>const char *<parameter>path</parameter></paramdef> 63 <paramdef>const char *<parameter>interface</parameter></paramdef> 64 <paramdef>const char *<parameter>member</parameter></paramdef> 65 <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef> 66 <paramdef>sd_bus_message **<parameter>reply</parameter></paramdef> 67 <paramdef>const char *<parameter>type</parameter></paramdef> 68 </funcprototype> 69 70 <funcprototype> 71 <funcdef>int <function>sd_bus_get_property_trivial</function></funcdef> 72 <paramdef>sd_bus *<parameter>bus</parameter></paramdef> 73 <paramdef>const char *<parameter>destination</parameter></paramdef> 74 <paramdef>const char *<parameter>path</parameter></paramdef> 75 <paramdef>const char *<parameter>interface</parameter></paramdef> 76 <paramdef>const char *<parameter>member</parameter></paramdef> 77 <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef> 78 <paramdef>char <parameter>type</parameter></paramdef> 79 <paramdef>void *<parameter>ret_ptr</parameter></paramdef> 80 </funcprototype> 81 82 <funcprototype> 83 <funcdef>int <function>sd_bus_get_property_string</function></funcdef> 84 <paramdef>sd_bus *<parameter>bus</parameter></paramdef> 85 <paramdef>const char *<parameter>destination</parameter></paramdef> 86 <paramdef>const char *<parameter>path</parameter></paramdef> 87 <paramdef>const char *<parameter>interface</parameter></paramdef> 88 <paramdef>const char *<parameter>member</parameter></paramdef> 89 <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef> 90 <paramdef>char **<parameter>ret</parameter></paramdef> 91 </funcprototype> 92 93 <funcprototype> 94 <funcdef>int <function>sd_bus_get_property_strv</function></funcdef> 95 <paramdef>sd_bus *<parameter>bus</parameter></paramdef> 96 <paramdef>const char *<parameter>destination</parameter></paramdef> 97 <paramdef>const char *<parameter>path</parameter></paramdef> 98 <paramdef>const char *<parameter>interface</parameter></paramdef> 99 <paramdef>const char *<parameter>member</parameter></paramdef> 100 <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef> 101 <paramdef>char ***<parameter>ret</parameter></paramdef> 102 </funcprototype> 103 </funcsynopsis> 104 </refsynopsisdiv> 105 106 <refsect1> 107 <title>Description</title> 108 109 <para>These functions set or query D-Bus properties. D-Bus properties are service fields exposed 110 via the <constant>org.freedesktop.DBus.Properties</constant> interface. Under the hood, these 111 functions call methods of the <constant>org.freedesktop.DBus.Properties</constant> interface and 112 as a result their semantics are similar to 113 <citerefentry><refentrytitle>sd_bus_call_method</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 114 </para> 115 116 <para><function>sd_bus_set_property()</function> sets a D-Bus property. If setting the property 117 fails or an internal error occurs, an error is returned and an extended description of the error 118 is optionally stored in <parameter>ret_error</parameter> if it is not <constant>NULL</constant>. 119 <parameter>type</parameter> and the arguments that follow it describe the new value of the 120 property and must follow the format described in 121 <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 122 </para> 123 124 <para><function>sd_bus_set_propertyv()</function> is equivalent to 125 <function>sd_bus_set_property()</function>, except that it is called with a 126 <literal>va_list</literal> instead of a variable number of arguments.</para> 127 128 <para><function>sd_bus_get_property()</function> queries a D-Bus property. If retrieving the 129 property fails or an internal error occurs, an error is returned and an extended description of 130 the error is optionally stored in <parameter>ret_error</parameter> if it is not 131 <constant>NULL</constant>. On success, the property is stored in <parameter>reply</parameter>. 132 <parameter>type</parameter> describes the property type and must follow the format described in 133 <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 134 </para> 135 136 <para><function>sd_bus_get_property_trivial()</function>, 137 <function>sd_bus_get_property_string()</function> and 138 <function>sd_bus_get_property_strv()</function> are shorthands for 139 <function>sd_bus_get_property()</function> that are used to query basic, string and string 140 vector properties respectively. The caller is responsible for freeing the string and string 141 vector results stored in <parameter>ret</parameter> by 142 <function>sd_bus_get_property_string()</function> and 143 <function>sd_bus_get_property_strv()</function>.</para> 144 </refsect1> 145 146 <refsect1> 147 <title>Return Value</title> 148 149 <para>On success, these functions return a non-negative integer. On failure, they return a 150 negative errno-style error code.</para> 151 152 <refsect2 id='errors'> 153 <title>Errors</title> 154 155 <para>See the 156 <citerefentry><refentrytitle>sd_bus_call_method</refentrytitle><manvolnum>3</manvolnum></citerefentry> 157 man page for a list of possible errors.</para> 158 </refsect2> 159 </refsect1> 160 161 <xi:include href="libsystemd-pkgconfig.xml" /> 162 163 <refsect1> 164 <title>See Also</title> 165 166 <para> 167 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 168 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 169 <citerefentry><refentrytitle>sd_bus_call_method</refentrytitle><manvolnum>3</manvolnum></citerefentry> 170 </para> 171 </refsect1> 172 173</refentry> 174