man/sd_bus_message_read_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 © 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 <code>uint8_t *</code>. If <parameter>type</parameter> is
  59       <constant>'s'</constant>, the object passed in <parameter>p</parameter> should
  60       have type <code>const char **</code>. Note that, if the basic type is a pointer
  61       (e.g., <code>const char *</code> 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>unsigned integer</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>int *</entry>
  97           </row>
  98
  99           <row>
 100             <entry><literal>n</literal></entry>
 101             <entry><constant>SD_BUS_TYPE_INT16</constant></entry>
 102             <entry>signed integer</entry>
 103             <entry>int16_t *</entry>
 104           </row>
 105
 106           <row>
 107             <entry><literal>q</literal></entry>
 108             <entry><constant>SD_BUS_TYPE_UINT16</constant></entry>
 109             <entry>unsigned integer</entry>
 110             <entry>uint16_t *</entry>
 111           </row>
 112
 113           <row>
 114             <entry><literal>i</literal></entry>
 115             <entry><constant>SD_BUS_TYPE_INT32</constant></entry>
 116             <entry>signed integer</entry>
 117             <entry>int32_t *</entry>
 118           </row>
 119
 120           <row>
 121             <entry><literal>u</literal></entry>
 122             <entry><constant>SD_BUS_TYPE_UINT32</constant></entry>
 123             <entry>unsigned integer</entry>
 124             <entry>uint32_t *</entry>
 125           </row>
 126
 127           <row>
 128             <entry><literal>x</literal></entry>
 129             <entry><constant>SD_BUS_TYPE_INT64</constant></entry>
 130             <entry>signed integer</entry>
 131             <entry>int64_t *</entry>
 132           </row>
 133
 134           <row>
 135             <entry><literal>t</literal></entry>
 136             <entry><constant>SD_BUS_TYPE_UINT64</constant></entry>
 137             <entry>unsigned integer</entry>
 138             <entry>uint64_t *</entry>
 139           </row>
 140
 141           <row>
 142             <entry><literal>d</literal></entry>
 143             <entry><constant>SD_BUS_TYPE_DOUBLE</constant></entry>
 144             <entry>floating-point</entry>
 145             <entry>double *</entry>
 146           </row>
 147
 148           <row>
 149             <entry><literal>s</literal></entry>
 150             <entry><constant>SD_BUS_TYPE_STRING</constant></entry>
 151             <entry>Unicode string</entry>
 152             <entry>const 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>const char **</entry>
 160           </row>
 161
 162           <row>
 163             <entry><literal>g</literal></entry>
 164             <entry><constant>SD_BUS_TYPE_SIGNATURE</constant></entry>
 165             <entry>signature</entry>
 166             <entry>const char **</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>int *</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   </refsect1>
 194
 195   <refsect1 id='errors'>
 196     <title>Errors</title>
 197
 198     <para>Returned errors may indicate the following problems:</para>
 199
 200     <variablelist>
 201       <varlistentry>
 202         <term><constant>-EINVAL</constant></term>
 203
 204         <listitem><para>Specified type string is invalid or the message parameter is
 205         <constant>NULL</constant>.</para></listitem>
 206       </varlistentry>
 207
 208       <varlistentry>
 209         <term><constant>-ENXIO</constant></term>
 210
 211         <listitem><para>The message does not contain the specified type at current
 212         position.</para></listitem>
 213       </varlistentry>
 214
 215       <varlistentry>
 216         <term><constant>-EBADMSG</constant></term>
 217
 218         <listitem><para>The message cannot be parsed.</para></listitem>
 219       </varlistentry>
 220     </variablelist>
 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_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 231     </para>
 232   </refsect1>
 233
 234 </refentry>