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