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