SD_BUS_MESSAGE_READ_BASIC(3)

NAME
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 | 8bit unsigned integer | uint8_t *
"b" | SD_BUS_TYPE_BOOLEAN | boolean | int * (NB: not bool *)
"n" | SD_BUS_TYPE_INT16 | 16bit signed integer | int16_t *
"q" | SD_BUS_TYPE_UINT16 | 16bit unsigned integer | uint16_t *
"i" | SD_BUS_TYPE_INT32 | 32bit signed integer | int32_t *
"u" | SD_BUS_TYPE_UINT32 | 32bit unsigned integer | uint32_t *
"x" | SD_BUS_TYPE_INT64 | 64bit signed integer | int64_t *
"t" | SD_BUS_TYPE_UINT64 | 64bit unsigned integer | uint64_t *
"d" | SD_BUS_TYPE_DOUBLE | IEEE 754 double precision floating-point | double *
"s" | SD_BUS_TYPE_STRING | UTF-8 string | const char **
"o" | SD_BUS_TYPE_OBJECT_PATH | D-Bus object path string | const char **
"g" | SD_BUS_TYPE_SIGNATURE | D-Bus signature string | 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