sd_bus_message_get_cookie.xml revision 8474b70c3a3842cdf3d51f331dd117ab6421f6d0
eac684ef1c29684b1bcd27a89c38c202e568e469Tom Gundersen<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
eac684ef1c29684b1bcd27a89c38c202e568e469Tom Gundersen This file is part of systemd.
eac684ef1c29684b1bcd27a89c38c202e568e469Tom Gundersen Copyright 2013 Lennart Poettering
eac684ef1c29684b1bcd27a89c38c202e568e469Tom Gundersen systemd is free software; you can redistribute it and/or modify it
eac684ef1c29684b1bcd27a89c38c202e568e469Tom Gundersen under the terms of the GNU Lesser General Public License as published by
eac684ef1c29684b1bcd27a89c38c202e568e469Tom Gundersen the Free Software Foundation; either version 2.1 of the License, or
eac684ef1c29684b1bcd27a89c38c202e568e469Tom Gundersen (at your option) any later version.
eac684ef1c29684b1bcd27a89c38c202e568e469Tom Gundersen systemd is distributed in the hope that it will be useful, but
eac684ef1c29684b1bcd27a89c38c202e568e469Tom Gundersen WITHOUT ANY WARRANTY; without even the implied warranty of
eac684ef1c29684b1bcd27a89c38c202e568e469Tom Gundersen MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
eac684ef1c29684b1bcd27a89c38c202e568e469Tom Gundersen Lesser General Public License for more details.
eac684ef1c29684b1bcd27a89c38c202e568e469Tom Gundersen You should have received a copy of the GNU Lesser General Public License
eac684ef1c29684b1bcd27a89c38c202e568e469Tom Gundersen along with systemd; If not, see <http://www.gnu.org/licenses/>.
eac684ef1c29684b1bcd27a89c38c202e568e469Tom Gundersen<refentry id="sd_bus_message_get_cookie" conditional="ENABLE_KDBUS">
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <title>sd_bus_message_get_cookie</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <productname>systemd</productname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <email>lennart@poettering.net</email>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refentrytitle>sd_bus_message_get_cookie</refentrytitle>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>sd_bus_message_get_cookie</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>sd_bus_message_get_reply_cookie</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refpurpose>Returns the transaction cookie of a message</refpurpose>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_bus_message_get_cookie</function></funcdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>uint64_t *<parameter>cookie</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </funcprototype>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_bus_message_get_reply_cookie</function></funcdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>uint64_t *<parameter>cookie</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </funcprototype>
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen </refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><function>sd_bus_message_get_cookie()</function> returns
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the transaction cookie of a message. The cookie
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek uniquely identifies a message within each bus peer,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek but is not globally unique. It is assigned when a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek message is sent.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><function>sd_bus_message_get_reply_cookie()</function>
57e27ec0ada6775d85a5201cd25e989d92d0a1afZbigniew Jędrzejewski-Szmek returns the transaction cookie of the message the
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt specified message is a response to. When a reply
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt message is generated for a method call message, its
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek cookie is copied over into this field. Note that while
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek every message that is transferred is identified by a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek cookie, only response messages carry a reply cookie
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Both functions take a message object as first
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek parameter and a place to store the 64-bit cookie
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>On success, these calls return 0 or a positive
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek integer. On failure, these calls return a negative
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek errno-style error code.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>On success, the cookie/reply cookie is returned
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek in the specified 64-bit unsigned integer variable.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Returned errors may indicate the following problems:</para>
5256e00e8b9015dd1a976d647fc71dc7efbd8cf8Tom Gundersen <varlistentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>A specified parameter
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>No cookie has been
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek assigned to this message. This either
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek indicates that the message has not
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek been sent yet and hence has no cookie
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek assigned, or that the message is not a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek method response message and hence
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek carries a reply cookie
5256e00e8b9015dd1a976d647fc71dc7efbd8cf8Tom Gundersen </variablelist>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The <function>sd_bus_message_get_cookie()</function>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek and <function>sd_bus_message_get_reply_cookie()</function>
5256e00e8b9015dd1a976d647fc71dc7efbd8cf8Tom Gundersen interfaces are available as a shared library, which can
5256e00e8b9015dd1a976d647fc71dc7efbd8cf8Tom Gundersen be compiled and linked to with the
5256e00e8b9015dd1a976d647fc71dc7efbd8cf8Tom Gundersen <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>