chiark / gitweb /
util: make http url validity checks more generic, and move them to util.c
[elogind.git] / man / sd_bus_message_get_cookie.xml
1 <?xml version='1.0'?> <!--*-nxml-*-->
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 2013 Lennart Poettering
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_get_cookie" conditional="ENABLE_KDBUS">
25
26         <refentryinfo>
27                 <title>sd_bus_message_get_cookie</title>
28                 <productname>systemd</productname>
29
30                 <authorgroup>
31                         <author>
32                                 <contrib>Developer</contrib>
33                                 <firstname>Lennart</firstname>
34                                 <surname>Poettering</surname>
35                                 <email>lennart@poettering.net</email>
36                         </author>
37                 </authorgroup>
38         </refentryinfo>
39
40         <refmeta>
41                 <refentrytitle>sd_bus_message_get_cookie</refentrytitle>
42                 <manvolnum>3</manvolnum>
43         </refmeta>
44
45         <refnamediv>
46                 <refname>sd_bus_message_get_cookie</refname>
47                 <refname>sd_bus_message_get_reply_cookie</refname>
48                 <refpurpose>Returns the transaction cookie of 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 <function>sd_bus_message_get_cookie</function></funcdef>
57                                 <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
58                                 <paramdef>uint64_t *<parameter>cookie</parameter></paramdef>
59                         </funcprototype>
60
61                         <funcprototype>
62                                 <funcdef>int <function>sd_bus_message_get_reply_cookie</function></funcdef>
63                                 <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
64                                 <paramdef>uint64_t *<parameter>cookie</parameter></paramdef>
65                         </funcprototype>
66                 </funcsynopsis>
67         </refsynopsisdiv>
68
69         <refsect1>
70                 <title>Description</title>
71
72                 <para><function>sd_bus_message_get_cookie()</function> returns
73                 the transaction cookie of a message. The cookie
74                 uniquely identifies a message within each bus peer,
75                 but is not globally unique. It is assigned when a
76                 message is sent.</para>
77
78                 <para><function>sd_bus_message_get_reply_cookie()</function>
79                 returns the transaction cookie of the message the
80                 specified message is a response to. When a reply
81                 message is generated for a method call message, its
82                 cookie is copied over into this field. Note that while
83                 every message that is transferred is identified by a
84                 cookie, only response messages carry a reply cookie
85                 field.</para>
86
87                 <para>Both functions take a message object as first
88                 parameter and a place to store the 64-bit cookie
89                 in.</para>
90         </refsect1>
91
92         <refsect1>
93                 <title>Return Value</title>
94
95                 <para>On success, these calls return 0 or a positive
96                 integer. On failure, these calls return a negative
97                 errno-style error code.</para>
98
99                 <para>On success, the cookie/reply cookie is returned
100                 in the specified 64-bit unsigned integer variable.</para>
101         </refsect1>
102
103         <refsect1>
104                 <title>Errors</title>
105
106                 <para>Returned errors may indicate the following problems:</para>
107
108                 <variablelist>
109                         <varlistentry>
110                                 <term><constant>-EINVAL</constant></term>
111
112                                 <listitem><para>A specified parameter
113                                 is invalid.</para></listitem>
114                         </varlistentry>
115
116                         <varlistentry>
117                                 <term><constant>-ENODATA</constant></term>
118
119                                 <listitem><para>No cookie has been
120                                 assigned to this message. This either
121                                 indicates that the message has not
122                                 been sent yet and hence has no cookie
123                                 assigned, or that the message is not a
124                                 method response message and hence
125                                 carries a reply cookie
126                                 field.</para></listitem>
127                         </varlistentry>
128                 </variablelist>
129         </refsect1>
130
131         <refsect1>
132                 <title>Notes</title>
133
134                 <para>The <function>sd_bus_message_get_cookie()</function>
135                 and <function>sd_bus_message_get_reply_cookie()</function>
136                 interfaces are available as a shared library, which can
137                 be compiled and linked to with the
138                 <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
139                 file.</para>
140         </refsect1>
141
142         <refsect1>
143                 <title>See Also</title>
144
145                 <para>
146                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
147                         <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
148                         <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
149                 </para>
150         </refsect1>
151
152 </refentry>