SD_BUS_MESSAGE_APPEND_BASIC(3)

NAME
sd_bus_message_append_basic - Attach a single part to a message

SYNOPSIS

#include <systemd/sd-bus.h>

int sd_bus_message_append_basic(sd_bus_message *m, char type, char void *p);

DESCRIPTION

sd_bus_message_append_basic appends a single item to the message m. Parameter type determines how pointer p is interpreted. type must be one of the basic types as defined by the Basic Types[1] section of the D-Bus specification, and listed in the table below.

Table 1. Item format specifiers
Specifier | Constant | Description | Size
"y" | SD_BUS_TYPE_BYTE | unsigned integer | 1 byte
"b" | SD_BUS_TYPE_BOOLEAN | boolean | 4 bytes
"n" | SD_BUS_TYPE_INT16 | signed integer | 2 bytes
"q" | SD_BUS_TYPE_UINT16 | unsigned integer | 2 bytes
"i" | SD_BUS_TYPE_INT32 | signed integer | 4 bytes
"u" | SD_BUS_TYPE_UINT32 | unsigned integer | 4 bytes
"x" | SD_BUS_TYPE_INT64 | signed integer | 8 bytes
"t" | SD_BUS_TYPE_UINT64 | unsigned integer | 8 bytes
"d" | SD_BUS_TYPE_DOUBLE | floating-point | 8 bytes
"s" | SD_BUS_TYPE_STRING | Unicode string | variable
"o" | SD_BUS_TYPE_OBJECT_PATH | object path | variable
"g" | SD_BUS_TYPE_SIGNATURE | signature | variable
"h" | SD_BUS_TYPE_UNIX_FD | UNIX file descriptor | 4 bytes

The value of the parameter is copied into the memory area containing the message and may be changed after this call. If type is "h" (UNIX file descriptor), it is always "consumed" by this call, and either successfully appended to the message or closed.

For types "s", "o", and "g", the parameter p is interpreted as a pointer to a NUL-terminated character sequence. As a special case, a NULL pointer is interpreted as an empty string. The string should be valid Unicode string encoded as UTF-8. In case of the two latter types, the additional requirements for a D-Bus object path or type signature should be satisfied. Those requirements should be verified by the recipient of the message.

RETURN VALUE

On success, this call 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 parameter is invalid.

-EPERM
    Message has been sealed.

-ESTALE
    Message is in invalid state.

-ENXIO
    Message cannot be appended to.

-ENOMEM
    Memory allocation failed.

NOTES

The sd_bus_append_basic() function described here is available as a shared library, which can be compiled and linked to with the libsystemd pkg-config(1) file.

SEE ALSO

systemd(1), sd-bus(3), sd_bus_message_append(3), The D-Bus specification[2]

NOTES

1.  Basic Types
    http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types

2.  The D-Bus specification
    http://dbus.freedesktop.org/doc/dbus-specification.html