sd_bus_message_get_cookie.xml revision 99e0f83e0bcc54dbc2b3a4f3fdd15fcd3033b21e
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/>.
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
99e0f83e0bcc54dbc2b3a4f3fdd15fcd3033b21eLennart Poettering 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
99e0f83e0bcc54dbc2b3a4f3fdd15fcd3033b21eLennart Poettering parameter and a place to store the 64bit 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>
99e0f83e0bcc54dbc2b3a4f3fdd15fcd3033b21eLennart Poettering <para>On success the cookie/reply cookie is returned
99e0f83e0bcc54dbc2b3a4f3fdd15fcd3033b21eLennart Poettering in the specified 64bit 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
99e0f83e0bcc54dbc2b3a4f3fdd15fcd3033b21eLennart Poettering carries to 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>
99e0f83e0bcc54dbc2b3a4f3fdd15fcd3033b21eLennart Poettering interfaces are available as shared library, which can
99e0f83e0bcc54dbc2b3a4f3fdd15fcd3033b21eLennart Poettering be compiled and linked to with the
99e0f83e0bcc54dbc2b3a4f3fdd15fcd3033b21eLennart Poettering <constant>libsystemd-bus</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>