chiark / gitweb /
util: make http url validity checks more generic, and move them to util.c
[elogind.git] / man / sd_bus_message_append_basic.xml
1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <!--
6 This file is part of systemd.
7
8 Copyright 2014 Zbigniew Jędrzejewski-Szmek
9
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
14
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
19
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
22 -->
23
24 <refentry id="sd_bus_message_append_basic" conditional="ENABLE_KDBUS">
25
26   <refentryinfo>
27     <title>sd_bus_message_append_basic</title>
28     <productname>systemd</productname>
29
30     <authorgroup>
31       <author>
32         <contrib>A monkey with a typewriter</contrib>
33         <firstname>Zbigniew</firstname>
34         <surname>Jędrzejewski-Szmek</surname>
35         <email>zbyszek@in.waw.pl</email>
36       </author>
37     </authorgroup>
38   </refentryinfo>
39
40   <refmeta>
41     <refentrytitle>sd_bus_message_append_basic</refentrytitle>
42     <manvolnum>3</manvolnum>
43   </refmeta>
44
45   <refnamediv>
46     <refname>sd_bus_message_append_basic</refname>
47
48     <refpurpose>Attach a single part to a message</refpurpose>
49   </refnamediv>
50
51   <refsynopsisdiv>
52     <funcsynopsis>
53       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
54
55       <funcprototype>
56         <funcdef>int sd_bus_message_append_basic</funcdef>
57         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
58         <paramdef>char <parameter>type</parameter></paramdef>
59         <paramdef>char void *<parameter>p</parameter></paramdef>
60       </funcprototype>
61     </funcsynopsis>
62   </refsynopsisdiv>
63
64   <refsect1>
65     <title>Description</title>
66
67     <para><function>sd_bus_message_append_basic</function> appends a
68     single item to the message <parameter>m</parameter>. Parameter
69     <parameter>type</parameter> determines how pointer
70     <parameter>p</parameter> is interpreted.
71     <parameter>type</parameter> must be one of the basic types
72     as defined by the
73
74     <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types">Basic Types</ulink>
75     section of the D-Bus specification, and listed in the table below.
76     </para>
77
78     <table id='format-specifiers'>
79       <title>Item format specifiers</title>
80
81       <tgroup cols='4'>
82         <colspec colname='specifier' />
83         <colspec colname='constant' />
84         <colspec colname='description' />
85         <colspec colname='size' />
86         <thead>
87           <row>
88             <entry>Specifier</entry>
89             <entry>Constant</entry>
90             <entry>Description</entry>
91             <entry>Size</entry>
92           </row>
93         </thead>
94         <tbody>
95           <row>
96             <entry><literal>y</literal></entry>
97             <entry><constant>SD_BUS_TYPE_BYTE</constant></entry>
98             <entry>unsigned integer</entry>
99             <entry>1 byte</entry>
100           </row>
101
102           <row>
103             <entry><literal>b</literal></entry>
104             <entry><constant>SD_BUS_TYPE_BOOLEAN</constant></entry>
105             <entry>boolean</entry>
106             <entry>4 bytes</entry>
107           </row>
108
109           <row>
110             <entry><literal>n</literal></entry>
111             <entry><constant>SD_BUS_TYPE_INT16</constant></entry>
112             <entry>signed integer</entry>
113             <entry>2 bytes</entry>
114           </row>
115
116           <row>
117             <entry><literal>q</literal></entry>
118             <entry><constant>SD_BUS_TYPE_UINT16</constant></entry>
119             <entry>unsigned integer</entry>
120             <entry>2 bytes</entry>
121           </row>
122
123           <row>
124             <entry><literal>i</literal></entry>
125             <entry><constant>SD_BUS_TYPE_INT32</constant></entry>
126             <entry>signed integer</entry>
127             <entry>4 bytes</entry>
128           </row>
129
130           <row>
131             <entry><literal>u</literal></entry>
132             <entry><constant>SD_BUS_TYPE_UINT32</constant></entry>
133             <entry>unsigned integer</entry>
134             <entry>4 bytes</entry>
135           </row>
136
137           <row>
138             <entry><literal>x</literal></entry>
139             <entry><constant>SD_BUS_TYPE_INT64</constant></entry>
140             <entry>signed integer</entry>
141             <entry>8 bytes</entry>
142           </row>
143
144           <row>
145             <entry><literal>t</literal></entry>
146             <entry><constant>SD_BUS_TYPE_UINT64</constant></entry>
147             <entry>unsigned integer</entry>
148             <entry>8 bytes</entry>
149           </row>
150
151           <row>
152             <entry><literal>d</literal></entry>
153             <entry><constant>SD_BUS_TYPE_DOUBLE</constant></entry>
154             <entry>floating-point</entry>
155             <entry>8 bytes</entry>
156           </row>
157
158           <row>
159             <entry><literal>s</literal></entry>
160             <entry><constant>SD_BUS_TYPE_STRING</constant></entry>
161             <entry>Unicode string</entry>
162             <entry>variable</entry>
163           </row>
164
165           <row>
166             <entry><literal>o</literal></entry>
167             <entry><constant>SD_BUS_TYPE_OBJECT_PATH</constant></entry>
168             <entry>object path</entry>
169             <entry>variable</entry>
170           </row>
171
172           <row>
173             <entry><literal>g</literal></entry>
174             <entry><constant>SD_BUS_TYPE_SIGNATURE</constant></entry>
175             <entry>signature</entry>
176             <entry>variable</entry>
177           </row>
178
179           <row>
180             <entry><literal>h</literal></entry>
181             <entry><constant>SD_BUS_TYPE_UNIX_FD</constant></entry>
182             <entry>UNIX file descriptor</entry>
183             <entry>4 bytes</entry>
184           </row>
185        </tbody>
186       </tgroup>
187     </table>
188
189     <para>The value of the parameter is copied into the memory area
190     containing the message and may be changed after this call. If
191     <parameter>type</parameter> is <literal>h</literal> (UNIX file
192     descriptor), it is always "consumed" by this call, and either
193     successfully appended to the message or closed.</para>
194
195     <para>For types <literal>s</literal>, <literal>o</literal>, and
196     <literal>g</literal>, the parameter <parameter>p</parameter> is
197     interpreted as a pointer to a <constant>NUL</constant>-terminated
198     character sequence. As a special case, a <constant>NULL</constant>
199     pointer is interpreted as an empty string. The string should be
200     valid Unicode string encoded as UTF-8. In case of the two latter
201     types, the additional requirements for a D-Bus object path or
202     type signature should be satisfied. Those requirements should be
203     verified by the recipient of the message.
204     </para>
205   </refsect1>
206
207   <refsect1>
208     <title>Return Value</title>
209
210     <para>On success, this call returns 0 or a positive integer. On
211     failure, it returns a negative errno-style error code.</para>
212   </refsect1>
213
214   <refsect1 id='errors'>
215     <title>Errors</title>
216
217     <para>Returned errors may indicate the following problems:</para>
218
219     <variablelist>
220
221       <varlistentry>
222         <term><constant>-EINVAL</constant></term>
223
224         <listitem><para>Specified parameter is invalid.
225         </para></listitem>
226       </varlistentry>
227
228       <varlistentry>
229         <term><constant>-EPERM</constant></term>
230
231         <listitem><para>Message has been sealed.
232         </para></listitem>
233       </varlistentry>
234
235       <varlistentry>
236         <term><constant>-ESTALE</constant></term>
237
238         <listitem><para>Message is in invalid state.
239         </para></listitem>
240       </varlistentry>
241
242       <varlistentry>
243         <term><constant>-ENXIO</constant></term>
244
245         <listitem><para>Message cannot be appended to.
246         </para></listitem>
247       </varlistentry>
248
249       <varlistentry>
250         <term><constant>-ENOMEM</constant></term>
251
252         <listitem><para>Memory allocation failed.</para></listitem>
253       </varlistentry>
254     </variablelist>
255   </refsect1>
256
257   <refsect1>
258     <title>Notes</title>
259
260     <para>The <function>sd_bus_append_basic()</function> function
261     described here is available as a shared library, which can be
262     compiled and linked to with the
263     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
264     file.</para>
265   </refsect1>
266
267   <refsect1>
268     <title>See Also</title>
269
270     <para>
271       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
272       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
273       <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
274       <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink>
275     </para>
276   </refsect1>
277
278 </refentry>