4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering This file is part of systemd.
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering Copyright 2014 Zbigniew Jędrzejewski-Szmek
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering systemd is free software; you can redistribute it and/or modify it
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering under the terms of the GNU Lesser General Public License as published by
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering the Free Software Foundation; either version 2.1 of the License, or
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering (at your option) any later version.
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering systemd is distributed in the hope that it will be useful, but
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering Lesser General Public License for more details.
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering You should have received a copy of the GNU Lesser General Public License
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering<refentry id="sd_bus_message_append_basic">
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <refentryinfo>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <title>sd_bus_message_append_basic</title>
7c2a5e264c1d94ca9ba9c49acfdcd541c8a63a88Lennart Poettering <contrib>A monkey with a typewriter</contrib>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering </authorgroup>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering </refentryinfo>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <refentrytitle>sd_bus_message_append_basic</refentrytitle>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <refname>sd_bus_message_append_basic</refname>
7c2a5e264c1d94ca9ba9c49acfdcd541c8a63a88Lennart Poettering <refpurpose>Attach a single field to a message</refpurpose>
7c2a5e264c1d94ca9ba9c49acfdcd541c8a63a88Lennart Poettering <refsynopsisdiv>
7c2a5e264c1d94ca9ba9c49acfdcd541c8a63a88Lennart Poettering <funcsynopsis>
7c2a5e264c1d94ca9ba9c49acfdcd541c8a63a88Lennart Poettering <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
7c2a5e264c1d94ca9ba9c49acfdcd541c8a63a88Lennart Poettering <funcprototype>
7c2a5e264c1d94ca9ba9c49acfdcd541c8a63a88Lennart Poettering <funcdef>int sd_bus_message_append_basic</funcdef>
7c2a5e264c1d94ca9ba9c49acfdcd541c8a63a88Lennart Poettering <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
7c2a5e264c1d94ca9ba9c49acfdcd541c8a63a88Lennart Poettering <paramdef>char <parameter>type</parameter></paramdef>
7c2a5e264c1d94ca9ba9c49acfdcd541c8a63a88Lennart Poettering <paramdef>const void *<parameter>p</parameter></paramdef>
7c2a5e264c1d94ca9ba9c49acfdcd541c8a63a88Lennart Poettering </funcprototype>
7c2a5e264c1d94ca9ba9c49acfdcd541c8a63a88Lennart Poettering </funcsynopsis>
7c2a5e264c1d94ca9ba9c49acfdcd541c8a63a88Lennart Poettering </refsynopsisdiv>
7c2a5e264c1d94ca9ba9c49acfdcd541c8a63a88Lennart Poettering <para><function>sd_bus_message_append_basic()</function> appends a
0dd25fb9f005d8ab7ac4bc10a609d00569f8c56aLennart Poettering single field to the message <parameter>m</parameter>. The
51323288fc628a5cac50914df915545d685b793eLennart Poettering parameter <parameter>type</parameter> determines how the pointer
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <parameter>type</parameter> must be one of the basic types as
309e9d86f0e7f9c5f0a2a09227bdfdb3174d4436Lennart Poettering defined by the <ulink
309e9d86f0e7f9c5f0a2a09227bdfdb3174d4436Lennart Poettering url="http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types">Basic
51323288fc628a5cac50914df915545d685b793eLennart Poettering Types</ulink> section of the D-Bus specification, and listed in
309e9d86f0e7f9c5f0a2a09227bdfdb3174d4436Lennart Poettering the table below.
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <entry><constant>SD_BUS_TYPE_BYTE</constant></entry>
309e9d86f0e7f9c5f0a2a09227bdfdb3174d4436Lennart Poettering <entry><constant>SD_BUS_TYPE_BOOLEAN</constant></entry>
309e9d86f0e7f9c5f0a2a09227bdfdb3174d4436Lennart Poettering <entry><constant>SD_BUS_TYPE_INT16</constant></entry>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <entry><constant>SD_BUS_TYPE_UINT16</constant></entry>
309e9d86f0e7f9c5f0a2a09227bdfdb3174d4436Lennart Poettering <entry><constant>SD_BUS_TYPE_INT32</constant></entry>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <entry><constant>SD_BUS_TYPE_UINT32</constant></entry>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <entry><constant>SD_BUS_TYPE_INT64</constant></entry>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <entry><constant>SD_BUS_TYPE_UINT64</constant></entry>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <entry><constant>SD_BUS_TYPE_DOUBLE</constant></entry>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <entry><constant>SD_BUS_TYPE_STRING</constant></entry>
7c2a5e264c1d94ca9ba9c49acfdcd541c8a63a88Lennart Poettering <entry><constant>SD_BUS_TYPE_OBJECT_PATH</constant></entry>
7c2a5e264c1d94ca9ba9c49acfdcd541c8a63a88Lennart Poettering <entry><constant>SD_BUS_TYPE_SIGNATURE</constant></entry>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <entry><constant>SD_BUS_TYPE_UNIX_FD</constant></entry>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <para>The value of the parameter is copied into a memory area held
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering by the message object, stays in the possession of the caller and
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering may hence be freely changed after this call without affecting the
309e9d86f0e7f9c5f0a2a09227bdfdb3174d4436Lennart Poettering bus message it has been added to. If <parameter>type</parameter>
309e9d86f0e7f9c5f0a2a09227bdfdb3174d4436Lennart Poettering is <literal>h</literal> (UNIX file descriptor), the descriptor is
309e9d86f0e7f9c5f0a2a09227bdfdb3174d4436Lennart Poettering duplicated by this call and the passed descriptor stays in
309e9d86f0e7f9c5f0a2a09227bdfdb3174d4436Lennart Poettering possession of the caller.</para>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <para>For types <literal>s</literal>, <literal>o</literal>, and
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <literal>g</literal>, the parameter <parameter>p</parameter> is
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering interpreted as a pointer to a <constant>NUL</constant>-terminated
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering character sequence. As a special case, a <constant>NULL</constant>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering pointer is interpreted as an empty string. The string should be
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering valid Unicode string encoded as UTF-8. In case of the two latter
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering types, the additional requirements for a D-Bus object path or
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering type signature should be satisfied. Those requirements should be
309e9d86f0e7f9c5f0a2a09227bdfdb3174d4436Lennart Poettering verified by the recipient of the message.
51323288fc628a5cac50914df915545d685b793eLennart Poettering <para>On success, this call returns 0 or a positive integer. On
51323288fc628a5cac50914df915545d685b793eLennart Poettering failure, it returns a negative errno-style error code.</para>
51323288fc628a5cac50914df915545d685b793eLennart Poettering <para>Returned errors may indicate the following problems:</para>
309e9d86f0e7f9c5f0a2a09227bdfdb3174d4436Lennart Poettering <variablelist>
309e9d86f0e7f9c5f0a2a09227bdfdb3174d4436Lennart Poettering <varlistentry>
51323288fc628a5cac50914df915545d685b793eLennart Poettering <term><constant>-EINVAL</constant></term>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <listitem><para>Specified parameter is invalid.
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering </varlistentry>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <varlistentry>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering </varlistentry>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <varlistentry>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <term><constant>-ESTALE</constant></term>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <listitem><para>Message is in invalid state.
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering </varlistentry>
9d485985338a46b8cb1acdf1af6c1eb2e88acfeeLennart Poettering <varlistentry>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <listitem><para>Message cannot be appended to.
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering </varlistentry>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <varlistentry>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <term><constant>-ENOMEM</constant></term>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <listitem><para>Memory allocation failed.</para></listitem>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering </varlistentry>
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering </variablelist>
309e9d86f0e7f9c5f0a2a09227bdfdb3174d4436Lennart Poettering <para>The <function>sd_bus_append_basic()</function> function
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering described here is available as a shared library, which can be
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering compiled and linked to with the
4d1cf1e229c9bdbc44778c0863eaad918f5724e7Lennart Poettering <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
e70df46b9721a3d025e7a0b4ffb5893cbde5e55dLennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
e70df46b9721a3d025e7a0b4ffb5893cbde5e55dLennart Poettering <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
e70df46b9721a3d025e7a0b4ffb5893cbde5e55dLennart Poettering <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
e70df46b9721a3d025e7a0b4ffb5893cbde5e55dLennart Poettering <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink>