sd_bus_message_get_cookie.xml revision 7c071fda945a8f9e3b11d37dc04c8bdfa615d44a
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd This file is part of systemd.
3f08db06526d6901aa08c110b5bc7dde6bc39905nd Copyright 2013 Lennart Poettering
7add1372edb1ee95a2c4d1314df4c7567bda7c62jim systemd is free software; you can redistribute it and/or modify it
7add1372edb1ee95a2c4d1314df4c7567bda7c62jim under the terms of the GNU Lesser General Public License as published by
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen the Free Software Foundation; either version 2.1 of the License, or
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen (at your option) any later version.
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen systemd is distributed in the hope that it will be useful, but
7add1372edb1ee95a2c4d1314df4c7567bda7c62jim WITHOUT ANY WARRANTY; without even the implied warranty of
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd Lesser General Public License for more details.
3f08db06526d6901aa08c110b5bc7dde6bc39905nd You should have received a copy of the GNU Lesser General Public License
7add1372edb1ee95a2c4d1314df4c7567bda7c62jim along with systemd; If not, see <http://www.gnu.org/licenses/>.
4b5981e276e93df97c34e4da05ca5cf8bbd937dand<refentry id="sd_bus_message_get_cookie" conditional="ENABLE_KDBUS">
6df89e6e4adeb986b41b7ec6b7593a887e031ce7nd <refentryinfo>
7add1372edb1ee95a2c4d1314df4c7567bda7c62jim <authorgroup>
d474d8ef01ec5c2a09341cd148851ed383c3287crbowen </authorgroup>
3b3b7fc78d1f5bfc2769903375050048ff41ff26nd </refentryinfo>
a29610af88e278144045bfa1bc63b4a1a4b5ff14trawick <refentrytitle>sd_bus_message_get_cookie</refentrytitle>
a12dd6260a66f51e25119982390def72e2db4be5nd <refnamediv>
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd <refpurpose>Returns the transaction cookie of a message</refpurpose>
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd </refnamediv>
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen <refsynopsisdiv>
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd <funcsynopsis>
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd <funcprototype>
63581ee088272ef76aa8d053609dc1705c222deesf <funcdef>int <function>sd_bus_message_get_cookie</function></funcdef>
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd <paramdef>sd_bus_message* <parameter>message</parameter></paramdef>
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd <paramdef>uint64_t* <parameter>cookie</parameter></paramdef>
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd </funcprototype>
562b6e25d7f0ca73dca724b09b555a91399448d5rbowen <funcprototype>
562b6e25d7f0ca73dca724b09b555a91399448d5rbowen <funcdef>int <function>sd_bus_message_get_reply_cookie</function></funcdef>
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd <paramdef>sd_bus_message* <parameter>message</parameter></paramdef>
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd <paramdef>uint64_t* <parameter>cookie</parameter></paramdef>
4af55bbfdbff2cae0cd3195876c93ea991523d1fcolm </funcprototype>
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd </funcsynopsis>
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd </refsynopsisdiv>
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd <refsect1>
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd <para><function>sd_bus_message_get_cookie()</function> returns
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd the transaction cookie of a message. The cookie
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd uniquely identifies a message within each bus peer,
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd but is not globally unique. It is assigned when a
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd message is sent.</para>
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd <para><function>sd_bus_message_get_reply_cookie()</function>
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd returns the transaction cookie of the message the
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd specified message is a response to. When a reply
1844bb5f7939bd31f51dffaf8d8cf1c00657a681rbowen message is generated for a method call message, its
1844bb5f7939bd31f51dffaf8d8cf1c00657a681rbowen cookie is copied over into this field. Note that while
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd every message that is transferred is identified by a
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd cookie, only response messages carry a reply cookie
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd field.</para>
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd <para>Both functions take a message object as first
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd parameter and a place to store the 64-bit cookie
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd in.</para>
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd </refsect1>
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd <refsect1>
c5ac4f57bfd156a62495b9c6a049f05bbcb69acarbowen <para>On success, these calls return 0 or a positive
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd integer. On failure, these calls return a negative
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd errno-style error code.</para>
e930328445e961ade1bd37ed7ca01c293b586400noodl in the specified 64-bit unsigned integer variable.</para>
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd </refsect1>
3b3b7fc78d1f5bfc2769903375050048ff41ff26nd <refsect1>
7add1372edb1ee95a2c4d1314df4c7567bda7c62jim <para>Returned errors may indicate the following problems:</para>
7add1372edb1ee95a2c4d1314df4c7567bda7c62jim <variablelist>
7f5b59ccc63c0c0e3e678a168f09ee6a2f51f9d0nd <varlistentry>
3b3b7fc78d1f5bfc2769903375050048ff41ff26nd </varlistentry>
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen <varlistentry>
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd assigned to this message. This either
29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd indicates that the message has not