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_message_append" 7 xmlns:xi="http://www.w3.org/2001/XInclude"> 8 9 <refentryinfo> 10 <title>sd_bus_message_append</title> 11 <productname>systemd</productname> 12 </refentryinfo> 13 14 <refmeta> 15 <refentrytitle>sd_bus_message_append</refentrytitle> 16 <manvolnum>3</manvolnum> 17 </refmeta> 18 19 <refnamediv> 20 <refname>sd_bus_message_append</refname> 21 <refname>sd_bus_message_appendv</refname> 22 23 <refpurpose>Attach fields to a D-Bus message based on a type string</refpurpose> 24 </refnamediv> 25 26 <refsynopsisdiv> 27 <funcsynopsis> 28 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> 29 30 <funcprototype> 31 <funcdef>int sd_bus_message_append</funcdef> 32 <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> 33 <paramdef>const char *<parameter>types</parameter></paramdef> 34 <paramdef>…</paramdef> 35 </funcprototype> 36 37 <funcprototype> 38 <funcdef>int sd_bus_message_appendv</funcdef> 39 <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> 40 <paramdef>const char *<parameter>types</parameter></paramdef> 41 <paramdef>va_list <parameter>ap</parameter></paramdef> 42 </funcprototype> 43 44 </funcsynopsis> 45 </refsynopsisdiv> 46 47 <refsect1> 48 <title>Description</title> 49 50 <para>The <function>sd_bus_message_append()</function> function appends a sequence of fields to 51 the D-Bus message object <parameter>m</parameter>. The type string <parameter>types</parameter> 52 describes the types of the field arguments that follow. For each type specified in the type 53 string, one or more arguments need to be specified, in the same order as declared in the type 54 string.</para> 55 56 <para>The type string is composed of the elements shown in the table below. It contains zero or 57 more single "complete types". Each complete type may be one of the basic types or a fully 58 described container type. A container type may be a structure with the contained types, a 59 variant, an array with its element type, or a dictionary entry with the contained types. The 60 type string is <constant>NUL</constant>-terminated.</para> 61 62 <para>In case of a basic type, one argument of the corresponding type is expected.</para> 63 64 <para>A structure is denoted by a sequence of complete types between <literal>(</literal> and 65 <literal>)</literal>. This sequence cannot be empty — it must contain at least one type. 66 Arguments corresponding to this nested sequence follow the same rules as if they were not 67 nested.</para> 68 69 <para>A variant is denoted by <literal>v</literal>. Corresponding arguments must begin with a 70 type string denoting a complete type, and following that, arguments corresponding to the 71 specified type.</para> 72 73 <para>An array is denoted by <literal>a</literal> followed by a complete type. Corresponding 74 arguments must begin with the number of entries in the array, followed by the entries 75 themselves, matching the element type of the array.</para> 76 77 <para>A dictionary is an array of dictionary entries, denoted by <literal>a</literal> followed 78 by a pair of complete types between <literal>{</literal> and <literal>}</literal>. The first of 79 those types must be a basic type. Corresponding arguments must begin with the number of 80 dictionary entries, followed by a pair of values for each entry matching the element type of the 81 dictionary entries.</para> 82 83 <para><function>sd_bus_message_appendv()</function> is equivalent to 84 <function>sd_bus_message_append()</function>, except that it is called with a 85 <literal>va_list</literal> instead of a variable number of arguments. This function does not 86 call the <function>va_end()</function> macro. Because it invokes the 87 <function>va_arg()</function> macro, the value of <parameter>ap</parameter> is undefined after 88 the call.</para> 89 90 <para>For further details on the D-Bus type system, please consult the 91 <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#type-system">D-Bus Specification</ulink>. 92 </para> 93 94 <table> 95 <title>Item type specifiers</title> 96 97 <tgroup cols='5'> 98 <xi:include href="sd_bus_message_append_basic.xml" xpointer="xpointer(//table[@id='format-specifiers'])//colspec" /> 99 <xi:include href="sd_bus_message_append_basic.xml" xpointer="xpointer(//table[@id='format-specifiers']//thead)" /> 100 101 <tbody> 102 <xi:include href="sd_bus_message_append_basic.xml" xpointer="xpointer(//table[@id='format-specifiers']//tbody/*)" /> 103 104 <row> 105 <entry><literal>a</literal></entry> 106 <entry><constant>SD_BUS_TYPE_ARRAY</constant></entry> 107 <entry>array</entry> 108 <entry>determined by array type and size</entry> 109 <entry>int, followed by array contents</entry> 110 </row> 111 112 <row> 113 <entry><literal>v</literal></entry> 114 <entry><constant>SD_BUS_TYPE_VARIANT</constant></entry> 115 <entry>variant</entry> 116 <entry>determined by the type argument</entry> 117 <entry>signature string, followed by variant contents</entry> 118 </row> 119 120 <row> 121 <entry><literal>(</literal></entry> 122 <entry><constant>SD_BUS_TYPE_STRUCT_BEGIN</constant></entry> 123 <entry>array start</entry> 124 <entry morerows="1">determined by the nested types</entry> 125 <entry morerows="1">structure contents</entry> 126 </row> 127 <row> 128 <entry><literal>)</literal></entry> 129 <entry><constant>SD_BUS_TYPE_STRUCT_END</constant></entry> 130 <entry>array end</entry> 131 </row> 132 133 <row> 134 <entry><literal>{</literal></entry> 135 <entry><constant>SD_BUS_TYPE_DICT_ENTRY_BEGIN</constant></entry> 136 <entry>dictionary entry start</entry> 137 <entry morerows="1">determined by the nested types</entry> 138 <entry morerows="1">dictionary contents</entry> 139 </row> 140 <row> 141 <entry><literal>}</literal></entry> 142 <entry><constant>SD_BUS_TYPE_DICT_ENTRY_END</constant></entry> 143 <entry>dictionary entry end</entry> 144 </row> 145 </tbody> 146 </tgroup> 147 </table> 148 149 <para>For types <literal>s</literal> and <literal>g</literal> (unicode string or signature), the pointer 150 may be <constant>NULL</constant>, which is equivalent to an empty string. For <literal>h</literal> (UNIX 151 file descriptor), the descriptor is duplicated by this call and the passed descriptor stays in possession 152 of the caller. See 153 <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry> 154 for the precise interpretation of those and other types.</para> 155 </refsect1> 156 157 <refsect1> 158 <title>Types String Grammar</title> 159 160 <programlisting>types ::= complete_type* 161complete_type ::= basic_type | variant | structure | array | dictionary 162basic_type ::= "y" | "n" | "q" | "u" | "i" | "x" | "t" | "d" | 163 "b" | "h" | 164 "s" | "o" | "g" 165variant ::= "v" 166structure ::= "(" complete_type+ ")" 167array ::= "a" complete_type 168dictionary ::= "a" "{" basic_type complete_type "}" 169</programlisting> 170 </refsect1> 171 172 <refsect1> 173 <title>Examples</title> 174 175 <para>Append a single basic type (the string <literal>a string</literal>): 176 </para> 177 178 <programlisting>sd_bus_message *m; 179… 180sd_bus_message_append(m, "s", "a string");</programlisting> 181 182 <para>Append all types of integers:</para> 183 184 <programlisting>uint8_t y = 1; 185int16_t n = 2; 186uint16_t q = 3; 187int32_t i = 4; 188uint32_t u = 5; 189int32_t x = 6; 190uint32_t t = 7; 191double d = 8.0; 192sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d);</programlisting> 193 194 <para>Append a structure composed of a string and a D-Bus path:</para> 195 196 <programlisting>sd_bus_message_append(m, "(so)", "a string", "/a/path"); 197 </programlisting> 198 199 <para>Append an array of UNIX file descriptors:</para> 200 201 <programlisting>sd_bus_message_append(m, "ah", 3, STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO); 202 </programlisting> 203 204 <para>Append a variant, with the real type "g" (signature), 205 and value "sdbusisgood":</para> 206 207 <programlisting>sd_bus_message_append(m, "v", "g", "sdbusisgood");</programlisting> 208 209 <para>Append a dictionary containing the mapping {1=>"a", 2=>"b", 3=>""}: 210 </para> 211 212 <programlisting>sd_bus_message_append(m, "a{is}", 3, 1, "a", 2, "b", 3, NULL); 213 </programlisting> 214 </refsect1> 215 216 <refsect1> 217 <title>Return Value</title> 218 219 <para>On success, these functions return a non-negative integer. On failure, they return a 220 negative errno-style error code.</para> 221 222 <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" /> 223 </refsect1> 224 225 <xi:include href="libsystemd-pkgconfig.xml" /> 226 227 <refsect1> 228 <title>See Also</title> 229 230 <para> 231 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 232 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 233 <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 234 <citerefentry><refentrytitle>sd_bus_message_append_array</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 235 <citerefentry><refentrytitle>sd_bus_message_open_container</refentrytitle><manvolnum>3</manvolnum></citerefentry> 236 </para> 237 </refsect1> 238 239</refentry> 240