1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<refentry id="sd_bus_message_open_container"
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_bus_message_open_container</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>sd_bus_message_open_container</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_bus_message_open_container</refname>
<refname>sd_bus_message_close_container</refname>
<refname>sd_bus_message_enter_container</refname>
<refname>sd_bus_message_exit_container</refname>
<refpurpose>Create and move between containers in D-Bus messages</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
<funcprototype>
<funcdef>int sd_bus_message_open_container</funcdef>
<paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
<paramdef>char <parameter>type</parameter></paramdef>
<paramdef>const char *<parameter>contents</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int sd_bus_message_close_container</funcdef>
<paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int sd_bus_message_enter_container</funcdef>
<paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
<paramdef>char <parameter>type</parameter></paramdef>
<paramdef>const char *<parameter>contents</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int sd_bus_message_exit_container</funcdef>
<paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_bus_message_open_container()</function> appends a new container to the message
<parameter>m</parameter>. After opening a new container, it can be filled with content using
<citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>
and similar functions. Containers behave like a stack. To nest containers inside each other, call
<function>sd_bus_message_open_container()</function> multiple times without calling
<function>sd_bus_message_close_container()</function> in between. Each container will be nested inside the
previous container. <parameter>type</parameter> represents the container type and should be one of
<literal>r</literal>, <literal>a</literal>, <literal>v</literal> or <literal>e</literal> as described in
<citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
Instead of literals, the corresponding constants <constant>SD_BUS_TYPE_STRUCT</constant>,
<constant>SD_BUS_TYPE_ARRAY</constant>, <constant>SD_BUS_TYPE_VARIANT</constant> or
<constant>SD_BUS_TYPE_DICT_ENTRY</constant> can also be used. <parameter>contents</parameter> describes
the type of the container's elements and should be a D-Bus type string following the rules described in
<citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
<para><function>sd_bus_message_close_container()</function> closes the last container opened with
<function>sd_bus_message_open_container()</function>. On success, the write pointer of the message
<parameter>m</parameter> is positioned after the closed container in its parent container or in
<parameter>m</parameter> itself if there is no parent container.</para>
<para><function>sd_bus_message_enter_container()</function> enters the next container of the message
<parameter>m</parameter> for reading. It behaves mostly the same as
<function>sd_bus_message_open_container()</function>. Entering a container allows reading its contents
with
<citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>
and similar functions. <parameter>type</parameter> and <parameter>contents</parameter> are the same as in
<function>sd_bus_message_open_container()</function>.</para>
<para><function>sd_bus_message_exit_container()</function> exits the scope of the last container entered
with <function>sd_bus_message_enter_container()</function>. It behaves mostly the same as
<function>sd_bus_message_close_container()</function>. Note that
<function>sd_bus_message_exit_container()</function> may only be called after iterating through all
members of the container, i.e. reading or skipping over them. Use
<citerefentry><refentrytitle>sd_bus_message_skip</refentrytitle><manvolnum>3</manvolnum></citerefentry>
to skip over fields of a container in order to be able to exit the container with
<function>sd_bus_message_exit_container()</function> without reading all members.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, these functions return a non-negative integer.
<function>sd_bus_message_open_container()</function> and <function>sd_bus_message_close_container()</function>
return 0.
<function>sd_bus_message_enter_container()</function> returns 1 if it successfully opened a new container, and 0 if
that was not possible because the end of the currently open container or message was reached.
<function>sd_bus_message_exit_container()</function> returns 1 on success.
On failure, all of these functions return a negative errno-style error code.</para>
<refsect2>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para><parameter>m</parameter> or <parameter>contents</parameter> are
<constant>NULL</constant> or <parameter>type</parameter> is invalid.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-EBADMSG</constant></term>
<listitem><para>Message <parameter>m</parameter> has invalid structure.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENXIO</constant></term>
<listitem><para>Message <parameter>m</parameter> does not have a container of type
<parameter>type</parameter> at the current position, or the contents do not match
<parameter>contents</parameter>.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-EPERM</constant></term>
<listitem><para>The message <parameter>m</parameter> is already sealed.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ESTALE</constant></term>
<listitem><para>The message <parameter>m</parameter> is in an invalid state.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENOMEM</constant></term>
<listitem><para>Memory allocation failed.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-EBUSY</constant></term>
<listitem><para><function>sd_bus_message_exit_container()</function> was called but there are
unread members left in the container.</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>Examples</title>
<example>
<title>Append an array of strings to a message</title>
<programlisting><xi:include href="sd-bus-container-append.c" parse="text" /></programlisting>
</example>
<example>
<title>Read an array of strings from a message</title>
<programlisting><xi:include href="sd-bus-container-read.c" parse="text" /></programlisting>
</example>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_message_skip</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<ulink url="https://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink>
</para>
</refsect1>
</refentry>
|
