1<?xml version='1.0'?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
5
6<refentry id="sd_bus_message_seal"
7          xmlns:xi="http://www.w3.org/2001/XInclude">
8
9  <refentryinfo>
10    <title>sd_bus_message_seal</title>
11    <productname>systemd</productname>
12  </refentryinfo>
13
14  <refmeta>
15    <refentrytitle>sd_bus_message_seal</refentrytitle>
16    <manvolnum>3</manvolnum>
17  </refmeta>
18
19  <refnamediv>
20    <refname>sd_bus_message_seal</refname>
21
22    <refpurpose>Prepare a D-Bus message for transmission</refpurpose>
23  </refnamediv>
24
25  <refsynopsisdiv>
26    <funcsynopsis>
27      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
28
29      <funcprototype>
30        <funcdef>int <function>sd_bus_message_seal</function></funcdef>
31        <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
32        <paramdef>uint64_t <parameter>cookie</parameter></paramdef>
33        <paramdef>uint64_t <parameter>timeout_usec</parameter></paramdef>
34      </funcprototype>
35    </funcsynopsis>
36  </refsynopsisdiv>
37
38  <refsect1>
39    <title>Description</title>
40
41    <para><function>sd_bus_message_seal()</function> finishes the message <parameter>m</parameter>
42    and prepares it for transmission using
43    <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
44    <parameter>cookie</parameter> specifies the identifier used to match the message reply to its
45    corresponding request. <parameter>timeout_usec</parameter> specifies the maximum time in
46    microseconds to wait for a reply to arrive.</para>
47
48    <para>Note that in most scenarios, it's not necessary to call this function directly.
49    <citerefentry><refentrytitle>sd_bus_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
50    <citerefentry><refentrytitle>sd_bus_call_async</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
51    <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>
52    will seal any given messages if they have not been sealed yet.</para>
53  </refsect1>
54
55  <refsect1>
56    <title>Return Value</title>
57
58    <para>On success, this function returns a non-negative integer. On failure, it returns a
59    negative errno-style error code.</para>
60
61    <refsect2>
62      <title>Errors</title>
63
64      <para>Returned errors may indicate the following problems:</para>
65
66      <variablelist>
67        <varlistentry>
68          <term><constant>-EINVAL</constant></term>
69
70          <listitem><para>The <parameter>m</parameter> parameter is <constant>NULL</constant>.
71          </para></listitem>
72        </varlistentry>
73
74         <varlistentry>
75          <term><constant>-EBADMSG</constant></term>
76
77          <listitem><para>The D-Bus message <parameter>m</parameter> has open containers.
78          </para></listitem>
79        </varlistentry>
80
81        <varlistentry>
82          <term><constant>-ENOMSG</constant></term>
83
84          <listitem><para>The D-Bus message <parameter>m</parameter> is a reply but its type
85          signature does not match the return type signature of its corresponding member in the
86          object vtable.</para></listitem>
87        </varlistentry>
88      </variablelist>
89    </refsect2>
90  </refsect1>
91
92  <xi:include href="libsystemd-pkgconfig.xml" />
93
94  <refsect1>
95    <title>See Also</title>
96
97    <para>
98      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
99      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
100      <citerefentry><refentrytitle>sd_bus_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
101      <citerefentry><refentrytitle>sd_bus_call_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
102      <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>
103    </para>
104  </refsect1>
105
106</refentry>
107