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