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