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

man/rules/meson.build

@@ -325,7 +325,10 @@ manpages = [
    'sd_bus_message_enter_container',
    'sd_bus_message_exit_container'],
   ''],
- ['sd_bus_message_read', '3', ['sd_bus_message_readv'], ''],
+ ['sd_bus_message_read',
+  '3',
+  ['sd_bus_message_peek_type', 'sd_bus_message_readv'],
+  ''],
  ['sd_bus_message_read_array', '3', [], ''],
  ['sd_bus_message_read_basic', '3', [], ''],
  ['sd_bus_message_read_strv', '3', [], ''],

man/sd-bus.xml

@@ -117,6 +117,7 @@
 <citerefentry><refentrytitle>sd_bus_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_message_new_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_message_open_container</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_message_peek_type</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_message_read_array</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_message_read_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

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
+    <para><function>sd_bus_message_read()</function> reads a sequence of fields from the D-Bus message object
-    the D-Bus message object <parameter>m</parameter> and advances the read position
+    <parameter>m</parameter> and advances the read position in the message. The type string
-    in the message. The type string <parameter>types</parameter> describes the types
+    <parameter>types</parameter> describes the types of items expected in the message and the field arguments
-    of items expected in the message and the field arguments that follow. The type
+    that follow. The type string may be <constant>NULL</constant> or empty, in which case nothing is read.
-    string may be <constant>NULL</constant> or empty, in which case nothing is
+    </para>
-    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
+    i.e. basic and container types. It must contain zero or more single "complete types". The type string is
-    types". The type string is <constant>NUL</constant>-terminated.</para>
+    <constant>NUL</constant>-terminated.</para>
 
-    <para>For each type specified in the type string, one or more arguments need to be specified
+    <para>For each type specified in the type string, one or more arguments need to be specified after the
-    after the <parameter>types</parameter> parameter, in the same order. The arguments must be
+    <parameter>types</parameter> parameter, in the same order. The arguments must be pointers to appropriate
-    pointers to appropriate types (a pointer to <type>int8_t</type> for a <literal>y</literal> in
+    types (a pointer to <type>int8_t</type> for a <literal>y</literal> in the type string, a pointer to
-    the type string, a pointer to <type>int32_t</type> for an <literal>i</literal>, a pointer to
+    <type>int32_t</type> for an <literal>i</literal>, a pointer to <type>const char*</type> for an
-    <type>const char*</type> for an <literal>s</literal>, ...)  which are set based on the values in
+    <literal>s</literal>, ...)  which are set based on the values in the message. As an exception, in case of
-    the message. As an exception, in case of array and variant types, the first argument is an
+    array and variant types, the first argument is an "input" argument that further specifies how the message
-    "input" argument that further specifies how the message should be read. See the table below for
+    should be read. See the table below for a complete list of allowed arguments and their types. Note that,
-    a complete list of allowed arguments and their types. Note that, if the basic type is a pointer
+    if the basic type is a pointer (e.g., <type>const char *</type> in the case of a string), the argument is
-    (e.g., <type>const char *</type> in the case of a string), the argument is a pointer to a
+    a pointer to a pointer, and also the pointer value that is written is only borrowed and the contents must
-    pointer, and also the pointer value that is written is only borrowed and the contents must be
+    be copied if they are to be used after the end of the messages lifetime.</para>
-    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
+    <para>Each argument may also be <constant>NULL</constant>, in which case the value is read and ignored.
-    ignored.</para>
+    </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
+    <para>If objects of the specified types are not present at the current position in the message, an error
-    in the message, an error is returned.
+    is returned.</para>
-    </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
+    <function>sd_bus_message_read()</function>, except that it is called with a <literal>va_list</literal>
-    <literal>va_list</literal> instead of a variable number of arguments. This
+    instead of a variable number of arguments. This function does not call the <function>va_end()</function>
-    function does not call the <function>va_end()</function> macro. Because it
+    macro. Because it invokes the <function>va_arg()</function> macro, the value of <parameter>ap</parameter>
-    invokes the <function>va_arg()</function> macro, the value of
+    is undefined after the call.</para>
-    <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
+    <para>On success, these functions return a non-negative integer. On failure, they return a negative
-    <function>sd_bus_message_readv()</function> return 0 or a positive integer. On failure, they return a
+    errno-style error code.</para>
-    negative errno-style error code.</para>
 
     <xi:include href="sd_bus_message_read_basic.xml" xpointer="errors" />
   </refsect1>