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       The sd_bus_message_new_method_call() function creates a new bus message
42       object that is a reply to the method call call and returns it in the m
43       output parameter. The call parameter must be a method call message. The
44       sender of call is used as the destination.
45

RETURN VALUE

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

NOTES

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

EXAMPLES

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

SEE ALSO

155       systemd(1), sd-bus(3), sd_bus_path_encode(3)
156

NOTES

158        1. D-Bus Tutorial
159           https://dbus.freedesktop.org/doc/dbus-tutorial.html#concepts
160
161
162
163systemd 245                                  SD_BUS_MESSAGE_NEW_METHOD_CALL(3)
Impressum