man/sd_bus_process.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   This file is part of elogind.
   7
   8   Copyright 2016 Julian Orth
   9
  10   elogind is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   elogind is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with elogind; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="sd_bus_process">
  25
  26   <refentryinfo>
  27     <title>sd_bus_process</title>
  28     <productname>elogind</productname>
  29
  30     <authorgroup>
  31       <author>
  32         <firstname>Julian</firstname>
  33         <surname>Orth</surname>
  34         <email>ju.orth@gmail.com</email>
  35       </author>
  36     </authorgroup>
  37   </refentryinfo>
  38
  39   <refmeta>
  40     <refentrytitle>sd_bus_process</refentrytitle>
  41     <manvolnum>3</manvolnum>
  42   </refmeta>
  43
  44   <refnamediv>
  45     <refname>sd_bus_process</refname>
  46
  47     <refpurpose>Drive the connection</refpurpose>
  48   </refnamediv>
  49
  50   <refsynopsisdiv>
  51     <funcsynopsis>
  52       <funcsynopsisinfo>#include &lt;elogind/sd-bus.h&gt;</funcsynopsisinfo>
  53
  54       <funcprototype>
  55         <funcdef>int <function>sd_bus_process</function></funcdef>
  56         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  57         <paramdef>sd_bus_message **<parameter>r</parameter></paramdef>
  58       </funcprototype>
  59     </funcsynopsis>
  60   </refsynopsisdiv>
  61
  62   <refsect1>
  63     <title>Description</title>
  64
  65     <para>
  66       <function>sd_bus_process()</function> drives the connection between the
  67       message bus and the client. That is, it handles connecting,
  68       authentication, and message processing. It should be called in a loop
  69       until no further progress can be made or an error occurs.
  70     </para>
  71
  72     <para>
  73       Once no further progress can be made,
  74       <citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  75       should be called. Alternatively the user can wait for incoming data on
  76       the file descriptor returned by
  77       <citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  78     </para>
  79
  80     <para>
  81       <function>sd_bus_process</function> processes at most one incoming
  82       message per call.  If the parameter <parameter>r</parameter> is not NULL
  83       and the call processed a message, <code>*r</code> is set to this message.
  84       The caller owns a reference to this message and should call
  85       <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  86       when the message is no longer needed. If <parameter>r</parameter> is not
  87       NULL, progress was made, but no message was processed, <code>*r</code> is
  88       set to NULL.
  89     </para>
  90   </refsect1>
  91
  92   <refsect1>
  93     <title>Return Value</title>
  94
  95     <para>
  96       If progress was made, a positive integer is returned. If no progress was
  97       made, 0 is returned. If an error occurs, a negative errno-style error code
  98       is returned.
  99     </para>
 100   </refsect1>
 101
 102   <refsect1>
 103     <title>See Also</title>
 104
 105     <para>
 106       <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 107       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 108     </para>
 109   </refsect1>
 110
 111 </refentry>