sd_bus_message_enter_container(3)

1SD_BUS_MESSAGE_OPEN_CONTAIsNdE_Rb(u3s)_message_open_coSnDt_aBiUnSe_rMESSAGE_OPEN_CONTAINER(3)
2
3
4

NAME

6       sd_bus_message_open_container, sd_bus_message_close_container,
7       sd_bus_message_enter_container, sd_bus_message_exit_container - Create
8       and move between containers in D-Bus messages
9

SYNOPSIS

11       #include <systemd/sd-bus.h>
12
13       int sd_bus_message_open_container(sd_bus_message *m, char type,
14                                         const char *contents);
15
16       int sd_bus_message_close_container(sd_bus_message *m);
17
18       int sd_bus_message_enter_container(sd_bus_message *m, char type,
19                                          const char *contents);
20
21       int sd_bus_message_exit_container(sd_bus_message *m);
22

DESCRIPTION

24       sd_bus_message_open_container() appends a new container to the message
25       m. After opening a new container, it can be filled with content using
26       sd_bus_message_append(3) and similar functions. Containers behave like
27       a stack. To nest containers inside each other, call
28       sd_bus_message_open_container() multiple times without calling
29       sd_bus_message_close_container() in between. Each container will be
30       nested inside the previous container.  type represents the container
31       type and should be one of "r", "a", "v" or "e" as described in
32       sd_bus_message_append(3). Instead of literals, the corresponding
33       constants SD_BUS_TYPE_STRUCT, SD_BUS_TYPE_ARRAY, SD_BUS_TYPE_VARIANT or
34       SD_BUS_TYPE_DICT_ENTRY can also be used.  contents describes the type
35       of the container's elements and should be a D-Bus type string following
36       the rules described in sd_bus_message_append(3).
37
38       sd_bus_message_close_container() closes the last container opened with
39       sd_bus_message_open_container(). On success, the write pointer of the
40       message m is positioned after the closed container in its parent
41       container or in m itself if there is no parent container.
42
43       sd_bus_message_enter_container() enters the next container of the
44       message m for reading. It behaves mostly the same as
45       sd_bus_message_open_container(). Entering a container allows reading
46       its contents with sd_bus_message_read(3) and similar functions.  type
47       and contents are the same as in sd_bus_message_open_container().
48
49       sd_bus_message_exit_container() exits the scope of the last container
50       entered with sd_bus_message_enter_container(). It behaves mostly the
51       same as sd_bus_message_close_container(). Note that
52       sd_bus_message_exit_container() may only be called after iterating
53       through all members of the container, i.e. reading or skipping them.
54       Use sd_bus_message_skip(3) to skip over felds of a container in order
55       to be able to exit the container with sd_bus_message_exit_container()
56       without reading all members.
57

RETURN VALUE

59       On success, these functions return a non-negative integer.
60       sd_bus_message_open_container() and sd_bus_message_close_container()
61       return 0.  sd_bus_message_enter_container() returns 1 if it
62       successfully opened a new container, and 0 if that was not possible
63       because the end of the currently open container or message was reached.
64       sd_bus_message_exit_container() returns 1 on success. On failure, all
65       of these functions return a negative errno-style error code.
66
67   Errors
68       Returned errors may indicate the following problems:
69
70       -EINVAL
71           m or contents are NULL or type is invalid.
72
73       -EPERM
74           The message m is already sealed.
75
76       -ESTALE
77           The message m is in an invalid state.
78
79       -ENOMEM
80           Memory allocation failed.
81
82       -EBUSY
83           sd_bus_message_exit_container() was called but there are unread
84           members left in the container.
85

NOTES

87       These APIs are implemented as a shared library, which can be compiled
88       and linked to with the libsystemd pkg-config(1) file.
89

EXAMPLES

91       Example 1. Append an array of strings to a message
92
93           /* SPDX-License-Identifier: CC0-1.0 */
94
95           #include <systemd/sd-bus.h>
96
97           int append_strings_to_message(sd_bus_message *m, const char *const *arr) {
98             int r;
99
100             r = sd_bus_message_open_container(m, 'a', "s");
101             if (r < 0)
102               return r;
103
104             for (const char *s = *arr; *s; s++) {
105               r = sd_bus_message_append(m, "s", s);
106               if (r < 0)
107                 return r;
108             }
109
110             return sd_bus_message_close_container(m);
111           }
112
113       Example 2. Read an array of strings from a message
114
115           /* SPDX-License-Identifier: CC0-1.0 */
116
117           #include <stdio.h>
118
119           #include <systemd/sd-bus.h>
120
121           int read_strings_from_message(sd_bus_message *m) {
122             int r;
123
124             r = sd_bus_message_enter_container(m, 'a', "s");
125             if (r < 0)
126               return r;
127
128             for (;;) {
129               const char *s;
130
131               r = sd_bus_message_read(m, "s", &s);
132               if (r < 0)
133                 return r;
134               if (r == 0)
135                 break;
136
137               printf("%s\n", s);
138             }
139
140             return sd_bus_message_exit_container(m);
141           }
142

NOTES

149        1. The D-Bus specification
150           https://dbus.freedesktop.org/doc/dbus-specification.html
151
152
153
154systemd 250                                   SD_BUS_MESSAGE_OPEN_CONTAINER(3)