man/sd_bus_message_read.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 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   5
   6 <refentry id="sd_bus_message_read"
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>sd_bus_message_read</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>sd_bus_message_read</refentrytitle>
  16     <manvolnum>3</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>sd_bus_message_read</refname>
  21     <refname>sd_bus_message_readv</refname>
  22     <refname>sd_bus_message_peek_type</refname>
  23
  24     <refpurpose>Read a sequence of values from a message</refpurpose>
  25   </refnamediv>
  26
  27   <refsynopsisdiv>
  28     <funcsynopsis>
  29       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  30
  31       <funcprototype>
  32         <funcdef>int <function>sd_bus_message_read</function></funcdef>
  33         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  34         <paramdef>const char *<parameter>types</parameter></paramdef>
  35         <paramdef>...</paramdef>
  36       </funcprototype>
  37
  38       <funcprototype>
  39         <funcdef>int <function>sd_bus_message_readv</function></funcdef>
  40         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  41         <paramdef>const char *<parameter>types</parameter></paramdef>
  42         <paramdef>va_list <parameter>ap</parameter></paramdef>
  43       </funcprototype>
  44
  45       <funcprototype>
  46         <funcdef>int <function>sd_bus_message_peek_type</function></funcdef>
  47         <paramdef>char *<parameter>type</parameter></paramdef>
  48         <paramdef>const char **<parameter>contents</parameter></paramdef>
  49       </funcprototype>
  50     </funcsynopsis>
  51   </refsynopsisdiv>
  52
  53   <refsect1>
  54     <title>Description</title>
  55
  56     <para><function>sd_bus_message_read()</function> reads a sequence of fields from the D-Bus message object
  57     <parameter>m</parameter> and advances the read position in the message. The type string
  58     <parameter>types</parameter> describes the types of items expected in the message and the field arguments
  59     that follow. The type string may be <constant>NULL</constant> or empty, in which case nothing is read.
  60     </para>
  61
  62     <para>The type string is composed of the elements described in
  63     <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  64     i.e. basic and container types. It must contain zero or more single "complete types". The type string is
  65     <constant>NUL</constant>-terminated.</para>
  66
  67     <para>For each type specified in the type string, one or more arguments need to be specified after the
  68     <parameter>types</parameter> parameter, in the same order. The arguments must be pointers to appropriate
  69     types (a pointer to <type>int8_t</type> for a <literal>y</literal> in the type string, a pointer to
  70     <type>int32_t</type> for an <literal>i</literal>, a pointer to <type>const char*</type> for an
  71     <literal>s</literal>, ...)  which are set based on the values in the message. As an exception, in case of
  72     array and variant types, the first argument is an "input" argument that further specifies how the message
  73     should be read. See the table below for a complete list of allowed arguments and their types. Note that,
  74     if the basic type is a pointer (e.g., <type>const char *</type> in the case of a string), the argument is
  75     a pointer to a pointer, and also the pointer value that is written is only borrowed and the contents must
  76     be copied if they are to be used after the end of the messages lifetime.</para>
  77
  78     <para>Each argument may also be <constant>NULL</constant>, in which case the value is read and ignored.
  79     </para>
  80
  81     <table>
  82       <title>Item type specifiers</title>
  83
  84       <tgroup cols='5'>
  85         <colspec colname='specifier' />
  86         <colspec colname='constant' />
  87         <colspec colname='description' />
  88         <colspec colname='type1' />
  89         <colspec colname='type2' />
  90         <thead>
  91           <row>
  92             <entry>Specifier</entry>
  93             <entry>Constant</entry>
  94             <entry>Description</entry>
  95             <entry>Type of the first argument</entry>
  96             <entry>Types of the subsequent arguments, if any</entry>
  97           </row>
  98         </thead>
  99
 100         <tbody>
 101           <xi:include href="sd_bus_message_read_basic.xml" xpointer="xpointer(//table[@id='format-specifiers']//tbody/*)" />
 102
 103           <row>
 104             <entry><literal>a</literal></entry>
 105             <entry><constant>SD_BUS_TYPE_ARRAY</constant></entry>
 106             <entry>array</entry>
 107             <entry><type>int</type>, which specifies the expected length <parameter>n</parameter> of the array</entry>
 108             <entry><parameter>n</parameter> sets of arguments appropriate for the array element type</entry>
 109           </row>
 110
 111           <row>
 112             <entry><literal>v</literal></entry>
 113             <entry><constant>SD_BUS_TYPE_VARIANT</constant></entry>
 114             <entry>variant</entry>
 115             <entry>signature string</entry>
 116             <entry>arguments appropriate for the types specified by the signature</entry>
 117           </row>
 118
 119           <row>
 120             <entry><literal>(</literal></entry>
 121             <entry><constant>SD_BUS_TYPE_STRUCT_BEGIN</constant></entry>
 122             <entry>array start</entry>
 123             <entry morerows="1" namest="type1" nameend="type2">arguments appropriate for the structure elements</entry>
 124           </row>
 125           <row>
 126             <entry><literal>)</literal></entry>
 127             <entry><constant>SD_BUS_TYPE_STRUCT_END</constant></entry>
 128             <entry>array end</entry>
 129           </row>
 130
 131           <row>
 132             <entry><literal>{</literal></entry>
 133             <entry><constant>SD_BUS_TYPE_DICT_ENTRY_BEGIN</constant></entry>
 134             <entry>dictionary entry start</entry>
 135             <entry morerows="1">arguments appropriate for the first type in the pair</entry>
 136             <entry morerows="1">arguments appropriate for the second type in the pair</entry>
 137             </row>
 138           <row>
 139             <entry><literal>}</literal></entry>
 140             <entry><constant>SD_BUS_TYPE_DICT_ENTRY_END</constant></entry>
 141             <entry>dictionary entry end</entry>
 142           </row>
 143        </tbody>
 144       </tgroup>
 145     </table>
 146
 147     <para>If objects of the specified types are not present at the current position in the message, an error
 148     is returned.</para>
 149
 150     <para>The <function>sd_bus_message_readv()</function> is equivalent to the
 151     <function>sd_bus_message_read()</function>, except that it is called with a <literal>va_list</literal>
 152     instead of a variable number of arguments. This function does not call the <function>va_end()</function>
 153     macro. Because it invokes the <function>va_arg()</function> macro, the value of <parameter>ap</parameter>
 154     is undefined after the call.</para>
 155
 156     <para><function>sd_bus_message_peek_type()</function> determines the type of the next element in
 157     <parameter>m</parameter> to be read by <function>sd_bus_message_read()</function> or similar functions.
 158     On success, the type is stored in <parameter>type</parameter>, if it is not <constant>NULL</constant>.
 159     If the type is a container type, the type of its elements is stored in <parameter>contents</parameter>,
 160     if it is not <constant>NULL</constant>. If this function successfully determines the type of the next
 161     element in <parameter>m</parameter>, it returns a positive integer. If there are no more elements to be
 162     read, it returns zero.</para>
 163   </refsect1>
 164
 165   <refsect1>
 166     <title>Return Value</title>
 167
 168     <para>On success, these functions return a non-negative integer. On failure, they return a negative
 169     errno-style error code.</para>
 170
 171     <xi:include href="sd_bus_message_read_basic.xml" xpointer="errors" />
 172   </refsect1>
 173
 174   <xi:include href="libsystemd-pkgconfig.xml" />
 175
 176   <refsect1>
 177     <title>Examples</title>
 178
 179     <para>Read a single basic type (a 64-bit integer):
 180     </para>
 181
 182     <programlisting>sd_bus_message *m;
 183 int64_t x;
 184
 185 sd_bus_message_read(m, "x", &amp;x);</programlisting>
 186
 187     <para>Read a boolean value:</para>
 188
 189     <programlisting>sd_bus_message *m;
 190 int x; /* Do not use C99 'bool' type here, it's typically smaller
 191           in memory and would cause memory corruption */
 192
 193 sd_bus_message_read(m, "b", &amp;x);</programlisting>
 194
 195     <para>Read all types of integers:</para>
 196
 197     <programlisting>uint8_t y;
 198 int16_t n;
 199 uint16_t q;
 200 int32_t i;
 201 uint32_t u;
 202 int32_t x;
 203 uint32_t t;
 204 double d;
 205
 206 sd_bus_message_read(m, "ynqiuxtd", &amp;y, &amp;n, &amp;q, &amp;i, &amp;u, &amp;x, &amp;t, &amp;d);</programlisting>
 207
 208      <para>Read a structure composed of a string and a D-Bus path:</para>
 209
 210      <programlisting>const char *s, *p;
 211
 212 sd_bus_message_read(m, "(so)", &amp;s, &amp;p);
 213 </programlisting>
 214
 215      <para>Read a variant, with the real type "gt" (signature, unsigned integer):
 216      </para>
 217
 218      <programlisting>const char *s;
 219 uint64_t *v;
 220
 221 sd_bus_message_read(m, "v", "gt", &amp;s, &amp;v);</programlisting>
 222
 223      <para>Read a dictionary containing three pairs of type {integer=>string}:
 224      </para>
 225
 226      <programlisting>int i, j, k;
 227 const char *s, *t, *u;
 228
 229 sd_bus_message_read(m, "a{is}", 3, &amp;i, &amp;s, &amp;j, &amp;t, &amp;k, &amp;u);
 230      </programlisting>
 231   </refsect1>
 232
 233   <refsect1>
 234     <title>See Also</title>
 235
 236     <para>
 237       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 238       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 239       <citerefentry><refentrytitle>sd_bus_message_read_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 240       <citerefentry><refentrytitle>sd_bus_message_skip</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 241       <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 242     </para>
 243   </refsect1>
 244
 245 </refentry>