From 3df22bb5c8340b68b07028941a09da1fe5ad69ec Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Thu, 23 Apr 2020 19:37:21 +0200 Subject: [PATCH] sd-bus: Add sd_bus_message_peek_type docs --- man/rules/meson.build | 5 ++- man/sd-bus.xml | 1 + man/sd_bus_message_read.xml | 78 +++++++++++++++++++++---------------- 3 files changed, 49 insertions(+), 35 deletions(-) diff --git a/man/rules/meson.build b/man/rules/meson.build index 1405c95b61a..796966b2734 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -319,7 +319,10 @@ manpages = [ 'sd_bus_message_new_method_errorf'], ''], ['sd_bus_message_new_signal', '3', [], ''], - ['sd_bus_message_read', '3', ['sd_bus_message_readv'], ''], + ['sd_bus_message_read', + '3', + ['sd_bus_message_peek_type', 'sd_bus_message_readv'], + ''], ['sd_bus_message_read_array', '3', [], ''], ['sd_bus_message_read_basic', '3', [], ''], ['sd_bus_message_read_strv', '3', [], ''], diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 6b14474f792..034ba0da264 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -113,6 +113,7 @@ sd_bus_message_new_method_call3, sd_bus_message_new_method_error3, sd_bus_message_new_signal3, +sd_bus_message_peek_type3, sd_bus_message_read3, sd_bus_message_read_array3, sd_bus_message_read_basic3, diff --git a/man/sd_bus_message_read.xml b/man/sd_bus_message_read.xml index 53cda9f3293..646943325f5 100644 --- a/man/sd_bus_message_read.xml +++ b/man/sd_bus_message_read.xml @@ -19,6 +19,7 @@ sd_bus_message_read sd_bus_message_readv + sd_bus_message_peek_type Read a sequence of values from a message @@ -40,38 +41,42 @@ const char *types va_list ap + + + int sd_bus_message_peek_type + char *type + const char **contents + Description - sd_bus_message_read() reads a sequence of fields from - the D-Bus message object m and advances the read position - in the message. The type string types describes the types - of items expected in the message and the field arguments that follow. The type - string may be NULL or empty, in which case nothing is - read. + sd_bus_message_read() reads a sequence of fields from the D-Bus message object + m and advances the read position in the message. The type string + types describes the types of items expected in the message and the field arguments + that follow. The type string may be NULL or empty, in which case nothing is read. + The type string is composed of the elements described in sd_bus_message_append3, - i.e. basic and container types. It must contain zero or more single "complete - types". The type string is NUL-terminated. - - For each type specified in the type string, one or more arguments need to be specified - after the types parameter, in the same order. The arguments must be - pointers to appropriate types (a pointer to int8_t for a y in - the type string, a pointer to int32_t for an i, a pointer to - const char* for an s, ...) which are set based on the values in - the message. As an exception, in case of array and variant types, the first argument is an - "input" argument that further specifies how the message should be read. See the table below for - a complete list of allowed arguments and their types. Note that, if the basic type is a pointer - (e.g., const char * in the case of a string), the argument is a pointer to a - pointer, and also the pointer value that is written is only borrowed and the contents must be - copied if they are to be used after the end of the messages lifetime. - - Each argument may also be NULL, in which case the value is read and - ignored. + i.e. basic and container types. It must contain zero or more single "complete types". The type string is + NUL-terminated. + + For each type specified in the type string, one or more arguments need to be specified after the + types parameter, in the same order. The arguments must be pointers to appropriate + types (a pointer to int8_t for a y in the type string, a pointer to + int32_t for an i, a pointer to const char* for an + s, ...) which are set based on the values in the message. As an exception, in case of + array and variant types, the first argument is an "input" argument that further specifies how the message + should be read. See the table below for a complete list of allowed arguments and their types. Note that, + if the basic type is a pointer (e.g., const char * in the case of a string), the argument is + a pointer to a pointer, and also the pointer value that is written is only borrowed and the contents must + be copied if they are to be used after the end of the messages lifetime. + + Each argument may also be NULL, in which case the value is read and ignored. + Item type specifiers @@ -139,24 +144,29 @@
- If objects of the specified types are not present at the current position - in the message, an error is returned. - + If objects of the specified types are not present at the current position in the message, an error + is returned. The sd_bus_message_readv() is equivalent to the - sd_bus_message_read(), except that it is called with a - va_list instead of a variable number of arguments. This - function does not call the va_end() macro. Because it - invokes the va_arg() macro, the value of - ap is undefined after the call. + sd_bus_message_read(), except that it is called with a va_list + instead of a variable number of arguments. This function does not call the va_end() + macro. Because it invokes the va_arg() macro, the value of ap + is undefined after the call. + + sd_bus_message_peek_type() determines the type of the next element in + m to be read by sd_bus_message_read() or similar functions. + On success, the type is stored in type, if it is not NULL. + If the type is a container type, the type of its elements is stored in contents, + if it is not NULL. If this function successfully determines the type of the next + element in m, it returns a positive integer. If there are no more elements to be + read, it returns zero. Return Value - On success, sd_bus_message_read() and - sd_bus_message_readv() return 0 or a positive integer. On failure, they return a - negative errno-style error code. + On success, these functions return a non-negative integer. On failure, they return a negative + errno-style error code. -- 2.39.2