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

NOTES

145        1. The D-Bus specification
146           https://dbus.freedesktop.org/doc/dbus-specification.html
147
148
149
150systemd 248                                   SD_BUS_MESSAGE_OPEN_CONTAINER(3)