1SD_BUS_MESSAGE_NEW_METHODs_dC_AbLuLs(_3m)essage_new_metShDo_dB_UcSa_lMlESSAGE_NEW_METHOD_CALL(3)
2
3
4

NAME

6       sd_bus_message_new_method_call, sd_bus_message_new_method_return -
7       Create a method call message
8

SYNOPSIS

10       #include <systemd/sd-bus.h>
11
12       int sd_bus_message_new_method_call(sd_bus *bus, sd_bus_message **m,
13                                          const char *destination,
14                                          const char *path,
15                                          const char *interface,
16                                          const char *member);
17
18       int sd_bus_message_new_method_return(sd_bus_message *call,
19                                            sd_bus_message **m);
20

DESCRIPTION

22       The sd_bus_message_new_method_call() function creates a new bus message
23       object that encapsulates a D-Bus method call, and returns it in the m
24       output parameter. The call will be made on the destination destination,
25       path path, on the interface interface, member member.
26
27       Briefly, the destination is a dot-separated name that identifies a
28       service connected to the bus. The path is a slash-separated identifier
29       of an object within the destination that resembles a file system path.
30       The meaning of this path is defined by the destination. The interface
31       is a dot-separated name that resembles a Java interface name that
32       identifies a group of methods and signals supported by the object
33       identified by path. Methods and signals are collectively called members
34       and are identified by a simple name composed of ASCII letters, numbers,
35       and underscores. See the D-Bus Tutorial[1] for an in-depth explanation.
36
37       The destination parameter may be NULL. The interface parameter may be
38       NULL, if the destination has only a single member with the given name
39       and there is no ambiguity if the interface name is omitted.
40
41       Note that this is a low level interface. See sd_bus_call_method(3) for
42       a more convenient way of calling D-Bus methods.
43
44       The sd_bus_message_new_method_return() function creates a new bus
45       message object that is a reply to the method call call and returns it
46       in the m output parameter. The call parameter must be a method call
47       message. The sender of call is used as the destination.
48

RETURN VALUE

50       On success, these functions return a non-negative integer. On failure,
51       they return a negative errno-style error code.
52
53   Errors
54       Returned errors may indicate the following problems:
55
56       -EINVAL
57           The output parameter m is NULL.
58
59           The destination parameter is non-null and is not a valid D-Bus
60           service name ("org.somewhere.Something"), the path parameter is not
61           a valid D-Bus path ("/an/object/path"), the interface parameter is
62           non-null and is not a valid D-Bus interface name
63           ("an.interface.name"), or the member parameter is not a valid D-Bus
64           member ("Name").
65
66           The call parameter is not a method call object.
67
68       -ENOTCONN
69           The bus parameter bus is NULL or the bus is not connected.
70
71       -ENOMEM
72           Memory allocation failed.
73
74       -EPERM
75           The call parameter is not sealed.
76
77       -EOPNOTSUPP
78           The call message does not have a cookie.
79

NOTES

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

EXAMPLES

85       Example 1. Make a call to a D-Bus method that takes a single parameter
86
87           #include <stdio.h>
88           #include <string.h>
89           #include <unistd.h>
90           #include <sys/types.h>
91
92           #include <systemd/sd-bus.h>
93           #define _cleanup_(f) __attribute__((cleanup(f)))
94
95           /* This is equivalent to:
96            * busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 \
97            *       org.freedesktop.systemd1.Manager GetUnitByPID $$
98            *
99            * Compile with 'cc -lsystemd print-unit-path.c'
100            */
101
102           #define DESTINATION "org.freedesktop.systemd1"
103           #define PATH        "/org/freedesktop/systemd1"
104           #define INTERFACE   "org.freedesktop.systemd1.Manager"
105           #define MEMBER      "GetUnitByPID"
106
107           static int log_error(int error, const char *message) {
108             fprintf(stderr, "%s: %s\n", message, strerror(-error));
109             return error;
110           }
111
112           static int print_unit_path(sd_bus *bus) {
113             _cleanup_(sd_bus_message_unrefp) sd_bus_message *m = NULL;
114             _cleanup_(sd_bus_error_free) sd_bus_error error = SD_BUS_ERROR_NULL;
115             _cleanup_(sd_bus_message_unrefp) sd_bus_message *reply = NULL;
116             int r;
117
118             r = sd_bus_message_new_method_call(bus, &m,
119                                                DESTINATION, PATH, INTERFACE, MEMBER);
120             if (r < 0)
121               return log_error(r, "Failed to create bus message");
122
123             r = sd_bus_message_append(m, "u", (unsigned) getpid());
124             if (r < 0)
125               return log_error(r, "Failed to append to bus message");
126
127             r = sd_bus_call(bus, m, -1, &error, &reply);
128             if (r < 0)
129               return log_error(r, "Call failed");
130
131             const char *ans;
132             r = sd_bus_message_read(reply, "o", &ans);
133             if (r < 0)
134               return log_error(r, "Failed to read reply");
135
136             printf("Unit path is \"%s\".\n", ans);
137
138             return 0;
139           }
140
141           int main(int argc, char **argv) {
142             _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL;
143             int r;
144
145             r = sd_bus_open_system(&bus);
146             if (r < 0)
147               return log_error(r, "Failed to acquire bus");
148
149             print_unit_path(bus);
150           }
151
152       This defines a minimally useful program that will open a connection to
153       the bus, create a message object, send it, wait for the reply, and
154       finally extract and print the answer. It does error handling and proper
155       memory management.
156

SEE ALSO

158       systemd(1), sd-bus(3), sd_bus_call(3), sd_bus_call_method(3),
159       sd_bus_path_encode(3)
160

NOTES

162        1. D-Bus Tutorial
163           https://dbus.freedesktop.org/doc/dbus-tutorial.html#concepts
164
165
166
167systemd 246                                  SD_BUS_MESSAGE_NEW_METHOD_CALL(3)
Impressum