From 47203ed0858238bf0429b6367597b3731e7fd17d Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Tue, 31 Mar 2020 19:50:53 +0200 Subject: [PATCH] sd-bus: sd_bus_call docs improvements --- man/sd_bus_call.xml | 39 ++++++++++++++++++++++----------------- 1 file changed, 22 insertions(+), 17 deletions(-) diff --git a/man/sd_bus_call.xml b/man/sd_bus_call.xml index f2d725a29f..93462f24b5 100644 --- a/man/sd_bus_call.xml +++ b/man/sd_bus_call.xml @@ -52,34 +52,39 @@ Description sd_bus_call() takes a complete bus message object and calls the - corresponding D-Bus method. The response is stored in reply. + corresponding D-Bus method. On success, the response is stored in reply. usec indicates the timeout in microseconds. If ret_error is not NULL and - sd_bus_call() returns an error, ret_error is - initialized to an instance of sd_bus_error describing the error. + sd_bus_call() fails (either because of an internal error or because it + received a D-Bus error reply), ret_error is initialized to an instance of + sd_bus_error describing the error. sd_bus_call_async() is like sd_bus_call() but - works asynchronously. The callback shall reference a function to call - when the event source is triggered. The userdata pointer will be passed - to the callback function, and may be chosen freely by the caller. If slot - is not NULL and sd_bus_call_async() succeeds, + works asynchronously. The callback indicates the function to call when + the response arrives. The userdata pointer will be passed to the callback + function, and may be chosen freely by the caller. If slot is not + NULL and sd_bus_call_async() succeeds, slot is set to a slot object which can be used to cancel the method call at a later time using sd_bus_slot_unref3. If slot is NULL, the lifetime of the method call is bound to the lifetime of the bus object itself, and it cannot be cancelled independently. See sd_bus_slot_set_floating3 - for details. The callback function is called when the response arrives - and receives the response, userdata and a - sd_bus_error object as its arguments. The - sd_bus_error object is unused here and should be ignored. If - callback returns a non-negative integer when called, a debug message is - logged along with details about the response. - - To determine whether the method call succeeded, use + for details. callback is called when a reply arrives with the reply, + userdata and an sd_bus_error output + parameter as its arguments. Unlike sd_bus_call(), the + sd_bus_error output parameter passed to the callback will be empty. To + determine whether the method call succeeded, use sd_bus_message_is_method_error3 - on the reply object returned by sd_bus_call() or passed to the callback of - sd_bus_call_async(). + on the reply message passed to the callback instead. If the callback returns zero and the + sd_bus_error output parameter is still empty when the callback + inishes, other handlers registered with functions such as + sd_bus_add_filter3 or + sd_bus_add_match3 + are given a chance to process the message. If the callback returns a non-zero value or the + sd_bus_error output parameter is not empty when the callback finishes, + no further processing of the message is done. Generally, you want to return zero from the + callback to give other registered handlers a chance to process the reply as well. If usec is zero, the default D-Bus method call timeout is used. See sd_bus_get_method_call_timeout3.