# sd_bus_message_new_method_call

## NAME



           sd_bus_message_new_method_call, sd_bus_message_new_method_return -
           Create a method call message
    


## SYNOPSIS



           **#include <systemd/sd-bus.h>**
    
           **int sd_bus_message_new_method_call(sd_bus ***_bus_**,**
                                              **sd_bus_message ****_m_**,**
                                              **const char ***_destination_**,**
                                              **const char ***_path_**,**
                                              **const char ***_interface_**,**
                                              **const char ***_member_**);**
    
           **int sd_bus_message_new_method_return(sd_bus_message ***_call_**,**
                                                **sd_bus_message ****_m_**);**
    


## DESCRIPTION



           The **sd_bus_message_new_method_call()** function creates a new bus
           message object that encapsulates a D-Bus method call, and returns
           it in the _m_ output parameter. The call will be made on the
           destination _destination_ , path _path_ , on the interface _interface_ ,
           member _member_.
    
           Briefly, the _destination_ is a dot-separated name that identifies a
           service connected to the bus. The _path_ is a slash-separated
           identifier of an object within the destination that resembles a
           file system path. The meaning of this path is defined by the
           destination. The _interface_ is a dot-separated name that resembles
           a Java interface name that identifies a group of methods and
           signals supported by the object identified by path. Methods and
           signals are collectively called _members_ and are identified by a
           simple name composed of ASCII letters, numbers, and underscores.
           See the **D-Bus Tutorial******[1] for an in-depth explanation.
    
           The _destination_ parameter may be **NULL**. The _interface_ parameter may
           be **NULL** , if the destination has only a single member with the
           given name and there is no ambiguity if the interface name is
           omitted.
    
           Note that this is a low level interface. See sd_bus_call_method(3)
           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.
    


## RETURN VALUE



           On success, these functions return a non-negative integer. On
           failure, they return a negative errno-style error code.
    
       **Errors**
           Returned errors may indicate the following problems:
    
           **-EINVAL**
               The output parameter _m_ is **NULL**.
    
               The _destination_ parameter is non-null and is not a valid D-Bus
               service name ("org.somewhere.Something"), the _path_ parameter
               is not a valid D-Bus path ("/an/object/path"), the _interface_
               parameter is non-null and is not a valid D-Bus interface name
               ("an.interface.name"), or the _member_ parameter is not a valid
               D-Bus member ("Name").
    
               The _call_ parameter is not a method call object.
    
           **-ENOTCONN**
               The bus parameter _bus_ is **NULL** or the bus is not connected.
    
           **-ENOMEM**
               Memory allocation failed.
    
           **-EPERM**
               The _call_ parameter is not sealed.
    
           **-EOPNOTSUPP**
               The _call_ message does not have a cookie.
    


## 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.
    


## EXAMPLES



           **Example 1. Make a call to a D-Bus method that takes a single**
           **parameter**
    
               /* SPDX-License-Identifier: MIT-0 */
    
               /* This is equivalent to:
                * busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 \
                *       org.freedesktop.systemd1.Manager GetUnitByPID $$
                *
                * Compile with 'cc print-unit-path.c -lsystemd'
                */
    
               #include <errno.h>
               #include <stdio.h>
               #include <sys/types.h>
               #include <unistd.h>
    
               #include <systemd/sd-bus.h>
    
               #define _cleanup_(f) __attribute__((cleanup(f)))
               #define DESTINATION "org.freedesktop.systemd1"
               #define PATH        "/org/freedesktop/systemd1"
               #define INTERFACE   "org.freedesktop.systemd1.Manager"
               #define MEMBER      "GetUnitByPID"
    
               static int log_error(int error, const char *message) {
                 fprintf(stderr, "%s: %s\n", message, strerror(-error));
                 return error;
               }
    
               int main(int argc, char **argv) {
                 _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL;
                 _cleanup_(sd_bus_error_free) sd_bus_error error = SD_BUS_ERROR_NULL;
                 _cleanup_(sd_bus_message_unrefp) sd_bus_message *reply = NULL, *m = NULL;
                 int r;
    
                 r = sd_bus_open_system(&bus);
                 if (r < 0)
                   return log_error(r, "Failed to acquire bus");
    
                 r = sd_bus_message_new_method_call(bus, &m,
                                                    DESTINATION, PATH, INTERFACE, MEMBER);
                 if (r < 0)
                   return log_error(r, "Failed to create bus message");
    
                 r = sd_bus_message_append(m, "u", (unsigned) getpid());
                 if (r < 0)
                   return log_error(r, "Failed to append to bus message");
    
                 r = sd_bus_call(bus, m, -1, &error, &reply);
                 if (r < 0)
                   return log_error(r, MEMBER " call failed");
    
                 const char *ans;
                 r = sd_bus_message_read(reply, "o", &ans);
                 if (r < 0)
                   return log_error(r, "Failed to read reply");
    
                 printf("Unit path is \"%s\".\n", ans);
    
                 return 0;
               }
    
           This defines a minimally useful program that will open a
           connection to the bus, create a message object, send it, wait for
           the reply, and finally extract and print the answer. It does error
           handling and proper memory management.
    


## NOTES



            1. D-Bus Tutorial
               https://dbus.freedesktop.org/doc/dbus-tutorial.html#concepts
    


* * *