Merge pull request #15569 from DaanDeMeyer/sd-bus-message-peek-type-docs

1 files changed, 44 insertions, 34 deletions

diff --git a/man/sd_bus_message_read.xml b/man/sd_bus_message_read.xml
index a716660a2c..1b9f36cd84 100644
--- a/man/sd_bus_message_read.xml
+++ b/man/sd_bus_message_read.xml
@@ -19,6 +19,7 @@
   <refnamediv>
     <refname>sd_bus_message_read</refname>
     <refname>sd_bus_message_readv</refname>
+    <refname>sd_bus_message_peek_type</refname>
 
     <refpurpose>Read a sequence of values from a message</refpurpose>
   </refnamediv>
@@ -40,38 +41,42 @@
         <paramdef>const char *<parameter>types</parameter></paramdef>
         <paramdef>va_list <parameter>ap</parameter></paramdef>
       </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_message_peek_type</function></funcdef>
+        <paramdef>char *<parameter>type</parameter></paramdef>
+        <paramdef>const char **<parameter>contents</parameter></paramdef>
+      </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>
 
   <refsect1>
     <title>Description</title>
 
-    <para><function>sd_bus_message_read()</function> reads a sequence of fields from
-    the D-Bus message object <parameter>m</parameter> and advances the read position
-    in the message. The type string <parameter>types</parameter> describes the types
-    of items expected in the message and the field arguments that follow. The type
-    string may be <constant>NULL</constant> or empty, in which case nothing is
-    read.</para>
+    <para><function>sd_bus_message_read()</function> reads a sequence of fields from the D-Bus message object
+    <parameter>m</parameter> and advances the read position in the message. The type string
+    <parameter>types</parameter> describes the types of items expected in the message and the field arguments
+    that follow. The type string may be <constant>NULL</constant> or empty, in which case nothing is read.
+    </para>
 
     <para>The type string is composed of the elements described in
     <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
-    i.e. basic and container types. It must contain zero or more single "complete
-    types". The type string is <constant>NUL</constant>-terminated.</para>
-
-    <para>For each type specified in the type string, one or more arguments need to be specified
-    after the <parameter>types</parameter> parameter, in the same order. The arguments must be
-    pointers to appropriate types (a pointer to <type>int8_t</type> for a <literal>y</literal> in
-    the type string, a pointer to <type>int32_t</type> for an <literal>i</literal>, a pointer to
-    <type>const char*</type> for an <literal>s</literal>, ...)  which are set based on the values in
-    the message. As an exception, in case of array and variant types, the first argument is an
-    "input" argument that further specifies how the message should be read. See the table below for
-    a complete list of allowed arguments and their types. Note that, if the basic type is a pointer
-    (e.g., <type>const char *</type> in the case of a string), the argument is a pointer to a
-    pointer, and also the pointer value that is written is only borrowed and the contents must be
-    copied if they are to be used after the end of the messages lifetime.</para>
-
-    <para>Each argument may also be <constant>NULL</constant>, in which case the value is read and
-    ignored.</para>
+    i.e. basic and container types. It must contain zero or more single "complete types". The type string is
+    <constant>NUL</constant>-terminated.</para>
+
+    <para>For each type specified in the type string, one or more arguments need to be specified after the
+    <parameter>types</parameter> parameter, in the same order. The arguments must be pointers to appropriate
+    types (a pointer to <type>int8_t</type> for a <literal>y</literal> in the type string, a pointer to
+    <type>int32_t</type> for an <literal>i</literal>, a pointer to <type>const char*</type> for an
+    <literal>s</literal>, ...)  which are set based on the values in the message. As an exception, in case of
+    array and variant types, the first argument is an "input" argument that further specifies how the message
+    should be read. See the table below for a complete list of allowed arguments and their types. Note that,
+    if the basic type is a pointer (e.g., <type>const char *</type> in the case of a string), the argument is
+    a pointer to a pointer, and also the pointer value that is written is only borrowed and the contents must
+    be copied if they are to be used after the end of the messages lifetime.</para>
+
+    <para>Each argument may also be <constant>NULL</constant>, in which case the value is read and ignored.
+    </para>
 
     <table>
       <title>Item type specifiers</title>
@@ -139,24 +144,29 @@
       </tgroup>
     </table>
 
-    <para>If objects of the specified types are not present at the current position
-    in the message, an error is returned.
-    </para>
+    <para>If objects of the specified types are not present at the current position in the message, an error
+    is returned.</para>
 
     <para>The <function>sd_bus_message_readv()</function> is equivalent to the
-    <function>sd_bus_message_read()</function>, except that it is called with a
-    <literal>va_list</literal> instead of a variable number of arguments. This
-    function does not call the <function>va_end()</function> macro. Because it
-    invokes the <function>va_arg()</function> macro, the value of
-    <parameter>ap</parameter> is undefined after the call.</para>
+    <function>sd_bus_message_read()</function>, except that it is called with a <literal>va_list</literal>
+    instead of a variable number of arguments. This function does not call the <function>va_end()</function>
+    macro. Because it invokes the <function>va_arg()</function> macro, the value of <parameter>ap</parameter>
+    is undefined after the call.</para>
+
+    <para><function>sd_bus_message_peek_type()</function> determines the type of the next element in
+    <parameter>m</parameter> to be read by <function>sd_bus_message_read()</function> or similar functions.
+    On success, the type is stored in <parameter>type</parameter>, if it is not <constant>NULL</constant>.
+    If the type is a container type, the type of its elements is stored in <parameter>contents</parameter>,
+    if it is not <constant>NULL</constant>. If this function successfully determines the type of the next
+    element in <parameter>m</parameter>, it returns a positive integer. If there are no more elements to be
+    read, it returns zero.</para>
   </refsect1>
 
   <refsect1>
     <title>Return Value</title>
 
-    <para>On success, <function>sd_bus_message_read()</function> and
-    <function>sd_bus_message_readv()</function> return 0 or a positive integer. On failure, they return a
-    negative errno-style error code.</para>
+    <para>On success, these functions return a non-negative integer. On failure, they return a negative
+    errno-style error code.</para>
 
     <xi:include href="sd_bus_message_read_basic.xml" xpointer="errors" />
   </refsect1>