sd_bus_call(3)

1SD_BUS_CALL(3)                    sd_bus_call                   SD_BUS_CALL(3)
2
3
4

NAME

6       sd_bus_call, sd_bus_call_async - Invoke a D-Bus method call
7

SYNOPSIS

9       #include <systemd/sd-bus.h>
10
11       typedef int (*sd_bus_message_handler_t)(sd_bus_message *m,
12                                               void *userdata,
13                                               sd_bus_error *ret_error);
14
15       int sd_bus_call(sd_bus *bus, sd_bus_message *m, uint64_t usec,
16                       sd_bus_error *ret_error, sd_bus_message **reply);
17
18       int sd_bus_call_async(sd_bus *bus, sd_bus_slot **slot,
19                             sd_bus_message *m,
20                             sd_bus_message_handler_t callback,
21                             void *userdata, uint64_t usec);
22

DESCRIPTION

24       sd_bus_call() takes a complete bus message object and calls the
25       corresponding D-Bus method. On success, the response is stored in
26       reply.  usec indicates the timeout in microseconds. If ret_error is not
27       NULL and sd_bus_call() fails (either because of an internal error or
28       because it received a D-Bus error reply), ret_error is initialized to
29       an instance of sd_bus_error describing the error.
30
31       sd_bus_call_async() is like sd_bus_call() but works asynchronously. The
32       callback indicates the function to call when the response arrives. The
33       userdata pointer will be passed to the callback function, and may be
34       chosen freely by the caller. If slot is not NULL and
35       sd_bus_call_async() succeeds, slot is set to a slot object which can be
36       used to cancel the method call at a later time using
37       sd_bus_slot_unref(3). If slot is NULL, the lifetime of the method call
38       is bound to the lifetime of the bus object itself, and it cannot be
39       cancelled independently. See sd_bus_slot_set_floating(3) for details.
40       callback is called when a reply arrives with the reply, userdata and an
41       sd_bus_error output parameter as its arguments. Unlike sd_bus_call(),
42       the sd_bus_error output parameter passed to the callback will be empty.
43       To determine whether the method call succeeded, use
44       sd_bus_message_is_method_error(3) on the reply message passed to the
45       callback instead. If the callback returns zero and the sd_bus_error
46       output parameter is still empty when the callback finishes, other
47       handlers registered with functions such as sd_bus_add_filter(3) or
48       sd_bus_add_match(3) are given a chance to process the message. If the
49       callback returns a non-zero value or the sd_bus_error output parameter
50       is not empty when the callback finishes, no further processing of the
51       message is done. Generally, you want to return zero from the callback
52       to give other registered handlers a chance to process the reply as
53       well. (Note that the sd_bus_error parameter is an output parameter of
54       the callback function, not an input parameter; it can be used to
55       propagate errors from the callback handler, it will not receive any
56       error that was received as method reply.)
57
58       The message m passed to the callback is only borrowed, that is, the
59       callback should not call sd_bus_message_unref(3) on it. If the callback
60       wants to hold on to the message beyond the lifetime of the callback, it
61       needs to call sd_bus_message_ref(3) to create a new reference.
62
63       If usec is zero, the default D-Bus method call timeout is used. See
64       sd_bus_get_method_call_timeout(3).
65

RETURN VALUE

67       On success, these functions return a non-negative integer. On failure,
68       they return a negative errno-style error code.
69
70   Errors
71       Returned errors may indicate the following problems. When sd_bus_call()
72       internally receives a D-Bus error reply, it will set ret_error if it is
73       not NULL, and will return a negative value mapped from the error reply.
74       See sd_bus_error_get_errno(3).
75
76       -EINVAL
77           The input parameter m is NULL.  The input parameter m is not a
78           D-Bus method call. To create a new D-Bus method call, use
79           sd_bus_message_new_method_call(3).  The input parameter m has the
80           BUS_MESSAGE_NO_REPLY_EXPECTED flag set.  The input parameter error
81           is non-NULL but was not set to SD_BUS_ERROR_NULL.
82
83       -ECHILD
84           The bus connection was allocated in a parent process and is being
85           reused in a child process after fork().
86
87       -ENOTCONN
88           The input parameter bus is NULL or the bus is not connected.
89
90       -ECONNRESET
91           The bus connection was closed while waiting for the response.
92
93       -ETIMEDOUT
94           A response was not received within the given timeout.
95
96       -ELOOP
97           The message m is addressed to its own client.
98
99       -ENOMEM
100           Memory allocation failed.
101

NOTES

103       These APIs are implemented as a shared library, which can be compiled
104       and linked to with the libsystemd pkg-config(1) file.
105

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

SEE ALSO