264 lines
9.6 KiB
XML
264 lines
9.6 KiB
XML
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//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>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<contrib>A monkey with a typewriter</contrib>
|
|
<firstname>Zbigniew</firstname>
|
|
<surname>Jędrzejewski-Szmek</surname>
|
|
<email>zbyszek@in.waw.pl</email>
|
|
</author>
|
|
</authorgroup>
|
|
</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>The <function>sd_bus_message_appendv()</function> is equivalent to
|
|
the function <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 ap
|
|
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 "s" and "g" (unicode string or signature), the pointer may be
|
|
<constant>NULL</constant>, which is equivalent to an empty string. 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 0 or a positive
|
|
integer. On failure, these functions return a negative
|
|
errno-style error code.</para>
|
|
</refsect1>
|
|
|
|
<xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" />
|
|
|
|
<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>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|