mirror of
https://github.com/systemd/systemd
synced 2024-11-05 18:25:39 +00:00
239 lines
9.5 KiB
XML
239 lines
9.5 KiB
XML
<?xml version='1.0'?>
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
|
|
|
|
<refentry id="sd_bus_message_append"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
|
|
<refentryinfo>
|
|
<title>sd_bus_message_append</title>
|
|
<productname>systemd</productname>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>sd_bus_message_append</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>sd_bus_message_append</refname>
|
|
<refname>sd_bus_message_appendv</refname>
|
|
|
|
<refpurpose>Attach fields to a D-Bus message based on a type string</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
|
|
|
|
<funcprototype>
|
|
<funcdef>int sd_bus_message_append</funcdef>
|
|
<paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
|
|
<paramdef>const char *<parameter>types</parameter></paramdef>
|
|
<paramdef>…</paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>int sd_bus_message_appendv</funcdef>
|
|
<paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
|
|
<paramdef>const char *<parameter>types</parameter></paramdef>
|
|
<paramdef>va_list <parameter>ap</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>The <function>sd_bus_message_append()</function> function appends a sequence of fields to
|
|
the D-Bus message object <parameter>m</parameter>. The type string <parameter>types</parameter>
|
|
describes the types of the field arguments that follow. For each type specified in the type
|
|
string, one or more arguments need to be specified, in the same order as declared in the type
|
|
string.</para>
|
|
|
|
<para>The type string is composed of the elements shown in the table below. It contains zero or
|
|
more single "complete types". Each complete type may be one of the basic types or a fully
|
|
described container type. A container type may be a structure with the contained types, a
|
|
variant, an array with its element type, or a dictionary entry with the contained types. The
|
|
type string is <constant>NUL</constant>-terminated.</para>
|
|
|
|
<para>In case of a basic type, one argument of the corresponding type is expected.</para>
|
|
|
|
<para>A structure is denoted by a sequence of complete types between <literal>(</literal> and
|
|
<literal>)</literal>. This sequence cannot be empty — it must contain at least one type.
|
|
Arguments corresponding to this nested sequence follow the same rules as if they were not
|
|
nested.</para>
|
|
|
|
<para>A variant is denoted by <literal>v</literal>. Corresponding arguments must begin with a
|
|
type string denoting a complete type, and following that, arguments corresponding to the
|
|
specified type.</para>
|
|
|
|
<para>An array is denoted by <literal>a</literal> followed by a complete type. Corresponding
|
|
arguments must begin with the number of entries in the array, followed by the entries
|
|
themselves, matching the element type of the array.</para>
|
|
|
|
<para>A dictionary is an array of dictionary entries, denoted by <literal>a</literal> followed
|
|
by a pair of complete types between <literal>{</literal> and <literal>}</literal>. The first of
|
|
those types must be a basic type. Corresponding arguments must begin with the number of
|
|
dictionary entries, followed by a pair of values for each entry matching the element type of the
|
|
dictionary entries.</para>
|
|
|
|
<para><function>sd_bus_message_appendv()</function> is equivalent to
|
|
<function>sd_bus_message_append()</function>, except that it is called with a
|
|
<literal>va_list</literal> instead of a variable number of arguments. This function does not
|
|
call the <function>va_end()</function> macro. Because it invokes the
|
|
<function>va_arg()</function> macro, the value of <parameter>ap</parameter> is undefined after
|
|
the call.</para>
|
|
|
|
<para>For further details on the D-Bus type system, please consult the
|
|
<ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#type-system">D-Bus Specification</ulink>.
|
|
</para>
|
|
|
|
<table>
|
|
<title>Item type specifiers</title>
|
|
|
|
<tgroup cols='5'>
|
|
<xi:include href="sd_bus_message_append_basic.xml" xpointer="xpointer(//table[@id='format-specifiers'])//colspec" />
|
|
<xi:include href="sd_bus_message_append_basic.xml" xpointer="xpointer(//table[@id='format-specifiers']//thead)" />
|
|
|
|
<tbody>
|
|
<xi:include href="sd_bus_message_append_basic.xml" xpointer="xpointer(//table[@id='format-specifiers']//tbody/*)" />
|
|
|
|
<row>
|
|
<entry><literal>a</literal></entry>
|
|
<entry><constant>SD_BUS_TYPE_ARRAY</constant></entry>
|
|
<entry>array</entry>
|
|
<entry>determined by array type and size</entry>
|
|
<entry>int, followed by array contents</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>v</literal></entry>
|
|
<entry><constant>SD_BUS_TYPE_VARIANT</constant></entry>
|
|
<entry>variant</entry>
|
|
<entry>determined by the type argument</entry>
|
|
<entry>signature string, followed by variant contents</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>(</literal></entry>
|
|
<entry><constant>SD_BUS_TYPE_STRUCT_BEGIN</constant></entry>
|
|
<entry>array start</entry>
|
|
<entry morerows="1">determined by the nested types</entry>
|
|
<entry morerows="1">structure contents</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>)</literal></entry>
|
|
<entry><constant>SD_BUS_TYPE_STRUCT_END</constant></entry>
|
|
<entry>array end</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>{</literal></entry>
|
|
<entry><constant>SD_BUS_TYPE_DICT_ENTRY_BEGIN</constant></entry>
|
|
<entry>dictionary entry start</entry>
|
|
<entry morerows="1">determined by the nested types</entry>
|
|
<entry morerows="1">dictionary contents</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>}</literal></entry>
|
|
<entry><constant>SD_BUS_TYPE_DICT_ENTRY_END</constant></entry>
|
|
<entry>dictionary entry end</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<para>For types <literal>s</literal> and <literal>g</literal> (unicode string or signature), the pointer
|
|
may be <constant>NULL</constant>, which is equivalent to an empty string. For <literal>h</literal> (UNIX
|
|
file descriptor), the descriptor is duplicated by this call and the passed descriptor stays in possession
|
|
of the caller. See
|
|
<citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
for the precise interpretation of those and other types.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Types String Grammar</title>
|
|
|
|
<programlisting>types ::= complete_type*
|
|
complete_type ::= basic_type | variant | structure | array | dictionary
|
|
basic_type ::= "y" | "n" | "q" | "u" | "i" | "x" | "t" | "d" |
|
|
"b" | "h" |
|
|
"s" | "o" | "g"
|
|
variant ::= "v"
|
|
structure ::= "(" complete_type+ ")"
|
|
array ::= "a" complete_type
|
|
dictionary ::= "a" "{" basic_type complete_type "}"
|
|
</programlisting>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<para>Append a single basic type (the string <literal>a string</literal>):
|
|
</para>
|
|
|
|
<programlisting>sd_bus_message *m;
|
|
…
|
|
sd_bus_message_append(m, "s", "a string");</programlisting>
|
|
|
|
<para>Append all types of integers:</para>
|
|
|
|
<programlisting>uint8_t y = 1;
|
|
int16_t n = 2;
|
|
uint16_t q = 3;
|
|
int32_t i = 4;
|
|
uint32_t u = 5;
|
|
int32_t x = 6;
|
|
uint32_t t = 7;
|
|
double d = 8.0;
|
|
sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d);</programlisting>
|
|
|
|
<para>Append a structure composed of a string and a D-Bus path:</para>
|
|
|
|
<programlisting>sd_bus_message_append(m, "(so)", "a string", "/a/path");
|
|
</programlisting>
|
|
|
|
<para>Append an array of UNIX file descriptors:</para>
|
|
|
|
<programlisting>sd_bus_message_append(m, "ah", 3, STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO);
|
|
</programlisting>
|
|
|
|
<para>Append a variant, with the real type "g" (signature),
|
|
and value "sdbusisgood":</para>
|
|
|
|
<programlisting>sd_bus_message_append(m, "v", "g", "sdbusisgood");</programlisting>
|
|
|
|
<para>Append a dictionary containing the mapping {1=>"a", 2=>"b", 3=>""}:
|
|
</para>
|
|
|
|
<programlisting>sd_bus_message_append(m, "a{is}", 3, 1, "a", 2, "b", 3, NULL);
|
|
</programlisting>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>On success, these functions return a non-negative integer. On failure, they return a
|
|
negative errno-style error code.</para>
|
|
|
|
<xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" />
|
|
</refsect1>
|
|
|
|
<xi:include href="libsystemd-pkgconfig.xml" />
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<para>
|
|
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_bus_message_append_array</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_bus_message_open_container</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|