1SD_BUS_MESSAGE_APPEND(3) sd_bus_message_append SD_BUS_MESSAGE_APPEND(3)
2
6 sd_bus_message_append, sd_bus_message_appendv - Attach fields to a
7 D-Bus message based on a type string
8
10 #include <systemd/sd-bus.h>
11 int sd_bus_message_append(sd_bus_message *m, const char *types, ...);
13 int sd_bus_message_appendv(sd_bus_message *m, const char *types,
15 va_list ap);
16
18 The sd_bus_message_append() function appends a sequence of fields to
19 the D-Bus message object m. The type string types describes the types
20 of the field arguments that follow. For each type specified in the type
21 string, one or more arguments need to be specified, in the same order
22 as declared in the type string.
23 The type string is composed of the elements shown in the table below.
25 It contains zero or more single "complete types". Each complete type
26 may be one of the basic types or a fully described container type. A
27 container type may be a structure with the contained types, a variant,
28 an array with its element type, or a dictionary entry with the
29 contained types. The type string is NUL-terminated.
30 In case of a basic type, one argument of the corresponding type is
32 expected.
33 A structure is denoted by a sequence of complete types between "(" and
35 ")". This sequence cannot be empty — it must contain at least one type.
36 Arguments corresponding to this nested sequence follow the same rules
37 as if they were not nested.
38 A variant is denoted by "v". Corresponding arguments must begin with a
40 type string denoting a complete type, and following that, arguments
41 corresponding to the specified type.
42 An array is denoted by "a" followed by a complete type. Corresponding
44 arguments must begin with the number of entries in the array, followed
45 by the entries themselves, matching the element type of the array.
46 A dictionary is an array of dictionary entries, denoted by "a" followed
48 by a pair of complete types between "{" and "}". The first of those
49 types must be a basic type. Corresponding arguments must begin with the
50 number of dictionary entries, followed by a pair of values for each
51 entry matching the element type of the dictionary entries.
52 The sd_bus_message_appendv() is equivalent to the
54 sd_bus_message_append(), except that it is called with a "va_list"
55 instead of a variable number of arguments. This function does not call
56 the va_end() macro. Because it invokes the va_arg() macro, the value of
57 ap is undefined after the call.
58 For further details on the D-Bus type system, please consult the D-Bus
60 Specification[1].
61 Table 1. Item type specifiers
63 ┌──────────┬──────────────────────────────┬────────────────┬───────────────┬───────────────┐
64 │Specifier │ Constant │ Description │ Size │ Expected C │
65 │ │ │ │ │ Type │
66 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
67 │"y" │ SD_BUS_TYPE_BYTE │ unsigned │ 1 byte │ uint8_t │
68 │ │ │ integer │ │ │
69 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
70 │"b" │ SD_BUS_TYPE_BOOLEAN │ boolean │ 4 bytes │ int │
71 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
72 │"n" │ SD_BUS_TYPE_INT16 │ signed │ 2 bytes │ int16_t │
73 │ │ │ integer │ │ │
74 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
75 │"q" │ SD_BUS_TYPE_UINT16 │ unsigned │ 2 bytes │ uint16_t │
76 │ │ │ integer │ │ │
77 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
78 │"i" │ SD_BUS_TYPE_INT32 │ signed │ 4 bytes │ int32_t │
79 │ │ │ integer │ │ │
80 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
81 │"u" │ SD_BUS_TYPE_UINT32 │ unsigned │ 4 bytes │ uint32_t │
82 │ │ │ integer │ │ │
83 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
84 │"x" │ SD_BUS_TYPE_INT64 │ signed │ 8 bytes │ int64_t │
85 │ │ │ integer │ │ │
86 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
87 │"t" │ SD_BUS_TYPE_UINT64 │ unsigned │ 8 bytes │ uint64_t │
88 │ │ │ integer │ │ │
89 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
90 │"d" │ SD_BUS_TYPE_DOUBLE │ floating-point │ 8 bytes │ double │
91 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
92 │"s" │ SD_BUS_TYPE_STRING │ Unicode string │ variable │ char[] │
93 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
94 │"o" │ SD_BUS_TYPE_OBJECT_PATH │ object path │ variable │ char[] │
95 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
96 │"g" │ SD_BUS_TYPE_SIGNATURE │ signature │ variable │ char[] │
97 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
98 │"h" │ SD_BUS_TYPE_UNIX_FD │ UNIX file │ 4 bytes │ int │
99 │ │ │ descriptor │ │ │
100 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
101 │"a" │ SD_BUS_TYPE_ARRAY │ array │ determined by │ int, followed │
102 │ │ │ │ array type │ by array │
103 │ │ │ │ and size │ contents │
104 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
105 │"v" │ SD_BUS_TYPE_VARIANT │ variant │ determined by │ signature │
106 │ │ │ │ the type │ string, │
107 │ │ │ │ argument │ followed by │
108 │ │ │ │ │ variant │
109 │ │ │ │ │ contents │
110 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
111 │"(" │ SD_BUS_TYPE_STRUCT_BEGIN │ array start │ determined by │ structure │
112 ├──────────┼──────────────────────────────┼────────────────┤ the nested │ contents │
113 │")" │ SD_BUS_TYPE_STRUCT_END │ array end │ types │ │
114 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
115 │"{" │ SD_BUS_TYPE_DICT_ENTRY_BEGIN │ dictionary │ │ │
116 │ │ │ entry start │ determined by │ dictionary │
117 ├──────────┼──────────────────────────────┼────────────────┤ the nested │ contents │
118 │"}" │ SD_BUS_TYPE_DICT_ENTRY_END │ dictionary │ types │ │
119 │ │ │ entry end │ │ │
120 └──────────┴──────────────────────────────┴────────────────┴───────────────┴───────────────┘
121 For types "s" and "g" (unicode string or signature), the pointer may be
123 NULL, which is equivalent to an empty string. See
124 sd_bus_message_append_basic(3) for the precise interpretation of those
125 and other types.
126
128 types ::= complete_type*
129 complete_type ::= basic_type | variant | structure | array | dictionary
130 basic_type ::= "y" | "n" | "q" | "u" | "i" | "x" | "t" | "d" |
131 "b" | "h" |
132 "s" | "o" | "g"
133 variant ::= "v"
134 structure ::= "(" complete_type+ ")"
135 array ::= "a" complete_type
136 dictionary ::= "a" "{" basic_type complete_type "}"
137
139 Append a single basic type (the string "a string"):
140 sd_bus_message *m;
142 ...
143 sd_bus_message_append(m, "s", "a string");
144 Append all types of integers:
146 uint8_t y = 1;
148 int16_t n = 2;
149 uint16_t q = 3;
150 int32_t i = 4;
151 uint32_t u = 5;
152 int32_t x = 6;
153 uint32_t t = 7;
154 double d = 8.0;
155 sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d);
156 Append a structure composed of a string and a D-Bus path:
158 sd_bus_message_append(m, "(so)", "a string", "/a/path");
160 Append an array of UNIX file descriptors:
162 sd_bus_message_append(m, "ah", 3, STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO);
164 Append a variant, with the real type "g" (signature), and value
166 "sdbusisgood":
167 sd_bus_message_append(m, "v", "g", "sdbusisgood");
169 Append a dictionary containing the mapping {1=>"a", 2=>"b", 3=>""}:
171 sd_bus_message_append(m, "a{is}", 3, 1, "a", 2, "b", 3, NULL);
173
176 On success, these functions return 0 or a positive integer. On failure,
177 they return a negative errno-style error code.
178 Errors
180 Returned errors may indicate the following problems:
181 -EINVAL
183 Specified parameter is invalid.
184 -EPERM
186 Message has been sealed.
187 -ESTALE
189 Message is in invalid state.
190 -ENXIO
192 Message cannot be appended to.
193 -ENOMEM
195 Memory allocation failed.
196
198 These APIs are implemented as a shared library, which can be compiled
199 and linked to with the libsystemd pkg-config(1) file.
200
202 systemd(1), sd-bus(3), sd_bus_message_append_basic(3),
203 sd_bus_message_append_array(3)
204
206 1. D-Bus Specification
207 http://dbus.freedesktop.org/doc/dbus-specification.html#type-system
208systemd 243 SD_BUS_MESSAGE_APPEND(3)