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

SEE ALSO

160       systemd(1), sd-bus(3), sd_bus_call(3), sd_bus_call_method(3),
161       sd_bus_path_encode(3)
162

NOTES

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