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 <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*
 161 complete_type ::= basic_type | variant | structure | array | dictionary
 162 basic_type ::= "y" | "n" | "q" | "u" | "i" | "x" | "t" | "d" |
 163                "b" | "h" |
 164                "s" | "o" | "g"
 165 variant ::= "v"
 166 structure ::= "(" complete_type+ ")"
 167 array ::= "a" complete_type
 168 dictionary ::= "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 …
 180 sd_bus_message_append(m, "s", "a string");</programlisting>
 181
 182     <para>Append all types of integers:</para>
 183
 184     <programlisting>uint8_t y = 1;
 185 int16_t n = 2;
 186 uint16_t q = 3;
 187 int32_t i = 4;
 188 uint32_t u = 5;
 189 int32_t x = 6;
 190 uint32_t t = 7;
 191 double d = 8.0;
 192 sd_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>