sd_bus_message_append.xml revision e8216945a97bc2a2b04bc286e67ab5bba313b83e
c6d33447e28403a90ad817dba4df75fae785be28pquerna<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
c6d33447e28403a90ad817dba4df75fae785be28pquerna<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
c6d33447e28403a90ad817dba4df75fae785be28pquerna"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
c6d33447e28403a90ad817dba4df75fae785be28pquerna This file is part of systemd.
c6d33447e28403a90ad817dba4df75fae785be28pquerna Copyright 2014 Zbigniew Jędrzejewski-Szmek
c6d33447e28403a90ad817dba4df75fae785be28pquerna systemd is free software; you can redistribute it and/or modify it
c6d33447e28403a90ad817dba4df75fae785be28pquerna under the terms of the GNU Lesser General Public License as published by
c6d33447e28403a90ad817dba4df75fae785be28pquerna the Free Software Foundation; either version 2.1 of the License, or
c6d33447e28403a90ad817dba4df75fae785be28pquerna (at your option) any later version.
c6d33447e28403a90ad817dba4df75fae785be28pquerna systemd is distributed in the hope that it will be useful, but
c6d33447e28403a90ad817dba4df75fae785be28pquerna WITHOUT ANY WARRANTY; without even the implied warranty of
546d45814f6de2976187f3eaad9ba7a4b01c8b77pquerna MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
546d45814f6de2976187f3eaad9ba7a4b01c8b77pquerna Lesser General Public License for more details.
c6d33447e28403a90ad817dba4df75fae785be28pquerna You should have received a copy of the GNU Lesser General Public License
c6d33447e28403a90ad817dba4df75fae785be28pquerna along with systemd; If not, see <http://www.gnu.org/licenses/>.
546d45814f6de2976187f3eaad9ba7a4b01c8b77pquerna <refentryinfo>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <authorgroup>
546d45814f6de2976187f3eaad9ba7a4b01c8b77pquerna </authorgroup>
546d45814f6de2976187f3eaad9ba7a4b01c8b77pquerna </refentryinfo>
546d45814f6de2976187f3eaad9ba7a4b01c8b77pquerna <refentrytitle>sd_bus_message_append</refentrytitle>
546d45814f6de2976187f3eaad9ba7a4b01c8b77pquerna <refnamediv>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <refpurpose>Attach fields to a D-Bus message based on a type
c6d33447e28403a90ad817dba4df75fae785be28pquerna string</refpurpose>
c6d33447e28403a90ad817dba4df75fae785be28pquerna </refnamediv>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <refsynopsisdiv>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <funcsynopsis>
546d45814f6de2976187f3eaad9ba7a4b01c8b77pquerna <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <funcprototype>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <paramdef>const char *<parameter>types</parameter></paramdef>
c6d33447e28403a90ad817dba4df75fae785be28pquerna </funcprototype>
c6d33447e28403a90ad817dba4df75fae785be28pquerna </funcsynopsis>
c6d33447e28403a90ad817dba4df75fae785be28pquerna </refsynopsisdiv>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <para>The <function>sd_bus_message_append()</function> function
c6d33447e28403a90ad817dba4df75fae785be28pquerna appends a sequence of fields to the D-Bus message object
c6d33447e28403a90ad817dba4df75fae785be28pquerna <parameter>types</parameter> describes the types of the field
c6d33447e28403a90ad817dba4df75fae785be28pquerna arguments that follow. For each type specified in the type string
c6d33447e28403a90ad817dba4df75fae785be28pquerna one or more arguments need to be specified, in the same order as
c6d33447e28403a90ad817dba4df75fae785be28pquerna declared in the type string.</para>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <para>The type string is composed of the elements shown in the
c6d33447e28403a90ad817dba4df75fae785be28pquerna table below. It contains zero or more single "complete types".
c6d33447e28403a90ad817dba4df75fae785be28pquerna Each complete type may be one of the basic types or a fully
c6d33447e28403a90ad817dba4df75fae785be28pquerna described container type. A container type may be a structure with
c6d33447e28403a90ad817dba4df75fae785be28pquerna the contained types, a variant, an array with its element type, or
c6d33447e28403a90ad817dba4df75fae785be28pquerna a dictionary entry with the contained types. The type string is
c6d33447e28403a90ad817dba4df75fae785be28pquerna <para>In case of a basic type, one argument of the corresponding
c6d33447e28403a90ad817dba4df75fae785be28pquerna type is expected.</para>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <para>A structure is denoted by a sequence of complete types
c6d33447e28403a90ad817dba4df75fae785be28pquerna between <literal>(</literal> and <literal>)</literal>. This
c6d33447e28403a90ad817dba4df75fae785be28pquerna sequence cannot be empty — it must contain at least one type.
c6d33447e28403a90ad817dba4df75fae785be28pquerna Arguments corresponding to this nested sequence follow the same
546d45814f6de2976187f3eaad9ba7a4b01c8b77pquerna rules as if they were not nested.</para>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <para>A variant is denoted by <literal>v</literal>. Corresponding
c6d33447e28403a90ad817dba4df75fae785be28pquerna arguments must begin with a type string denoting a complete type,
c6d33447e28403a90ad817dba4df75fae785be28pquerna and following that, arguments corresponding to the specified type.
c6d33447e28403a90ad817dba4df75fae785be28pquerna <para>An array is denoted by <literal>a</literal> followed by a
c6d33447e28403a90ad817dba4df75fae785be28pquerna complete type. Corresponding arguments must begin with the number of
c6d33447e28403a90ad817dba4df75fae785be28pquerna entries in the array, followed by the entries themselves,
c6d33447e28403a90ad817dba4df75fae785be28pquerna matching the element type of the array.</para>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <para>A dictionary is an array of dictionary entries, denoted by
c6d33447e28403a90ad817dba4df75fae785be28pquerna <literal>a</literal> followed by a pair of complete types between
c6d33447e28403a90ad817dba4df75fae785be28pquerna <literal>{</literal> and <literal>}</literal>. The first of those
c6d33447e28403a90ad817dba4df75fae785be28pquerna types must be a basic type. Corresponding arguments must begin
c6d33447e28403a90ad817dba4df75fae785be28pquerna with the number of dictionary entries, followed by a pair of
c6d33447e28403a90ad817dba4df75fae785be28pquerna values for each entry matching the element type of
c6d33447e28403a90ad817dba4df75fae785be28pquerna the dictionary entries.</para>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <para>For further details on the D-Bus type system, please consult
c6d33447e28403a90ad817dba4df75fae785be28pquerna url="http://dbus.freedesktop.org/doc/dbus-specification.html#type-system">D-Bus
c6d33447e28403a90ad817dba4df75fae785be28pquerna <xi:include href="sd_bus_message_append_basic.xml" xpointer="xpointer(//table[@id='format-specifiers'])//colspec" />
c6d33447e28403a90ad817dba4df75fae785be28pquerna <xi:include href="sd_bus_message_append_basic.xml" xpointer="xpointer(//table[@id='format-specifiers']//thead)" />
c6d33447e28403a90ad817dba4df75fae785be28pquerna <xi:include href="sd_bus_message_append_basic.xml" xpointer="xpointer(//table[@id='format-specifiers']//tbody/*)" />
c6d33447e28403a90ad817dba4df75fae785be28pquerna <entry><constant>SD_BUS_TYPE_ARRAY</constant></entry>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <entry><constant>SD_BUS_TYPE_VARIANT</constant></entry>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <entry>signature string, followed by variant contents</entry>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <entry><constant>SD_BUS_TYPE_STRUCT_BEGIN</constant></entry>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <entry morerows="1">determined by the nested types</entry>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <entry><constant>SD_BUS_TYPE_STRUCT_END</constant></entry>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <entry><constant>SD_BUS_TYPE_DICT_ENTRY_BEGIN</constant></entry>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <entry morerows="1">determined by the nested types</entry>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <entry><constant>SD_BUS_TYPE_DICT_ENTRY_END</constant></entry>
c6d33447e28403a90ad817dba4df75fae785be28pquerna </refsect1>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <programlisting>types ::= complete_type*
c6d33447e28403a90ad817dba4df75fae785be28pquernacomplete_type ::= basic_type | variant | structure | array | dictionary
c6d33447e28403a90ad817dba4df75fae785be28pquernabasic_type ::= "y" | "n" | "q" | "u" | "i" | "x" | "t" | "d" |
c6d33447e28403a90ad817dba4df75fae785be28pquerna "b" | "h" |
c6d33447e28403a90ad817dba4df75fae785be28pquerna "s" | "o" | "g"
c6d33447e28403a90ad817dba4df75fae785be28pquernavariant ::= "v"
c6d33447e28403a90ad817dba4df75fae785be28pquernastructure ::= "(" complete_type+ ")"
c6d33447e28403a90ad817dba4df75fae785be28pquernaarray ::= "a" complete_type
c6d33447e28403a90ad817dba4df75fae785be28pquernadictionary ::= "a" "{" basic_type complete_type "}"
c6d33447e28403a90ad817dba4df75fae785be28pquerna</programlisting>
c6d33447e28403a90ad817dba4df75fae785be28pquerna </refsect1>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <para>Append a single basic type (the string <literal>a string</literal>):
c6d33447e28403a90ad817dba4df75fae785be28pquerna <programlisting>sd_bus_message *m;
c6d33447e28403a90ad817dba4df75fae785be28pquernasd_bus_message_append(m, "s", "a string");</programlisting>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <programlisting>uint8_t y = 1;
c6d33447e28403a90ad817dba4df75fae785be28pquernaint16_t n = 2;
c6d33447e28403a90ad817dba4df75fae785be28pquernauint16_t q = 3;
c6d33447e28403a90ad817dba4df75fae785be28pquernaint32_t i = 4;
c6d33447e28403a90ad817dba4df75fae785be28pquernauint32_t u = 5;
c6d33447e28403a90ad817dba4df75fae785be28pquernaint32_t x = 6;
c6d33447e28403a90ad817dba4df75fae785be28pquernauint32_t t = 7;
c6d33447e28403a90ad817dba4df75fae785be28pquernadouble d = 8.0;
c6d33447e28403a90ad817dba4df75fae785be28pquernasd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d);</programlisting>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <para>Append a structure composed of a string and a D-Bus path:</para>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <programlisting>sd_bus_message_append(m, "(so)", "a string", "/a/path");
c6d33447e28403a90ad817dba4df75fae785be28pquerna</programlisting>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <para>Append an array of UNIX file descriptors:</para>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <programlisting>sd_bus_message_append(m, "ah", 3, STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO);
c6d33447e28403a90ad817dba4df75fae785be28pquerna</programlisting>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <para>Append a variant, with the real type "g" (signature),
c6d33447e28403a90ad817dba4df75fae785be28pquerna and value "sdbusisgood":</para>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <programlisting>sd_bus_message_append(m, "v", "g", "sdbusisgood");</programlisting>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <para>Append a dictionary containing the mapping {1=>"a", 2=>"b", 3=>""}:
c6d33447e28403a90ad817dba4df75fae785be28pquerna <programlisting>sd_bus_message_append(m, "a{is}", 3, 1, "a", 2, "b", 3, NULL);
c6d33447e28403a90ad817dba4df75fae785be28pquerna </programlisting>
c6d33447e28403a90ad817dba4df75fae785be28pquerna </refsect1>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <para>On success, this call returns 0 or a positive
c6d33447e28403a90ad817dba4df75fae785be28pquerna integer. On failure, this call returns a negative
c6d33447e28403a90ad817dba4df75fae785be28pquerna errno-style error code.</para>
c6d33447e28403a90ad817dba4df75fae785be28pquerna </refsect1>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" />
c6d33447e28403a90ad817dba4df75fae785be28pquerna <para><function>sd_bus_open_user()</function> and other functions
c6d33447e28403a90ad817dba4df75fae785be28pquerna described here are available as a shared library, which can be
c6d33447e28403a90ad817dba4df75fae785be28pquerna compiled and linked to with the
c6d33447e28403a90ad817dba4df75fae785be28pquerna <constant>libsystemd-bus</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
c6d33447e28403a90ad817dba4df75fae785be28pquerna file.</para>
c6d33447e28403a90ad817dba4df75fae785be28pquerna </refsect1>
c6d33447e28403a90ad817dba4df75fae785be28pquerna <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
c6d33447e28403a90ad817dba4df75fae785be28pquerna <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
c6d33447e28403a90ad817dba4df75fae785be28pquerna <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
c6d33447e28403a90ad817dba4df75fae785be28pquerna <citerefentry><refentrytitle>sd_bus_message_append_array</refentrytitle><manvolnum>3</manvolnum></citerefentry>
c6d33447e28403a90ad817dba4df75fae785be28pquerna </refsect1>