mirror of
https://github.com/systemd/systemd.git
synced 2024-10-30 14:55:37 +03:00
289 lines
11 KiB
XML
289 lines
11 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+
|
||
|
||
This file is part of systemd.
|
||
|
||
Copyright 2014 Zbigniew Jędrzejewski-Szmek
|
||
|
||
systemd is free software; you can redistribute it and/or modify it
|
||
under the terms of the GNU Lesser General Public License as published by
|
||
the Free Software Foundation; either version 2.1 of the License, or
|
||
(at your option) any later version.
|
||
|
||
systemd is distributed in the hope that it will be useful, but
|
||
WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||
Lesser General Public License for more details.
|
||
|
||
You should have received a copy of the GNU Lesser General Public License
|
||
along with systemd; If not, see <http://www.gnu.org/licenses/>.
|
||
-->
|
||
|
||
<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" />
|
||
|
||
<refsect1>
|
||
<title>Notes</title>
|
||
|
||
<para><function>sd_bus_open_user()</function> and other functions
|
||
described here are available as a shared library, which can be
|
||
compiled and linked to with the
|
||
<constant>libsystemd-bus</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
||
file.</para>
|
||
</refsect1>
|
||
|
||
<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>
|