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