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 internal reference counter of m by
59 one.
60
61 sd_bus_message_unref() decreases the internal reference counter of m by
62 one. Once the reference count has dropped to zero, message object is
63 destroyed and cannot be used anymore, so further calls to
64 sd_bus_message_ref() or sd_bus_message_unref() are illegal.
65
66 sd_bus_message_unrefp() is similar to sd_bus_message_unref() but takes
67 a pointer to a pointer to an sd_bus_message object. This call is useful
68 in conjunction with GCC's and LLVM's Clean-up Variable Attribute[1].
69 See sd_bus_new(3) for an example how to use the cleanup attribute.
70
71 sd_bus_message_ref() and sd_bus_message_unref() execute no operation if
72 the passed in bus message object address is NULL.
73 sd_bus_message_unrefp() will first dereference its argument, which must
74 not be NULL, and will execute no operation if that is NULL.
75
76 sd_bus_message_get_bus() returns the bus object that message m is
77 attached to.
78
80 On success, sd_bus_message_new() returns 0 or a positive integer. On
81 failure, it returns a negative errno-style error code.
82
83 sd_bus_message_ref() always returns the argument.
84
85 sd_bus_message_unref() always returns NULL.
86
87 sd_bus_message_get_bus() always returns the bus object.
88
89 Errors
90 Returned errors may indicate the following problems:
91
92 -EINVAL
93 Specified type is invalid.
94
95 -ENOTCONN
96 The bus parameter bus is NULL or the bus is not connected.
97
98 -ENOMEM
99 Memory allocation failed.
100
102 These APIs are implemented as a shared library, which can be compiled
103 and linked to with the libsystemd pkg-config(1) file.
104
106 systemd(1), sd-bus(3), sd_bus_new(3),
107 sd_bus_message_new_method_call(3), sd_bus_message_new_method_error(3),
108 sd_bus_message_new_method_return(3), sd_bus_message_new_signal(3)
109
111 1. Clean-up Variable Attribute
112 https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
113
114
115
116systemd 251 SD_BUS_MESSAGE_NEW(3)