This patch adds a small message handler to the core which enables
clients to list available handlers via the list-handlers message.
Command: pacmd send-message /core list-handlers
pactl can be used with the same parameters.
The patch also introduces a convention for the return string.
It consists of a list of elements where curly braces are used
to separate elements. Each element can itself contain further
elements. For example consider a message that returns multiple
elements which each contain an integer and an array of float.
A response string would look like that:
{{Integer} {{1st float} {2nd float} ...}}{...}
---
doc/messaging_api.txt | 20 +++++++++++++------
src/pulsecore/core.c | 43 +++++++++++++++++++++++++++++++++++++++++
src/pulsecore/message-handler.c | 24 +++++++++++++++++++++++
3 files changed, 81 insertions(+), 6 deletions(-)
diff --git a/doc/messaging_api.txt b/doc/messaging_api.txt
index 11835cda..85a56d84 100644
--- a/doc/messaging_api.txt
+++ b/doc/messaging_api.txt
@@ -7,10 +7,18 @@ and a message command, both specified as strings. Additional parameters can
be specified using a single string, but are not mandatory. The message handler
returns an error number as defined in def.h and may also return a string in
the "response" variable. If "response" is NULL, this should be treated like
-an empty string. The following reference lists available messages, their
-parameters and return values.
+an empty string. It it is not NULL, it consists of a list of elements. Curly
+braces are used to separate elements. Each element can itself contain further
+elements. For example consider a message that returns multiple elements which
+each contain an integer and an array of float. A response string would look
+like that:
+{{Integer} {{1st float} {2nd float} ...}}{...}
-Recipient:
-Message:
-Parameters:
-Return value:
+The following reference lists available messages, their parameters and return
+values. If a return value is enclosed in {}, this means that multiple elements
+of the same type may be returned.
+
+Recipient: /core
+Message: list-handlers
+Parameters: None
+Return value: {{Handler name} {Description}}
diff --git a/src/pulsecore/core.c b/src/pulsecore/core.c
index bcab9ed1..6214aced 100644
--- a/src/pulsecore/core.c
+++ b/src/pulsecore/core.c
@@ -33,11 +33,13 @@
#include <pulsecore/module.h>
#include <pulsecore/core-rtclock.h>
#include <pulsecore/core-util.h>
+#include <pulsecore/message-handler.h>
#include <pulsecore/core-scache.h>
#include <pulsecore/core-subscribe.h>
#include <pulsecore/random.h>
#include <pulsecore/log.h>
#include <pulsecore/macro.h>
+#include <pulsecore/strbuf.h>
#include "core.h"
@@ -61,6 +63,43 @@ static int core_process_msg(pa_msgobject *o, int code, void *userdata, int64_t o
static void core_free(pa_object *o);
+/* Returns a list of handlers. */
+static char *message_handler_list(pa_core *c) {
+ pa_strbuf *buf;
+ void *state = NULL;
+ struct pa_message_handler *handler;
+
+ buf = pa_strbuf_new();
+
+ while ((handler = pa_hashmap_iterate(c->message_handlers, &state, NULL))) {
+ pa_strbuf_puts(buf, "{");
+
+ pa_strbuf_printf(buf, "{%s} {", handler->recipient);
+ if (handler->description)
+ pa_strbuf_printf(buf, "%s", handler->description);
+
+ pa_strbuf_puts(buf, "}}");
+ }
+
+ return pa_strbuf_to_string_free(buf);
+}
+
+static int core_message_handler(const char *recipient, const char *message, const char *message_parameters, char **response, void *userdata) {
+ pa_core *c;
+
+ pa_assert(c = (pa_core *) userdata);
+ pa_assert(message);
+ pa_assert(response);
+ pa_assert(pa_safe_streq(recipient, "/core"));
+
+ if (pa_streq(message, "list-handlers")) {
+ *response = message_handler_list(c);
+ return PA_OK;
+ }
+
+ return -PA_ERR_NOTIMPLEMENTED;
+}
+
pa_core* pa_core_new(pa_mainloop_api *m, bool shared, bool enable_memfd, size_t shm_size) {
pa_core* c;
pa_mempool *pool;
@@ -105,6 +144,8 @@ pa_core* pa_core_new(pa_mainloop_api *m, bool shared, bool enable_memfd, size_t
c->shared = pa_hashmap_new(pa_idxset_string_hash_func, pa_idxset_string_compare_func);
c->message_handlers = pa_hashmap_new(pa_idxset_string_hash_func, pa_idxset_string_compare_func);
+ pa_message_handler_register(c, "/core", "Core message handler", core_message_handler, (void *) c);
+
c->default_source = NULL;
c->default_sink = NULL;
@@ -205,6 +246,8 @@ static void core_free(pa_object *o) {
pa_assert(pa_hashmap_isempty(c->shared));
pa_hashmap_free(c->shared);
+ pa_message_handler_unregister(c, "/core");
+
pa_assert(pa_hashmap_isempty(c->message_handlers));
pa_hashmap_free(c->message_handlers);
diff --git a/src/pulsecore/message-handler.c b/src/pulsecore/message-handler.c
index 06e3680e..21cb8278 100644
--- a/src/pulsecore/message-handler.c
+++ b/src/pulsecore/message-handler.c
@@ -31,6 +31,20 @@
#include "message-handler.h"
+/* Check if a string does not contain control characters. Currently these are
+ * only "{" and "}". */
+static bool string_is_valid(const char *test_string) {
+ uint32_t i;
+
+ for (i = 0; i < strlen(test_string); i++) {
+ if (test_string[i] == '{' ||
+ test_string[i] == '}')
+ return false;
+ }
+
+ return true;
+}
+
/* Message handler functions */
/* Register message handler. recipient_name must be a unique name starting with "/". */
@@ -45,6 +59,11 @@ void pa_message_handler_register(pa_core *c, const char *recipient_name, const c
/* Ensure that the recipient name is not empty and starts with "/". */
pa_assert(recipient_name[0] == '/');
+ /* Ensure that recipient name and description are valid strings */
+ pa_assert(string_is_valid(recipient_name));
+ if (description)
+ pa_assert(string_is_valid(description));
+
handler = pa_xnew0(struct pa_message_handler, 1);
handler->userdata = userdata;
handler->callback = cb;
@@ -97,6 +116,11 @@ int pa_message_handler_set_description(pa_core *c, const char *recipient_name, c
if (!(handler = pa_hashmap_get(c->message_handlers, recipient_name)))
return -PA_ERR_NOENTITY;
+ if (description) {
+ if (!string_is_valid(description))
+ return -PA_ERR_INVALID;
+ }
+
pa_xfree(handler->description);
handler->description = pa_xstrdup(description);
--
2.14.1
