# sd_bus_call

## NAME



           sd_bus_call, sd_bus_call_async - Invoke a D-Bus method call
    


## SYNOPSIS



           **#include <systemd/sd-bus.h>**
    
           **typedef int (*sd_bus_message_handler_t)(sd_bus_message ***_m_**,**
                                                   **void ***_userdata_**,**
                                                   **sd_bus_error ***_ret_error_**);**
    
           **int sd_bus_call(sd_bus ***_bus_**, sd_bus_message ***_m_**, uint64_t** _usec_**,**
                           **sd_bus_error ***_ret_error_**, sd_bus_message ****_reply_**);**
    
           **int sd_bus_call_async(sd_bus ***_bus_**, sd_bus_slot ****_slot_**,**
                                 **sd_bus_message ***_m_**,**
                                 **sd_bus_message_handler_t** _callback_**,**
                                 **void ***_userdata_**, uint64_t** _usec_**);**
    


## DESCRIPTION



           **sd_bus_call()** takes a complete bus message object and calls the
           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()** 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_ 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_unref(3). 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_floating(3) 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_error(3) 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
           finishes, other handlers registered with functions such as
           sd_bus_add_filter(3) or sd_bus_add_match(3) 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. (Note that the
           sd_bus_error parameter is an output parameter of the callback
           function, not an input parameter; it can be used to propagate
           errors from the callback handler, it will not receive any error
           that was received as method reply.)
    
           The message _m_ passed to the callback is only borrowed, that is,
           the callback should not call sd_bus_message_unref(3) on it. If the
           callback wants to hold on to the message beyond the lifetime of
           the callback, it needs to call sd_bus_message_ref(3) to create a
           new reference.
    
           If _usec_ is zero, the default D-Bus method call timeout is used.
           See sd_bus_get_method_call_timeout(3).
    


## RETURN VALUE



           On success, these functions return a non-negative integer. On
           failure, they return a negative errno-style error code.
    
       **Errors**
           When **sd_bus_call()** internally receives a D-Bus error reply, it
           will set _ret_error_ if it is not **NULL** , and will return a negative
           value mapped from the error reply, see sd_bus_error_get_errno(3).
    
           Returned errors may indicate the following problems:
    
           **-EINVAL**
               The input parameter _m_ is **NULL**.
    
               The input parameter _m_ is not a D-Bus method call. To create a
               new D-Bus method call, use sd_bus_message_new_method_call(3).
    
               The input parameter _m_ has the **BUS_MESSAGE_NO_REPLY_EXPECTED**
               flag set.
    
               The input parameter _error_ is non-**NULL** but was not set to
               **SD_BUS_ERROR_NULL**.
    
           **-ECHILD**
               The bus connection was allocated in a parent process and is
               being reused in a child process after **fork()**.
    
           **-ENOTCONN**
               The input parameter _bus_ is **NULL** or the bus is not connected.
    
           **-ECONNRESET**
               The bus connection was closed while waiting for the response.
    
           **-ETIMEDOUT**
               A response was not received within the given timeout.
    
           **-ELOOP**
               The message _m_ is addressed to its own client.
    
           **-ENOMEM**
               Memory allocation failed.
    


## NOTES



           Functions described here are available as a shared library, which
           can be compiled against and linked to with the
           **libsystemd pkg-config**(1) file.
    
           The code described here uses getenv(3), which is declared to be
           not multi-thread-safe. This means that the code calling the
           functions described here must not call setenv(3) from a parallel
           thread. It is recommended to only do calls to **setenv()** from an
           early phase of the program when no other threads have been
           started.
    


* * *