2014-03-07 08:24:20 +04:00
<?xml version='1.0'?> <!-- * - nxml - * -->
< !DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
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: / / w w w . g n u . o r g / l i c e n s e s /> .
-->
<refentry id= "sd_bus_message_append_basic" conditional= "ENABLE_KDBUS" >
<refentryinfo >
<title > sd_bus_message_append_basic</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_basic</refentrytitle>
<manvolnum > 3</manvolnum>
</refmeta>
<refnamediv >
<refname > sd_bus_message_append_basic</refname>
<refpurpose > Attach a single part to a message</refpurpose>
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcsynopsisinfo > #include < systemd/sd-bus.h> </funcsynopsisinfo>
<funcprototype >
<funcdef > int sd_bus_message_append_basic</funcdef>
<paramdef > sd_bus_message *<parameter > m</parameter> </paramdef>
<paramdef > char <parameter > type</parameter> </paramdef>
<paramdef > char void *<parameter > p</parameter> </paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 >
<title > Description</title>
<para > <function > sd_bus_message_append_basic</function> appends a
single item to the message <parameter > m</parameter> . Parameter
<parameter > type</parameter> determines how pointer
<parameter > p</parameter> is interpreted.
<parameter > type</parameter> must be one of the basic types
as defined by the
<ulink url= "http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types" > Basic Types</ulink>
section of the D-Bus specification, and listed in the table below.
</para>
<table id= 'format-specifiers' >
<title > Item format specifiers</title>
<tgroup cols= '4' >
<colspec colname= 'specifier' />
<colspec colname= 'constant' />
<colspec colname= 'description' />
<colspec colname= 'size' />
<thead >
<row >
<entry > Specifier</entry>
<entry > Constant</entry>
<entry > Description</entry>
<entry > Size</entry>
</row>
</thead>
<tbody >
<row >
<entry > <literal > y</literal> </entry>
<entry > <constant > SD_BUS_TYPE_BYTE</constant> </entry>
<entry > unsigned interger</entry>
<entry > 1 byte</entry>
</row>
<row >
<entry > <literal > b</literal> </entry>
<entry > <constant > SD_BUS_TYPE_BOOLEAN</constant> </entry>
<entry > boolean</entry>
<entry > 4 bytes</entry>
</row>
<row >
<entry > <literal > n</literal> </entry>
<entry > <constant > SD_BUS_TYPE_INT16</constant> </entry>
<entry > signed integer</entry>
<entry > 2 bytes</entry>
</row>
<row >
<entry > <literal > q</literal> </entry>
<entry > <constant > SD_BUS_TYPE_UINT16</constant> </entry>
<entry > unsigned integer</entry>
<entry > 2 bytes</entry>
</row>
<row >
<entry > <literal > i</literal> </entry>
<entry > <constant > SD_BUS_TYPE_INT32</constant> </entry>
<entry > signed integer</entry>
<entry > 4 bytes</entry>
</row>
<row >
<entry > <literal > u</literal> </entry>
<entry > <constant > SD_BUS_TYPE_UINT32</constant> </entry>
<entry > unsigned integer</entry>
<entry > 4 bytes</entry>
</row>
<row >
<entry > <literal > x</literal> </entry>
<entry > <constant > SD_BUS_TYPE_INT64</constant> </entry>
<entry > signed integer</entry>
<entry > 8 bytes</entry>
</row>
<row >
<entry > <literal > t</literal> </entry>
<entry > <constant > SD_BUS_TYPE_UINT64</constant> </entry>
<entry > unsigned integer</entry>
<entry > 8 bytes</entry>
</row>
<row >
<entry > <literal > d</literal> </entry>
<entry > <constant > SD_BUS_TYPE_DOUBLE</constant> </entry>
<entry > floating-point</entry>
<entry > 8 bytes</entry>
</row>
<row >
<entry > <literal > s</literal> </entry>
<entry > <constant > SD_BUS_TYPE_STRING</constant> </entry>
<entry > Unicode string</entry>
<entry > variable</entry>
</row>
<row >
<entry > <literal > o</literal> </entry>
<entry > <constant > SD_BUS_TYPE_OBJECT_PATH</constant> </entry>
<entry > object path</entry>
<entry > variable</entry>
</row>
<row >
<entry > <literal > g</literal> </entry>
<entry > <constant > SD_BUS_TYPE_SIGNATURE</constant> </entry>
<entry > signature</entry>
<entry > variable</entry>
</row>
<row >
<entry > <literal > h</literal> </entry>
<entry > <constant > SD_BUS_TYPE_UNIX_FD</constant> </entry>
<entry > UNIX file descriptor</entry>
<entry > 4 bytes</entry>
</row>
</tbody>
</tgroup>
</table>
<para > The value of the parameter is copied into the memory area
containing the message and may be changed after this call. If
<parameter > type</parameter> is <literal > h</literal> (UNIX file
descriptor), it is always "consumed" by this call, and either
successfully appended to the message or closed.</para>
<para > For types <literal > s</literal> , <literal > o</literal> , and
<literal > g</literal> , the parameter <parameter > p</parameter> is
interpreted as a pointer to a <constant > NUL</constant> -terminated
character sequence. As a special case, a <constant > NULL</constant>
pointer is interpreted as an empty string. The string should be
valid Unicode string encoded as UTF-8. In case of the two latter
2014-05-08 03:28:45 +04:00
types, the additional requirements for a D-Bus object path or
2014-03-07 08:24:20 +04:00
type signature should be satisfied. Those requirements should be
verified by the recepient of the message.
</para>
</refsect1>
<refsect1 >
<title > Return Value</title>
<para > On success, this call returns 0 or a positive integer. On
failure, it returns a negative errno-style error code.</para>
</refsect1>
<refsect1 id= 'errors' >
<title > Errors</title>
<para > Returned errors may indicate the following problems:</para>
<variablelist >
<varlistentry >
<term > <varname > -EINVAL</varname> </term>
<listitem > <para > Specified parameter is invalid.
</para> </listitem>
</varlistentry>
<varlistentry >
<term > <varname > -EPERM</varname> </term>
<listitem > <para > Message has been sealed.
</para> </listitem>
</varlistentry>
<varlistentry >
<term > <varname > -ESTALE</varname> </term>
<listitem > <para > Message is in invalid state.
</para> </listitem>
</varlistentry>
<varlistentry >
<term > <varname > -ENXIO</varname> </term>
<listitem > <para > Message cannot be appended to.
</para> </listitem>
</varlistentry>
<varlistentry >
<term > <varname > -ENOMEM</varname> </term>
<listitem > <para > Memory allocation failed.</para> </listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 >
<title > Notes</title>
2014-05-08 03:28:45 +04:00
<para > The <function > sd_bus_append_basic()</function> function
2014-03-07 08:24:20 +04:00
described here is available as a shared library, which can be
compiled and linked to with the
<constant > libsystemd</constant> <citerefentry > <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</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
<ulink url= "http://dbus.freedesktop.org/doc/dbus-specification.html" > The D-Bus specification</ulink>
</para>
</refsect1>
</refentry>
