1SD_BUS_MESSAGE_NEW(3) sd_bus_message_new SD_BUS_MESSAGE_NEW(3)
2
3
4
6 sd_bus_message_new, sd_bus_message_ref, sd_bus_message_unref,
7 sd_bus_message_unrefp, SD_BUS_MESSAGE_METHOD_CALL,
8 SD_BUS_MESSAGE_METHOD_RETURN, SD_BUS_MESSAGE_METHOD_ERROR,
9 SD_BUS_MESSAGE_SIGNAL, sd_bus_message_get_bus - Create a new bus
10 message object and create or destroy references to it
11
13 #include <systemd/sd-bus.h>
14
15 enum {
16 SD_BUS_MESSAGE_METHOD_CALL,
17 SD_BUS_MESSAGE_METHOD_RETURN,
18 SD_BUS_MESSAGE_METHOD_ERROR,
19 SD_BUS_MESSAGE_SIGNAL,
20 };
21
22 int sd_bus_message_new(sd_bus *bus, sd_bus_message **m, uint8_t type);
23
24 sd_bus_message *sd_bus_message_ref(sd_bus_message *m);
25
26 sd_bus_message *sd_bus_message_unref(sd_bus_message *m);
27
28 void sd_bus_message_unrefp(sd_bus_message **mp);
29
30 sd_bus *sd_bus_message_get_bus(sd_bus_message *m);
31
33 sd_bus_message_new() creates a new bus message object attached to the
34 bus bus and returns it in the output parameter m. This object is
35 reference-counted, and will be destroyed when all references are gone.
36 Initially, the caller of this function owns the sole reference to the
37 message object. Note that the message object holds a reference to the
38 bus object, so the bus object will not be destroyed as long as the
39 message exists.
40
41 Note: this is a low-level call. In most cases functions like
42 sd_bus_message_new_method_call(3), sd_bus_message_new_method_error(3),
43 sd_bus_message_new_method_return(3), and sd_bus_message_new_signal(3)
44 that create a message of a certain type and initialize various fields
45 are easier to use.
46
47 The type parameter specifies the type of the message. It must be one of
48 SD_BUS_MESSAGE_METHOD_CALL — a method call,
49 SD_BUS_MESSAGE_METHOD_RETURN — a method call reply,
50 SD_BUS_MESSAGE_METHOD_ERROR — an error reply to a method call,
51 SD_BUS_MESSAGE_SIGNAL — a broadcast message with no reply.
52
53 The flag to allow interactive authorization is initialized based on the
54 current value set in the bus object, see
55 sd_bus_set_allow_interactive_authorization(3). This may be changed
56 using sd_bus_message_set_allow_interactive_authorization(3).
57
58 sd_bus_message_ref() increases the reference counter of m by one.
59
60 sd_bus_message_unref() decreases the reference counter of m by one.
61 Once the reference count has dropped to zero, message object is
62 destroyed and cannot be used anymore, so further calls to
63 sd_bus_message_ref() or sd_bus_message_unref() are illegal.
64
65 sd_bus_message_unrefp() is similar to sd_bus_message_unref() but takes
66 a pointer to a pointer to an sd_bus_message object. This call is useful
67 in conjunction with GCC's and LLVM's Clean-up Variable Attribute[1].
68 See sd_bus_new(3) for an example how to use the cleanup attribute.
69
70 sd_bus_message_ref() and sd_bus_message_unref() execute no operation if
71 the passed in bus object address is NULL. sd_bus_message_unrefp() will
72 first dereference its argument, which must not be NULL, and will
73 execute no operation if that is NULL.
74
75 sd_bus_message_get_bus() returns the bus object that message m is
76 attached to.
77
79 On success, sd_bus_message_new() returns 0 or a positive integer. On
80 failure, it returns a negative errno-style error code.
81
82 sd_bus_message_ref() always returns the argument.
83
84 sd_bus_message_unref() always returns NULL.
85
86 sd_bus_message_get_bus() always returns the bus object.
87
88 Errors
89 Returned errors may indicate the following problems:
90
91 -EINVAL
92 Specified type is invalid.
93
94 -ENOTCONN
95 The bus parameter bus is NULL or the bus is not connected.
96
97 -ENOMEM
98 Memory allocation failed.
99
101 These APIs are implemented as a shared library, which can be compiled
102 and linked to with the libsystemd pkg-config(1) file.
103
105 systemd(1), sd-bus(3), sd_bus_new(3),
106 sd_bus_message_new_method_call(3), sd_bus_message_new_method_error(3),
107 sd_bus_message_new_method_return(3), sd_bus_message_new_signal(3)
108
110 1. Clean-up Variable Attribute
111 https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
112
113
114
115systemd 245 SD_BUS_MESSAGE_NEW(3)