From 7cd40caa66462ef72442d2c4cb7267d0fce9bae1 Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Wed, 22 Apr 2020 22:02:39 +0200 Subject: [PATCH] sd-bus: Add sd_bus_message_open/close/enter/exit_container docs --- man/rules/meson.build | 6 + man/sd-bus-container-append.c | 17 +++ man/sd-bus-container-read.c | 25 ++++ man/sd-bus.xml | 4 + man/sd_bus_message_append.xml | 3 +- man/sd_bus_message_open_container.xml | 165 ++++++++++++++++++++++++++ man/sd_bus_message_read.xml | 3 +- 7 files changed, 221 insertions(+), 2 deletions(-) create mode 100644 man/sd-bus-container-append.c create mode 100644 man/sd-bus-container-read.c create mode 100644 man/sd_bus_message_open_container.xml diff --git a/man/rules/meson.build b/man/rules/meson.build index 1405c95b61..e59ad3769d 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -319,6 +319,12 @@ manpages = [ 'sd_bus_message_new_method_errorf'], ''], ['sd_bus_message_new_signal', '3', [], ''], + ['sd_bus_message_open_container', + '3', + ['sd_bus_message_close_container', + 'sd_bus_message_enter_container', + 'sd_bus_message_exit_container'], + ''], ['sd_bus_message_read', '3', ['sd_bus_message_readv'], ''], ['sd_bus_message_read_array', '3', [], ''], ['sd_bus_message_read_basic', '3', [], ''], diff --git a/man/sd-bus-container-append.c b/man/sd-bus-container-append.c new file mode 100644 index 0000000000..e350ea03d6 --- /dev/null +++ b/man/sd-bus-container-append.c @@ -0,0 +1,17 @@ +#include + +int append_strings_to_message(sd_bus_message *m, const char *const *arr) { + int r; + + r = sd_bus_message_open_container(m, 'a', "s"); + if (r < 0) + return r; + + for (const char *s = *arr; *s; s++) { + r = sd_bus_message_append(m, "s", s); + if (r < 0) + return r; + } + + return sd_bus_message_close_container(m); +} diff --git a/man/sd-bus-container-read.c b/man/sd-bus-container-read.c new file mode 100644 index 0000000000..b6c95f47fd --- /dev/null +++ b/man/sd-bus-container-read.c @@ -0,0 +1,25 @@ +#include + +#include + +int read_strings_from_message(sd_bus_message *m) { + int r; + + r = sd_bus_message_enter_container(m, 'a', "s"); + if (r < 0) + return r; + + for (;;) { + const char *s; + + r = sd_bus_message_read(m, "s", &s); + if (r < 0) + return r; + if (r == 0) + break; + + printf("%s\n", s); + } + + return sd_bus_message_exit_container(m); +} diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 6b14474f79..58f53cda0b 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -95,8 +95,11 @@ sd_bus_message_append_string_memfd3, sd_bus_message_append_strv3, sd_bus_message_at_end3, +sd_bus_message_close_container3, sd_bus_message_copy3, sd_bus_message_dump3, +sd_bus_message_enter_container3, +sd_bus_message_exit_container3, sd_bus_message_get_allow_interactive_authorization3, sd_bus_message_get_cookie3, sd_bus_message_get_errno3, @@ -113,6 +116,7 @@ sd_bus_message_new_method_call3, sd_bus_message_new_method_error3, sd_bus_message_new_signal3, +sd_bus_message_open_container3, sd_bus_message_read3, sd_bus_message_read_array3, sd_bus_message_read_basic3, diff --git a/man/sd_bus_message_append.xml b/man/sd_bus_message_append.xml index 6ebcc8d9ea..5faadd603a 100644 --- a/man/sd_bus_message_append.xml +++ b/man/sd_bus_message_append.xml @@ -229,7 +229,8 @@ sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d); systemd1, sd-bus3, sd_bus_message_append_basic3, - sd_bus_message_append_array3 + sd_bus_message_append_array3, + sd_bus_message_open_container3 diff --git a/man/sd_bus_message_open_container.xml b/man/sd_bus_message_open_container.xml new file mode 100644 index 0000000000..5f6e7c10e8 --- /dev/null +++ b/man/sd_bus_message_open_container.xml @@ -0,0 +1,165 @@ + + + + + + + + sd_bus_message_open_container + systemd + + + + sd_bus_message_open_container + 3 + + + + sd_bus_message_open_container + sd_bus_message_close_container + sd_bus_message_enter_container + sd_bus_message_exit_container + + Create and move between containers in D-Bus messages + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_open_container + sd_bus_message *m + char type + const char *contents + + + + int sd_bus_message_close_container + sd_bus_message *m + + + + int sd_bus_message_enter_container + sd_bus_message *m + char type + const char *contents + + + + int sd_bus_message_exit_container + sd_bus_message *m + + + + + + Description + + sd_bus_message_open_container() appends a new container to the message + m. After opening a new container, it can be filled with content using + sd_bus_message_append3 + and similar functions. Containers behave like a stack. To nest containers inside each other, call + sd_bus_message_open_container() multiple times without calling + sd_bus_message_close_container() inbetween. Each container will be nested inside the + previous container. type represents the container type and should be one of + r, a, v or e as described in + sd_bus_message_append3. + Instead of literals, the corresponding constants SD_BUS_TYPE_STRUCT, + SD_BUS_TYPE_ARRAY, SD_BUS_TYPE_VARIANT or + SD_BUS_TYPE_DICT_ENTRY can also be used. contents describes + the type of the container's elements and should be a D-Bus type string following the rules described in + sd_bus_message_append3. + + + sd_bus_message_close_container() closes the last container opened with + sd_bus_message_open_container(). On success, the write pointer of the message + m is positioned after the closed container in its parent container or in + m itself if there is no parent container. + + sd_bus_message_enter_container() enters the next container of the message + m. It behaves mostly the same as + sd_bus_message_open_container(). Entering a container allows reading its contents + with + sd_bus_message_read3 + and similar functions. type and contents are the same as in + sd_bus_message_open_container(). + + sd_bus_message_exit_container() exits the scope of the last container entered + with sd_bus_message_enter_container(). It behaves mostly the same as + sd_bus_message_close_container(). + + + + Return Value + + On success, these functions return a non-negative integer. On failure, they return a negative + errno-style error code. + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + m or contents are + NULL or type is invalid. + + + + -EPERM + + The message m is already sealed. + + + + -ESTALE + + The message m is in an invalid state. + + + + -ENOMEM + + Memory allocation failed. + + + + + + + + + Examples + + + Append an array of strings to a message + + + + + + Read an array of strings from a message + + + + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_message_append3, + sd_bus_message_read3, + The D-Bus specification + + + + diff --git a/man/sd_bus_message_read.xml b/man/sd_bus_message_read.xml index 53cda9f329..a716660a2c 100644 --- a/man/sd_bus_message_read.xml +++ b/man/sd_bus_message_read.xml @@ -228,7 +228,8 @@ sd_bus_message_read(m, "a{is}", 3, &i, &s, &j, &t, &k, & sd-bus3, sd_bus_message_read_basic3, sd_bus_message_skip3, - sd_bus_message_append3 + sd_bus_message_append3, + sd_bus_message_enter_container3