pactl: Implement list message-handlers

For better readability, "pactl list message-handlers" is introduced which
prints a formatted output of "pactl send-message /core list-handlers".

The patch also adds the functions pa_message_params_read_raw() and
pa_message_params_read_string() for easy parsing of the message response
string. Because the functions need to modify the parameter string,
the message handler and the pa_context_string_callback function now
receive a char* instead of a const char* as parameter argument.

Part-of: <https://gitlab.freedesktop.org/pulseaudio/pulseaudio/-/merge_requests/51>

src/pulse/introspect.c

@@ -2236,8 +2236,15 @@ static void context_string_callback(pa_pdispatch *pd, uint32_t command, uint32_t
         response = "";
 
     if (o->callback) {
-        pa_context_string_cb_t cb = (pa_context_string_cb_t) o->callback;
-        cb(o->context, success, response, o->userdata);
+        char *response_copy;
+        pa_context_string_cb_t cb;
+
+        response_copy = pa_xstrdup(response);
+
+        cb = (pa_context_string_cb_t) o->callback;
+        cb(o->context, success, response_copy, o->userdata);
+
+        pa_xfree(response_copy);
     }
 
 finish:

src/pulse/introspect.h

@@ -498,7 +498,7 @@ pa_operation* pa_context_unload_module(pa_context *c, uint32_t idx, pa_context_s
 /** @{ \name Messages */
 
 /** Callback prototype for pa_context_send_message_to_object() \since 15.0 */
-typedef void (*pa_context_string_cb_t)(pa_context *c, int success, const char *response, void *userdata);
+typedef void (*pa_context_string_cb_t)(pa_context *c, int success, char *response, void *userdata);
 
 /** Send a message to an object that registered a message handler. For more information
  * see https://cgit.freedesktop.org/pulseaudio/pulseaudio/tree/doc/messaging_api.txt. \since 15.0 */

src/pulse/meson.build

@@ -19,6 +19,7 @@ libpulse_sources = [
   'mainloop-api.c',
   'mainloop-signal.c',
   'mainloop.c',
+  'message-params.c',
   'operation.c',
   'proplist.c',
   'rtclock.c',
@@ -50,6 +51,7 @@ libpulse_headers = [
   'mainloop-api.h',
   'mainloop-signal.h',
   'mainloop.h',
+  'message-params.h',
   'operation.h',
   'proplist.h',
   'pulseaudio.h',

src/pulse/message-params.c

@@ -0,0 +1,118 @@
+/***
+  This file is part of PulseAudio.
+
+  PulseAudio is free software; you can redistribute it and/or modify
+  it under the terms of the GNU Lesser General Public License as
+  published by the Free Software Foundation; either version 2.1 of the
+  License, or (at your option) any later version.
+
+  PulseAudio is distributed in the hope that it will be useful, but
+  WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+  Lesser General Public License for more details.
+
+  You should have received a copy of the GNU Lesser General Public
+  License along with PulseAudio; if not, see <http://www.gnu.org/licenses/>.
+***/
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include <errno.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/types.h>
+
+#include <pulse/xmalloc.h>
+
+#include <pulsecore/macro.h>
+
+#include "message-params.h"
+
+/* Split the specified string into elements. An element is defined as
+ * a sub-string between curly braces. The function is needed to parse
+ * the parameters of messages. Each time it is called it returns the
+ * position of the current element in result and the state pointer is
+ * advanced to the next list element.
+ *
+ * The variable state points to, should be initialized to NULL before
+ * the first call. The function returns 1 on success, 0 if end of string
+ * is encountered and -1 on parse error.
+ *
+ * result is set to NULL on end of string or parse error. */
+static int split_list(char *c, char **result, void **state) {
+    char *current = *state ? *state : c;
+    uint32_t open_braces;
+
+    pa_assert(result);
+
+    *result = NULL;
+
+    /* Empty or no string */
+    if (!current || *current == 0)
+        return 0;
+
+    /* Find opening brace */
+    while (*current != 0) {
+
+        if (*current == '{')
+            break;
+
+        /* unexpected closing brace, parse error */
+        if (*current == '}')
+            return -1;
+
+        current++;
+    }
+
+    /* No opening brace found, end of string */
+    if (*current == 0)
+         return 0;
+
+    *result = current + 1;
+    open_braces = 1;
+
+    while (open_braces != 0 && *current != 0) {
+        current++;
+        if (*current == '{')
+            open_braces++;
+        if (*current == '}')
+            open_braces--;
+    }
+
+    /* Parse error, closing brace missing */
+    if (open_braces != 0) {
+        *result = NULL;
+        return -1;
+    }
+
+    /* Replace } with 0 */
+    *current = 0;
+
+    *state = current + 1;
+
+    return 1;
+}
+
+/* Read a string from the parameter list. The state pointer is
+ * advanced to the next element of the list. Returns a pointer
+ * to a sub-string within c. The result must not be freed. */
+int pa_message_params_read_string(char *c, const char **result, void **state) {
+    char *start_pos;
+    int r;
+
+    pa_assert(result);
+
+    if ((r = split_list(c, &start_pos, state)) == 1)
+        *result = start_pos;
+
+    return r;
+}
+
+/* Another wrapper for split_list() to distinguish between reading
+ * pure string data and raw data which may contain further lists. */
+int pa_message_params_read_raw(char *c, char **result, void **state) {
+    return split_list(c, result, state);
+}

src/pulse/message-params.h

@@ -0,0 +1,42 @@
+#ifndef foomessagehelperhfoo
+#define foomessagehelperhfoo
+
+/***
+  This file is part of PulseAudio.
+
+  PulseAudio is free software; you can redistribute it and/or modify
+  it under the terms of the GNU Lesser General Public License as
+  published by the Free Software Foundation; either version 2.1 of the
+  License, or (at your option) any later version.
+
+  PulseAudio is distributed in the hope that it will be useful, but
+  WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+  Lesser General Public License for more details.
+
+  You should have received a copy of the GNU Lesser General Public
+  License along with PulseAudio; if not, see <http://www.gnu.org/licenses/>.
+***/
+
+#include <stddef.h>
+#include <stdbool.h>
+#include <inttypes.h>
+
+#include <pulse/cdecl.h>
+#include <pulse/version.h>
+
+/** \file
+ * Utility functions for reading and writing message parameters */
+
+PA_C_DECL_BEGIN
+
+/** Read raw data from a parameter list. Used to split a message parameter
+ * string into list elements  \since 15.0 */
+int pa_message_params_read_raw(char *c, char **result, void **state);
+
+/** Read a string from a parameter list. \since 15.0 */
+int pa_message_params_read_string(char *c, const char **result, void **state);
+
+PA_C_DECL_END
+
+#endif