From 9735c644be672f5ba3b319417e266648ed133d42 Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Mon, 16 Mar 2020 20:41:57 +0100 Subject: [PATCH] sd-bus: Add sd_bus_method_call/sd_bus_method_call_async docs + cleanups. --- man/rules/meson.build | 6 +- man/sd-bus.xml | 2 + man/sd_bus_call_method.xml | 110 +++++++++++++++++++++++++ man/sd_bus_message_new_method_call.xml | 15 ++-- man/sd_bus_message_read.xml | 4 +- 5 files changed, 129 insertions(+), 8 deletions(-) create mode 100644 man/sd_bus_call_method.xml diff --git a/man/rules/meson.build b/man/rules/meson.build index 296dd7da3a7..d54e3bf78b4 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -137,6 +137,7 @@ manpages = [ 'sd_bus_add_fallback_vtable'], ''], ['sd_bus_attach_event', '3', ['sd_bus_detach_event', 'sd_bus_get_event'], ''], + ['sd_bus_call_method', '3', ['sd_bus_call_method_async'], ''], ['sd_bus_close', '3', ['sd_bus_flush'], ''], ['sd_bus_creds_get_pid', '3', @@ -217,7 +218,10 @@ manpages = [ '3', ['SD_BUS_ERROR_END', 'SD_BUS_ERROR_MAP', 'sd_bus_error_map'], ''], - ['sd_bus_get_fd', '3', ['sd_bus_get_events', 'sd_bus_get_timeout'], ''], + ['sd_bus_get_fd', + '3', + ['sd_bus_get_events', 'sd_bus_get_timeout', 'sd_bus_set_fd'], + ''], ['sd_bus_get_n_queued_read', '3', ['sd_bus_get_n_queued_write'], ''], ['sd_bus_is_open', '3', ['sd_bus_is_ready'], ''], ['sd_bus_message_append', '3', ['sd_bus_message_appendv'], ''], diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 76865e1f8ee..35db2bb69d5 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -43,6 +43,8 @@ sd_bus_add_match3, sd_bus_add_object_vtable3, sd_bus_attach_event3, +sd_bus_call_method3, +sd_bus_call_method_async3, sd_bus_creds_get_pid3, sd_bus_creds_new_from_pid3, sd_bus_close3, diff --git a/man/sd_bus_call_method.xml b/man/sd_bus_call_method.xml new file mode 100644 index 00000000000..1565bab82d7 --- /dev/null +++ b/man/sd_bus_call_method.xml @@ -0,0 +1,110 @@ + + + + + + + + sd_bus_call_method + systemd + + + + sd_bus_call_method + 3 + + + + sd_bus_call_method + sd_bus_call_method_async + + Invoke a D-Bus method call + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_call_method + sd_bus *bus + const char *destination + const char *path + const char *interface + const char *member + sd_bus_error *ret_error + sd_bus_message **reply + const char *types + ... + + + + int sd_bus_call_method_async + sd_bus *bus + sd_bus_slot **slot + const char *destination + const char *path + const char *interface + const char *member + sd_bus_message_handler_t callback + void *userdata + const char *types + ... + + + + + + Description + + sd_bus_call_method() is a convenience function for calling a D-Bus + method. It combines the + sd_bus_message_new_method_call3, + sd_bus_message_append3 and + sd_bus_call3 + functions into a single function call. + + sd_bus_call_method_async() is a convenience function for calling a + D-Bus method asynchronously. It combines the + sd_bus_message_new_method_call3, + sd_bus_message_append3 and + sd_bus_call_async3 + functions into a single function call. + + + + Return Value + + On success, these functions returns a non-negative integer. On failure, they return a + negative errno-style error code. + + + Errors + + See the man pages of + sd_bus_message_new_method_call3, + sd_bus_message_append3, + sd_bus_call3 and + sd_bus_call_async3 + for a list of possible errors. + + + + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_message_new_method_call3, + sd_bus_message_append3, + sd_bus_call3, + sd_bus_call_async3 + + + + diff --git a/man/sd_bus_message_new_method_call.xml b/man/sd_bus_message_new_method_call.xml index 0d181ed82eb..1201262690d 100644 --- a/man/sd_bus_message_new_method_call.xml +++ b/man/sd_bus_message_new_method_call.xml @@ -28,7 +28,7 @@ #include <systemd/sd-bus.h> - int sd_bus_message_new_method_call + int sd_bus_message_new_method_call sd_bus *bus sd_bus_message **m const char *destination @@ -38,7 +38,7 @@ - int sd_bus_message_new_method_return + int sd_bus_message_new_method_return sd_bus_message *call sd_bus_message **m @@ -70,7 +70,11 @@ has only a single member with the given name and there is no ambiguity if the interface name is omitted. - The sd_bus_message_new_method_call() function creates a new bus + Note that this is a low level interface. See + sd_bus_call_method3 + for a more convenient way of calling D-Bus methods. + + The sd_bus_message_new_method_return() function creates a new bus message object that is a reply to the method call call and returns it in the m output parameter. The call parameter must be a method call message. The sender of call is used as the destination. @@ -80,8 +84,8 @@ Return Value - This function returns 0 if the message object was successfully created, and a negative - errno-style error code otherwise. + On success, these functions returns a non-negative integer. On failure, they return a + negative errno-style error code. Errors @@ -160,6 +164,7 @@ systemd1, sd-bus3, sd_bus_path_encode3 + sd_bus_call_method3 diff --git a/man/sd_bus_message_read.xml b/man/sd_bus_message_read.xml index 2afa4417422..ee7bdc4bfdd 100644 --- a/man/sd_bus_message_read.xml +++ b/man/sd_bus_message_read.xml @@ -30,14 +30,14 @@ int sd_bus_message_read sd_bus_message *m - char char *types + const char *types ... int sd_bus_message_readv sd_bus_message *m - char char *types + const char *types va_list ap -- 2.39.5