man/sd_bus_message_append_basic.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   Copyright © 2014 Zbigniew Jędrzejewski-Szmek
   9 -->
  10
  11 <refentry id="sd_bus_message_append_basic" xmlns:xi="http://www.w3.org/2001/XInclude">
  12
  13   <refentryinfo>
  14     <title>sd_bus_message_append_basic</title>
  15     <productname>systemd</productname>
  16   </refentryinfo>
  17
  18   <refmeta>
  19     <refentrytitle>sd_bus_message_append_basic</refentrytitle>
  20     <manvolnum>3</manvolnum>
  21   </refmeta>
  22
  23   <refnamediv>
  24     <refname>sd_bus_message_append_basic</refname>
  25
  26     <refpurpose>Attach a single field to a message</refpurpose>
  27   </refnamediv>
  28
  29   <refsynopsisdiv>
  30     <funcsynopsis>
  31       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  32
  33       <funcprototype>
  34         <funcdef>int sd_bus_message_append_basic</funcdef>
  35         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  36         <paramdef>char <parameter>type</parameter></paramdef>
  37         <paramdef>const void *<parameter>p</parameter></paramdef>
  38       </funcprototype>
  39     </funcsynopsis>
  40   </refsynopsisdiv>
  41
  42   <refsect1>
  43     <title>Description</title>
  44
  45     <para><function>sd_bus_message_append_basic()</function> appends a
  46     single field to the message <parameter>m</parameter>. The
  47     parameter <parameter>type</parameter> determines how the pointer
  48     <parameter>p</parameter> is interpreted.
  49     <parameter>type</parameter> must be one of the basic types as
  50     defined by the <ulink
  51     url="http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types">Basic
  52     Types</ulink> section of the D-Bus specification, and listed in
  53     the table below.
  54     </para>
  55
  56     <table id='format-specifiers'>
  57       <title>Item type specifiers</title>
  58
  59       <tgroup cols='5'>
  60         <colspec colname='specifier' />
  61         <colspec colname='constant' />
  62         <colspec colname='description' />
  63         <colspec colname='size' />
  64         <colspec colname='ctype' />
  65         <thead>
  66           <row>
  67             <entry>Specifier</entry>
  68             <entry>Constant</entry>
  69             <entry>Description</entry>
  70             <entry>Size</entry>
  71             <entry>Expected C Type</entry>
  72           </row>
  73         </thead>
  74         <tbody>
  75           <row>
  76             <entry><literal>y</literal></entry>
  77             <entry><constant>SD_BUS_TYPE_BYTE</constant></entry>
  78             <entry>unsigned integer</entry>
  79             <entry>1 byte</entry>
  80             <entry>uint8_t</entry>
  81           </row>
  82
  83           <row>
  84             <entry><literal>b</literal></entry>
  85             <entry><constant>SD_BUS_TYPE_BOOLEAN</constant></entry>
  86             <entry>boolean</entry>
  87             <entry>4 bytes</entry>
  88             <entry>int</entry>
  89           </row>
  90
  91           <row>
  92             <entry><literal>n</literal></entry>
  93             <entry><constant>SD_BUS_TYPE_INT16</constant></entry>
  94             <entry>signed integer</entry>
  95             <entry>2 bytes</entry>
  96             <entry>int16_t</entry>
  97           </row>
  98
  99           <row>
 100             <entry><literal>q</literal></entry>
 101             <entry><constant>SD_BUS_TYPE_UINT16</constant></entry>
 102             <entry>unsigned integer</entry>
 103             <entry>2 bytes</entry>
 104             <entry>uint16_t</entry>
 105           </row>
 106
 107           <row>
 108             <entry><literal>i</literal></entry>
 109             <entry><constant>SD_BUS_TYPE_INT32</constant></entry>
 110             <entry>signed integer</entry>
 111             <entry>4 bytes</entry>
 112             <entry>int32_t</entry>
 113           </row>
 114
 115           <row>
 116             <entry><literal>u</literal></entry>
 117             <entry><constant>SD_BUS_TYPE_UINT32</constant></entry>
 118             <entry>unsigned integer</entry>
 119             <entry>4 bytes</entry>
 120             <entry>uint32_t</entry>
 121           </row>
 122
 123           <row>
 124             <entry><literal>x</literal></entry>
 125             <entry><constant>SD_BUS_TYPE_INT64</constant></entry>
 126             <entry>signed integer</entry>
 127             <entry>8 bytes</entry>
 128             <entry>int64_t</entry>
 129           </row>
 130
 131           <row>
 132             <entry><literal>t</literal></entry>
 133             <entry><constant>SD_BUS_TYPE_UINT64</constant></entry>
 134             <entry>unsigned integer</entry>
 135             <entry>8 bytes</entry>
 136             <entry>uint64_t</entry>
 137           </row>
 138
 139           <row>
 140             <entry><literal>d</literal></entry>
 141             <entry><constant>SD_BUS_TYPE_DOUBLE</constant></entry>
 142             <entry>floating-point</entry>
 143             <entry>8 bytes</entry>
 144             <entry>double</entry>
 145           </row>
 146
 147           <row>
 148             <entry><literal>s</literal></entry>
 149             <entry><constant>SD_BUS_TYPE_STRING</constant></entry>
 150             <entry>Unicode string</entry>
 151             <entry>variable</entry>
 152             <entry>char[]</entry>
 153           </row>
 154
 155           <row>
 156             <entry><literal>o</literal></entry>
 157             <entry><constant>SD_BUS_TYPE_OBJECT_PATH</constant></entry>
 158             <entry>object path</entry>
 159             <entry>variable</entry>
 160             <entry>char[]</entry>
 161           </row>
 162
 163           <row>
 164             <entry><literal>g</literal></entry>
 165             <entry><constant>SD_BUS_TYPE_SIGNATURE</constant></entry>
 166             <entry>signature</entry>
 167             <entry>variable</entry>
 168             <entry>char[]</entry>
 169           </row>
 170
 171           <row>
 172             <entry><literal>h</literal></entry>
 173             <entry><constant>SD_BUS_TYPE_UNIX_FD</constant></entry>
 174             <entry>UNIX file descriptor</entry>
 175             <entry>4 bytes</entry>
 176             <entry>int</entry>
 177           </row>
 178        </tbody>
 179       </tgroup>
 180     </table>
 181
 182     <para>The value of the parameter is copied into a memory area held
 183     by the message object, stays in the possession of the caller and
 184     may hence be freely changed after this call without affecting the
 185     bus message it has been added to. If <parameter>type</parameter>
 186     is <literal>h</literal> (UNIX file descriptor), the descriptor is
 187     duplicated by this call and the passed descriptor stays in
 188     possession of the caller.</para>
 189
 190     <para>For types <literal>s</literal>, <literal>o</literal>, and
 191     <literal>g</literal>, the parameter <parameter>p</parameter> is
 192     interpreted as a pointer to a <constant>NUL</constant>-terminated
 193     character sequence. As a special case, a <constant>NULL</constant>
 194     pointer is interpreted as an empty string. The string should be
 195     valid Unicode string encoded as UTF-8. In case of the two latter
 196     types, the additional requirements for a D-Bus object path or
 197     type signature should be satisfied. Those requirements should be
 198     verified by the recipient of the message.
 199     </para>
 200   </refsect1>
 201
 202   <refsect1>
 203     <title>Return Value</title>
 204
 205     <para>On success, this call returns 0 or a positive integer. On
 206     failure, it returns a negative errno-style error code.</para>
 207   </refsect1>
 208
 209   <refsect1 id='errors'>
 210     <title>Errors</title>
 211
 212     <para>Returned errors may indicate the following problems:</para>
 213
 214     <variablelist>
 215
 216       <varlistentry>
 217         <term><constant>-EINVAL</constant></term>
 218
 219         <listitem><para>Specified parameter is invalid.
 220         </para></listitem>
 221       </varlistentry>
 222
 223       <varlistentry>
 224         <term><constant>-EPERM</constant></term>
 225
 226         <listitem><para>Message has been sealed.
 227         </para></listitem>
 228       </varlistentry>
 229
 230       <varlistentry>
 231         <term><constant>-ESTALE</constant></term>
 232
 233         <listitem><para>Message is in invalid state.
 234         </para></listitem>
 235       </varlistentry>
 236
 237       <varlistentry>
 238         <term><constant>-ENXIO</constant></term>
 239
 240         <listitem><para>Message cannot be appended to.
 241         </para></listitem>
 242       </varlistentry>
 243
 244       <varlistentry>
 245         <term><constant>-ENOMEM</constant></term>
 246
 247         <listitem><para>Memory allocation failed.</para></listitem>
 248       </varlistentry>
 249     </variablelist>
 250   </refsect1>
 251
 252   <xi:include href="libelogind-pkgconfig.xml" />
 253
 254   <refsect1>
 255     <title>See Also</title>
 256
 257     <para>
 258       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 259       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 260       <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 261       <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink>
 262     </para>
 263   </refsect1>
 264
 265 </refentry>