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