man/sd_bus_message_read_basic.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//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 © 2016 Julian Orth
   9 -->
  10
  11 <refentry id="sd_bus_message_read_basic">
  12
  13   <refentryinfo>
  14     <title>sd_bus_message_read_basic</title>
  15     <productname>systemd</productname>
  16   </refentryinfo>
  17
  18   <refmeta>
  19     <refentrytitle>sd_bus_message_read_basic</refentrytitle>
  20     <manvolnum>3</manvolnum>
  21   </refmeta>
  22
  23   <refnamediv>
  24     <refname>sd_bus_message_read_basic</refname>
  25
  26     <refpurpose>Read a basic type from 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 <function>sd_bus_message_read_basic</function></funcdef>
  35         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  36         <paramdef>char <parameter>type</parameter></paramdef>
  37         <paramdef>void *<parameter>p</parameter></paramdef>
  38       </funcprototype>
  39     </funcsynopsis>
  40   </refsynopsisdiv>
  41
  42   <refsect1>
  43     <title>Description</title>
  44
  45     <para>
  46       <function>sd_bus_message_read_basic()</function> reads a basic type from a
  47       message and advances the read position in the message. The set of basic
  48       types and their ascii codes passed in <parameter>type</parameter> are
  49       described in the <ulink
  50         url="https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus
  51         Specification</ulink>.
  52     </para>
  53
  54     <para>
  55       If <parameter>p</parameter> is not <constant>NULL</constant>, it should contain
  56       a pointer to an appropriate object. For example, if <parameter>type</parameter>
  57       is <constant>'y'</constant>, the object passed in <parameter>p</parameter>
  58       should have type <type>uint8_t *</type>. If <parameter>type</parameter> is
  59       <constant>'s'</constant>, the object passed in <parameter>p</parameter> should
  60       have type <type>const char **</type>. Note that, if the basic type is a pointer
  61       (e.g., <type>const char *</type> in the case of a string), the pointer is only
  62       borrowed and the contents must be copied if they are to be used after the end
  63       of the messages lifetime. Similarly, during the lifetime of such a pointer, the
  64       message must not be modified. See the table below for a complete list of allowed
  65       types.
  66     </para>
  67
  68     <table id='format-specifiers'>
  69       <title>Item type specifiers</title>
  70
  71       <tgroup cols='4'>
  72         <colspec colname='specifier' />
  73         <colspec colname='constant' />
  74         <colspec colname='description' />
  75         <colspec colname='ctype' />
  76         <thead>
  77           <row>
  78             <entry>Specifier</entry>
  79             <entry>Constant</entry>
  80             <entry>Description</entry>
  81             <entry>Expected C Type</entry>
  82           </row>
  83         </thead>
  84         <tbody>
  85           <row>
  86             <entry><literal>y</literal></entry>
  87             <entry><constant>SD_BUS_TYPE_BYTE</constant></entry>
  88             <entry>8bit unsigned integer</entry>
  89             <entry><type>uint8_t *</type></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><type>int *</type> (NB: not <type>bool *</type>)</entry>
  97           </row>
  98
  99           <row>
 100             <entry><literal>n</literal></entry>
 101             <entry><constant>SD_BUS_TYPE_INT16</constant></entry>
 102             <entry>16bit signed integer</entry>
 103             <entry><type>int16_t *</type></entry>
 104           </row>
 105
 106           <row>
 107             <entry><literal>q</literal></entry>
 108             <entry><constant>SD_BUS_TYPE_UINT16</constant></entry>
 109             <entry>16bit unsigned integer</entry>
 110             <entry><type>uint16_t *</type></entry>
 111           </row>
 112
 113           <row>
 114             <entry><literal>i</literal></entry>
 115             <entry><constant>SD_BUS_TYPE_INT32</constant></entry>
 116             <entry>32bit signed integer</entry>
 117             <entry><type>int32_t *</type></entry>
 118           </row>
 119
 120           <row>
 121             <entry><literal>u</literal></entry>
 122             <entry><constant>SD_BUS_TYPE_UINT32</constant></entry>
 123             <entry>32bit unsigned integer</entry>
 124             <entry><type>uint32_t *</type></entry>
 125           </row>
 126
 127           <row>
 128             <entry><literal>x</literal></entry>
 129             <entry><constant>SD_BUS_TYPE_INT64</constant></entry>
 130             <entry>64bit signed integer</entry>
 131             <entry><type>int64_t *</type></entry>
 132           </row>
 133
 134           <row>
 135             <entry><literal>t</literal></entry>
 136             <entry><constant>SD_BUS_TYPE_UINT64</constant></entry>
 137             <entry>64bit unsigned integer</entry>
 138             <entry><type>uint64_t *</type></entry>
 139           </row>
 140
 141           <row>
 142             <entry><literal>d</literal></entry>
 143             <entry><constant>SD_BUS_TYPE_DOUBLE</constant></entry>
 144             <entry>IEEE 754 double precision floating-point</entry>
 145             <entry><type>double *</type></entry>
 146           </row>
 147
 148           <row>
 149             <entry><literal>s</literal></entry>
 150             <entry><constant>SD_BUS_TYPE_STRING</constant></entry>
 151             <entry>UTF-8 string</entry>
 152             <entry><type>const char **</type></entry>
 153           </row>
 154
 155           <row>
 156             <entry><literal>o</literal></entry>
 157             <entry><constant>SD_BUS_TYPE_OBJECT_PATH</constant></entry>
 158             <entry>D-Bus object path string</entry>
 159             <entry><type>const char **</type></entry>
 160           </row>
 161
 162           <row>
 163             <entry><literal>g</literal></entry>
 164             <entry><constant>SD_BUS_TYPE_SIGNATURE</constant></entry>
 165             <entry>D-Bus signature string</entry>
 166             <entry><type>const char **</type></entry>
 167           </row>
 168
 169           <row>
 170             <entry><literal>h</literal></entry>
 171             <entry><constant>SD_BUS_TYPE_UNIX_FD</constant></entry>
 172             <entry>UNIX file descriptor</entry>
 173             <entry><type>int *</type></entry>
 174           </row>
 175        </tbody>
 176       </tgroup>
 177     </table>
 178
 179     <para>
 180       If there is no object of the specified type at the current position in the
 181       message, an error is returned.
 182     </para>
 183   </refsect1>
 184
 185   <refsect1>
 186     <title>Return Value</title>
 187
 188     <para>
 189       On success, <function>sd_bus_message_read_basic()</function> returns 0 or
 190       a positive integer. On failure, it returns a negative errno-style error
 191       code.
 192     </para>
 193
 194     <refsect2 id='errors'>
 195       <title>Errors</title>
 196
 197       <para>Returned errors may indicate the following problems:</para>
 198
 199       <variablelist>
 200         <varlistentry>
 201           <term><constant>-EINVAL</constant></term>
 202
 203           <listitem><para>Specified type string is invalid or the message parameter is
 204           <constant>NULL</constant>.</para></listitem>
 205         </varlistentry>
 206
 207         <varlistentry>
 208           <term><constant>-ENXIO</constant></term>
 209
 210           <listitem><para>The message does not contain the specified type at current position.
 211           </para></listitem>
 212         </varlistentry>
 213
 214         <varlistentry>
 215           <term><constant>-EBADMSG</constant></term>
 216
 217           <listitem><para>The message cannot be parsed.</para></listitem>
 218         </varlistentry>
 219       </variablelist>
 220     </refsect2>
 221   </refsect1>
 222
 223   <refsect1>
 224     <title>See Also</title>
 225
 226     <para>
 227       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 228       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 229       <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 230       <citerefentry><refentrytitle>sd_bus_message_skip</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 231       <citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 232     </para>
 233   </refsect1>
 234
 235 </refentry>