man/sd_bus_message_append.xml

   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+ -->
   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 &lt;systemd/sd-bus.h&gt;</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 "s" and "g" (unicode string or signature), the pointer may be
 150     <constant>NULL</constant>, which is equivalent to an empty string. See
 151     <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 152     for the precise interpretation of those and other types.</para>
 153   </refsect1>
 154
 155   <refsect1>
 156     <title>Types String Grammar</title>
 157
 158     <programlisting>types ::= complete_type*
 159 complete_type ::= basic_type | variant | structure | array | dictionary
 160 basic_type ::= "y" | "n" | "q" | "u" | "i" | "x" | "t" | "d" |
 161                "b" | "h" |
 162                "s" | "o" | "g"
 163 variant ::= "v"
 164 structure ::= "(" complete_type+ ")"
 165 array ::= "a" complete_type
 166 dictionary ::= "a" "{" basic_type complete_type "}"
 167 </programlisting>
 168   </refsect1>
 169
 170   <refsect1>
 171     <title>Examples</title>
 172
 173     <para>Append a single basic type (the string <literal>a string</literal>):
 174     </para>
 175
 176     <programlisting>sd_bus_message *m;
 177 …
 178 sd_bus_message_append(m, "s", "a string");</programlisting>
 179
 180     <para>Append all types of integers:</para>
 181
 182     <programlisting>uint8_t y = 1;
 183 int16_t n = 2;
 184 uint16_t q = 3;
 185 int32_t i = 4;
 186 uint32_t u = 5;
 187 int32_t x = 6;
 188 uint32_t t = 7;
 189 double d = 8.0;
 190 sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d);</programlisting>
 191
 192      <para>Append a structure composed of a string and a D-Bus path:</para>
 193
 194      <programlisting>sd_bus_message_append(m, "(so)", "a string", "/a/path");
 195     </programlisting>
 196
 197      <para>Append an array of UNIX file descriptors:</para>
 198
 199      <programlisting>sd_bus_message_append(m, "ah", 3, STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO);
 200     </programlisting>
 201
 202      <para>Append a variant, with the real type "g" (signature),
 203      and value "sdbusisgood":</para>
 204
 205      <programlisting>sd_bus_message_append(m, "v", "g", "sdbusisgood");</programlisting>
 206
 207      <para>Append a dictionary containing the mapping {1=>"a", 2=>"b", 3=>""}:
 208      </para>
 209
 210      <programlisting>sd_bus_message_append(m, "a{is}", 3, 1, "a", 2, "b", 3, NULL);
 211      </programlisting>
 212   </refsect1>
 213
 214   <refsect1>
 215     <title>Return Value</title>
 216
 217     <para>On success, these functions return a non-negative integer. On failure, they return a
 218     negative errno-style error code.</para>
 219
 220     <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" />
 221   </refsect1>
 222
 223   <xi:include href="libsystemd-pkgconfig.xml" />
 224
 225   <refsect1>
 226     <title>See Also</title>
 227
 228     <para>
 229       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 230       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 231       <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 232       <citerefentry><refentrytitle>sd_bus_message_append_array</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 233       <citerefentry><refentrytitle>sd_bus_message_open_container</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 234     </para>
 235   </refsect1>
 236
 237 </refentry>