sd_bus_message_read_basic — Read a basic type from a message
Synopsis
#include <systemd/sd-bus.h>
int sd_bus_message_read_basic(sd_bus_message *m, char type, void *p);
Description
sd_bus_message_read_basic() reads a basic type from a message and advances the read position in the message. The set of basic types and their ascii codes passed in type are described in the D-Bus Specification[1].
If p is not NULL, it should contain a pointer to an appropriate object. For example, if type is 'y', the object passed in p should have type uint8_t *. If type is 's', the object passed in p should have type const char **. Note that, if the basic type is a pointer (e.g., const char * in the case of a string), the pointer is only borrowed and the contents must be copied if they are to be used after the end of the messages lifetime. Similarly, during the lifetime of such a pointer, the message must not be modified. See the table below for a complete list of allowed types.
Table 1. Item type specifiers
| Specifier | Constant | Description | Expected C Type |
|---|---|---|---|
| "y" | SD_BUS_TYPE_BYTE | unsigned integer | uint8_t * |
| "b" | SD_BUS_TYPE_BOOLEAN | boolean | int * |
| "n" | SD_BUS_TYPE_INT16 | signed integer | int16_t * |
| "q" | SD_BUS_TYPE_UINT16 | unsigned integer | uint16_t * |
| "i" | SD_BUS_TYPE_INT32 | signed integer | int32_t * |
| "u" | SD_BUS_TYPE_UINT32 | unsigned integer | uint32_t * |
| "x" | SD_BUS_TYPE_INT64 | signed integer | int64_t * |
| "t" | SD_BUS_TYPE_UINT64 | unsigned integer | uint64_t * |
| "d" | SD_BUS_TYPE_DOUBLE | floating-point | double * |
| "s" | SD_BUS_TYPE_STRING | Unicode string | const char ** |
| "o" | SD_BUS_TYPE_OBJECT_PATH | object path | const char ** |
| "g" | SD_BUS_TYPE_SIGNATURE | signature | const char ** |
| "h" | SD_BUS_TYPE_UNIX_FD | UNIX file descriptor | int * |
If there is no object of the specified type at the current position in the message, an error is returned.
Return Value
On success, sd_bus_message_read_basic() returns 0 or a positive integer. On failure, it returns a negative errno-style error code.
Errors
Returned errors may indicate the following problems:
- -EINVAL
Specified type string is invalid or the message parameter is NULL.
- -ENXIO
The message does not contain the specified type at current position.
- -EBADMSG
The message cannot be parsed.
See Also
systemd(1), sd-bus(3), sd_bus_message_append_basic(3), sd_bus_message_skip(3), sd_bus_message_read(3)
Notes
- 1.
D-Bus Specification
https://dbus.freedesktop.org/doc/dbus-specification.html
Referenced By
sd-bus(3), sd_bus_message_append_basic(3), sd_bus_message_read(3), sd_bus_message_skip(3), systemd.directives(7), systemd.index(7).