1SD_BUS_MESSAGE_APPEND(3)     sd_bus_message_append    SD_BUS_MESSAGE_APPEND(3)
2
3
4

NAME

6       sd_bus_message_append, sd_bus_message_appendv - Attach fields to a
7       D-Bus message based on a type string
8

SYNOPSIS

10       #include <systemd/sd-bus.h>
11
12       int sd_bus_message_append(sd_bus_message *m, const char *types, ...);
13
14       int sd_bus_message_appendv(sd_bus_message *m, const char *types,
15                                  va_list ap);
16

DESCRIPTION

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
24       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
31       In case of a basic type, one argument of the corresponding type is
32       expected.
33
34       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
39       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
43       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
47       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
53       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
59       For further details on the D-Bus type system, please consult the D-Bus
60       Specification[1].
61
62       Table 1. Item type specifiers
63       ┌──────────┬──────────────────────────────┬────────────────┬───────────────┬───────────────┐
64Specifier 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
122       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

TYPES STRING GRAMMAR

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

EXAMPLES

139       Append a single basic type (the string "a string"):
140
141           sd_bus_message *m;
142           ...
143           sd_bus_message_append(m, "s", "a string");
144
145       Append all types of integers:
146
147           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
157       Append a structure composed of a string and a D-Bus path:
158
159           sd_bus_message_append(m, "(so)", "a string", "/a/path");
160
161       Append an array of UNIX file descriptors:
162
163           sd_bus_message_append(m, "ah", 3, STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO);
164
165       Append a variant, with the real type "g" (signature), and value
166       "sdbusisgood":
167
168           sd_bus_message_append(m, "v", "g", "sdbusisgood");
169
170       Append a dictionary containing the mapping {1=>"a", 2=>"b", 3=>""}:
171
172           sd_bus_message_append(m, "a{is}", 3, 1, "a", 2, "b", 3, NULL);
173
174

RETURN VALUE

176       On success, these functions return 0 or a positive integer. On failure,
177       they return a negative errno-style error code.
178
179   Errors
180       Returned errors may indicate the following problems:
181
182       -EINVAL
183           Specified parameter is invalid.
184
185       -EPERM
186           Message has been sealed.
187
188       -ESTALE
189           Message is in invalid state.
190
191       -ENXIO
192           Message cannot be appended to.
193
194       -ENOMEM
195           Memory allocation failed.
196

NOTES

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

SEE ALSO

202       systemd(1), sd-bus(3), sd_bus_message_append_basic(3),
203       sd_bus_message_append_array(3)
204

NOTES

206        1. D-Bus Specification
207           http://dbus.freedesktop.org/doc/dbus-specification.html#type-system
208
209
210
211systemd 245                                           SD_BUS_MESSAGE_APPEND(3)
Impressum