]>
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> | |
3df22bb5 | 22 | <refname>sd_bus_message_peek_type</refname> |
50972aac ZJS |
23 | |
24 | <refpurpose>Read a sequence of values from a message</refpurpose> | |
25 | </refnamediv> | |
26 | ||
27 | <refsynopsisdiv> | |
28 | <funcsynopsis> | |
29 | <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> | |
30 | ||
31 | <funcprototype> | |
32 | <funcdef>int <function>sd_bus_message_read</function></funcdef> | |
33 | <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> | |
9735c644 | 34 | <paramdef>const char *<parameter>types</parameter></paramdef> |
50972aac ZJS |
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> | |
9735c644 | 41 | <paramdef>const char *<parameter>types</parameter></paramdef> |
50972aac ZJS |
42 | <paramdef>va_list <parameter>ap</parameter></paramdef> |
43 | </funcprototype> | |
3df22bb5 DDM |
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> | |
50972aac ZJS |
50 | </funcsynopsis> |
51 | </refsynopsisdiv> | |
52 | ||
53 | <refsect1> | |
54 | <title>Description</title> | |
55 | ||
3df22bb5 DDM |
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> | |
50972aac ZJS |
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>, | |
3df22bb5 DDM |
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> | |
50972aac ZJS |
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> | |
979bdc47 | 107 | <entry><type>int</type>, which specifies the expected length <parameter>n</parameter> of the array</entry> |
50972aac ZJS |
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 | ||
3df22bb5 DDM |
147 | <para>If objects of the specified types are not present at the current position in the message, an error |
148 | is returned.</para> | |
50972aac ZJS |
149 | |
150 | <para>The <function>sd_bus_message_readv()</function> is equivalent to the | |
3df22bb5 DDM |
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> | |
50972aac ZJS |
163 | </refsect1> |
164 | ||
165 | <refsect1> | |
166 | <title>Return Value</title> | |
167 | ||
3df22bb5 DDM |
168 | <para>On success, these functions return a non-negative integer. On failure, they return a negative |
169 | errno-style error code.</para> | |
50972aac | 170 | |
b1de39de ZJS |
171 | <xi:include href="sd_bus_message_read_basic.xml" xpointer="errors" /> |
172 | </refsect1> | |
50972aac ZJS |
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", &x);</programlisting> | |
186 | ||
10c238b2 LP |
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", &x);</programlisting> | |
194 | ||
50972aac ZJS |
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", &y, &n, &q, &i, &u, &x, &t, &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)", &s, &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", &s, &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, &i, &s, &j, &t, &k, &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>, | |
58df2afb | 240 | <citerefentry><refentrytitle>sd_bus_message_skip</refentrytitle><manvolnum>3</manvolnum></citerefentry>, |
7cd40caa DDM |
241 | <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>, |
242 | <citerefentry><refentrytitle>sd_bus_message_enter_container</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
50972aac ZJS |
243 | </para> |
244 | </refsect1> | |
245 | ||
246 | </refentry> |