[3/8] pactl, pacmd, cli-command: Add send-message command

Submitted by Georg Chini on April 9, 2018, 5:35 p.m.

Details

Message ID 20180409173525.18219-4-georg@chini.tk
State New
Headers show
Series "core: Add message sending/receiving" ( rev: 1 ) in PulseAudio

Not browsing as part of any series.

Commit Message

Georg Chini April 9, 2018, 5:35 p.m.
The patch also adds some API documentation.
---
 doc/messaging_api.txt            | 15 ++++++++++++++
 man/pactl.1.xml.in               |  7 +++++++
 man/pulse-cli-syntax.5.xml.in    |  7 +++++++
 shell-completion/bash/pulseaudio |  5 +++--
 shell-completion/zsh/_pulseaudio |  2 ++
 src/pulse/introspect.h           |  3 ++-
 src/pulsecore/cli-command.c      | 44 ++++++++++++++++++++++++++++++++++++++++
 src/utils/pacmd.c                |  1 +
 src/utils/pactl.c                | 43 ++++++++++++++++++++++++++++++++++++++-
 9 files changed, 123 insertions(+), 4 deletions(-)
 create mode 100644 doc/messaging_api.txt

Patch hide | download patch | download mbox

diff --git a/doc/messaging_api.txt b/doc/messaging_api.txt
new file mode 100644
index 00000000..cbc06e75
--- /dev/null
+++ b/doc/messaging_api.txt
@@ -0,0 +1,15 @@ 
+Message API reference
+
+The message API allows any object within pulseaudio to register a message
+handler. A message handler is a function that can be called by clients using
+PA_COMMAND_SEND_OBJECT_MESSAGE. A message consists at least of an object path
+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 also returns a string in
+the "response" variable. The following reference lists available messages,
+their parameters and return values.
+
+Recipient:
+Message:
+Parameters:
+Return value:
diff --git a/man/pactl.1.xml.in b/man/pactl.1.xml.in
index 39569b6b..4052fae3 100644
--- a/man/pactl.1.xml.in
+++ b/man/pactl.1.xml.in
@@ -245,6 +245,13 @@  License along with PulseAudio; if not, see <http://www.gnu.org/licenses/>.
       'ac3-iec61937, format.rate = "[ 32000, 44100, 48000 ]"').
       </p></optdesc> </option>
 
+    <option>
+      <p><opt>send-message</opt> <arg>RECIPIENT</arg> <arg>MESSAGE</arg> <arg>MESSAGE_PARAMETERS</arg></p>
+      <optdesc><p>Send a message string to the specified recipient object. If applicable an additional string containing
+      message parameters can be specified. A string is returned as a response to the message. For available message
+      commands see https://cgit.freedesktop.org/pulseaudio/pulseaudio/tree/doc/messaging_api.txt.</p></optdesc>
+    </option>
+
     <option>
       <p><opt>subscribe</opt></p>
       <optdesc><p>Subscribe to events, pactl does not exit by itself, but keeps waiting for new events.</p></optdesc>
diff --git a/man/pulse-cli-syntax.5.xml.in b/man/pulse-cli-syntax.5.xml.in
index 0a0fabaf..83f55d6b 100644
--- a/man/pulse-cli-syntax.5.xml.in
+++ b/man/pulse-cli-syntax.5.xml.in
@@ -297,6 +297,13 @@  License along with PulseAudio; if not, see <http://www.gnu.org/licenses/>.
       <optdesc><p>Debug: Show shared properties.</p></optdesc>
     </option>
 
+    <option>
+      <p><opt>send-message</opt> <arg>recipient</arg> <arg>message</arg> <arg>message_parameters</arg></p>
+      <optdesc><p>Send a message string to the specified recipient object. If applicable an additional string containing
+      message parameters can be specified. A string is returned as a response to the message. For available message
+      commands see https://cgit.freedesktop.org/pulseaudio/pulseaudio/tree/doc/messaging_api.txt.</p></optdesc>
+    </option>
+
     <option>
       <p><opt>exit</opt></p>
       <optdesc><p>Terminate the daemon. If you want to terminate a CLI
diff --git a/shell-completion/bash/pulseaudio b/shell-completion/bash/pulseaudio
index e473b9c2..797ec067 100644
--- a/shell-completion/bash/pulseaudio
+++ b/shell-completion/bash/pulseaudio
@@ -120,7 +120,8 @@  _pactl() {
                     set-source-port set-sink-volume set-source-volume
                     set-sink-input-volume set-source-output-volume set-sink-mute
                     set-source-mute set-sink-input-mute set-source-output-mute
-                    set-sink-formats set-port-latency-offset subscribe help)
+                    set-sink-formats set-port-latency-offset subscribe send-message
+                    help)
 
     _init_completion -n = || return
     preprev=${words[$cword-2]}
@@ -270,7 +271,7 @@  _pacmd() {
                     move-sink-input move-source-output suspend-sink suspend-source
                     suspend set-card-profile set-sink-port set-source-port
                     set-port-latency-offset set-log-target set-log-level set-log-meta
-                    set-log-time set-log-backtrace)
+                    set-log-time set-log-backtrace send-message)
     _init_completion -n = || return
     preprev=${words[$cword-2]}
 
diff --git a/shell-completion/zsh/_pulseaudio b/shell-completion/zsh/_pulseaudio
index 0e9e89bd..a2817ebb 100644
--- a/shell-completion/zsh/_pulseaudio
+++ b/shell-completion/zsh/_pulseaudio
@@ -263,6 +263,7 @@  _pactl_completion() {
             'set-sink-input-mute: mute a stream'
             'set-source-output-mute: mute a recording stream'
             'set-sink-formats: set supported formats of a sink'
+            'send-message: send a message to a pulseaudio object'
             'subscribe: subscribe to events'
         )
 
@@ -561,6 +562,7 @@  _pacmd_completion() {
             'dump: show daemon configuration'
             'dump-volumes: show the state of all volumes'
             'shared: show shared properties'
+            'send-message: send a message to a pulseaudio object'
             'exit: ask the PulseAudio daemon to exit'
         )
         _describe 'pacmd commands' _pacmd_commands
diff --git a/src/pulse/introspect.h b/src/pulse/introspect.h
index 7e47e740..fbe5b668 100644
--- a/src/pulse/introspect.h
+++ b/src/pulse/introspect.h
@@ -451,7 +451,8 @@  pa_operation* pa_context_unload_module(pa_context *c, uint32_t idx, pa_context_s
 /** Callback prototype for pa_context_send_message_to_object() */
 typedef void (*pa_context_string_cb_t)(pa_context *c, int success, const char *response, void *userdata);
 
-/** Send a message to an object that registered a message handler. */
+/** 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. */
 pa_operation* pa_context_send_message_to_object(pa_context *c, const char *recipient_name, const char *message, const char *message_parameters, pa_context_string_cb_t cb, void *userdata);
 
 /** @} */
diff --git a/src/pulsecore/cli-command.c b/src/pulsecore/cli-command.c
index 44795b0d..f0cd617f 100644
--- a/src/pulsecore/cli-command.c
+++ b/src/pulsecore/cli-command.c
@@ -53,6 +53,7 @@ 
 #include <pulsecore/sound-file-stream.h>
 #include <pulsecore/shared.h>
 #include <pulsecore/core-util.h>
+#include <pulsecore/message-handler.h>
 #include <pulsecore/core-error.h>
 #include <pulsecore/modinfo.h>
 #include <pulsecore/dynarray.h>
@@ -135,6 +136,7 @@  static int pa_cli_command_sink_port(pa_core *c, pa_tokenizer *t, pa_strbuf *buf,
 static int pa_cli_command_source_port(pa_core *c, pa_tokenizer *t, pa_strbuf *buf, bool *fail);
 static int pa_cli_command_port_offset(pa_core *c, pa_tokenizer *t, pa_strbuf *buf, bool *fail);
 static int pa_cli_command_dump_volumes(pa_core *c, pa_tokenizer *t, pa_strbuf *buf, bool *fail);
+static int pa_cli_command_send_message_to_object(pa_core *c, pa_tokenizer *t, pa_strbuf *buf, bool *fail);
 
 /* A method table for all available commands */
 
@@ -191,6 +193,7 @@  static const struct command commands[] = {
     { "set-log-meta",            pa_cli_command_log_meta,           "Show source code location in log messages (args: bool)", 2},
     { "set-log-time",            pa_cli_command_log_time,           "Show timestamps in log messages (args: bool)", 2},
     { "set-log-backtrace",       pa_cli_command_log_backtrace,      "Show backtrace in log messages (args: frames)", 2},
+    { "send-message",            pa_cli_command_send_message_to_object, "Send a message to an object (args: recipient, message, message_parameters)", 4},
     { "play-file",               pa_cli_command_play_file,          "Play a sound file (args: filename, sink|index)", 3},
     { "dump",                    pa_cli_command_dump,               "Dump daemon configuration", 1},
     { "dump-volumes",            pa_cli_command_dump_volumes,       "Debug: Show the state of all volumes", 1 },
@@ -1779,6 +1782,47 @@  static int pa_cli_command_port_offset(pa_core *c, pa_tokenizer *t, pa_strbuf *bu
     return 0;
 }
 
+static int pa_cli_command_send_message_to_object(pa_core *c, pa_tokenizer *t, pa_strbuf *buf, bool *fail) {
+    const char *object_path, *message, *message_parameters;
+    char *response = NULL;
+    int ret;
+
+    pa_core_assert_ref(c);
+    pa_assert(t);
+    pa_assert(buf);
+    pa_assert(fail);
+
+
+    if (!(object_path = pa_tokenizer_get(t, 1))) {
+        pa_strbuf_puts(buf, "You need to specify an object path as recipient for the message.\n");
+           return -1;
+    }
+
+    if (!(message = pa_tokenizer_get(t, 2))) {
+        pa_strbuf_puts(buf, "You need to specify a message name.\n");
+        return -1;
+    }
+
+    /* parameters may be NULL */
+    message_parameters = pa_tokenizer_get(t, 3);
+
+    ret = pa_message_handler_send_message(c, object_path, message, message_parameters, &response);
+
+    if (ret < 0) {
+        pa_strbuf_printf(buf, "Send message failed: %s\n", pa_strerror(ret));
+        ret = -1;
+
+    } else {
+        if (response)
+            pa_strbuf_puts(buf, response);
+        pa_strbuf_puts(buf, "\n");
+        ret = 0;
+    }
+
+    pa_xfree(response);
+    return ret;
+}
+
 static int pa_cli_command_dump(pa_core *c, pa_tokenizer *t, pa_strbuf *buf, bool *fail) {
     pa_module *m;
     pa_sink *sink;
diff --git a/src/utils/pacmd.c b/src/utils/pacmd.c
index 616573cc..6eae6c42 100644
--- a/src/utils/pacmd.c
+++ b/src/utils/pacmd.c
@@ -77,6 +77,7 @@  static void help(const char *argv0) {
     printf("%s %s %s\n", argv0, "set-log-meta", _("1|0"));
     printf("%s %s %s\n", argv0, "set-log-time", _("1|0"));
     printf("%s %s %s\n", argv0, "set-log-backtrace", _("FRAMES"));
+    printf("%s %s %s\n", argv0, "send-message", _("RECIPIENT MESSAGE [MESSAGE_PARAMETERS]"));
 
     printf(_("\n"
          "  -h, --help                            Show this help\n"
diff --git a/src/utils/pactl.c b/src/utils/pactl.c
index e9bf005b..66c0f251 100644
--- a/src/utils/pactl.c
+++ b/src/utils/pactl.c
@@ -56,7 +56,10 @@  static char
     *card_name = NULL,
     *profile_name = NULL,
     *port_name = NULL,
-    *formats = NULL;
+    *formats = NULL,
+    *object_path = NULL,
+    *message = NULL,
+    *message_args = NULL;
 
 static uint32_t
     sink_input_idx = PA_INVALID_INDEX,
@@ -130,6 +133,7 @@  static enum {
     SET_SOURCE_OUTPUT_MUTE,
     SET_SINK_FORMATS,
     SET_PORT_LATENCY_OFFSET,
+    SEND_OBJECT_MESSAGE,
     SUBSCRIBE
 } action = NONE;
 
@@ -834,6 +838,19 @@  static void index_callback(pa_context *c, uint32_t idx, void *userdata) {
     complete_action();
 }
 
+static void send_message_callback(pa_context *c, int success, const char *response, void *userdata) {
+
+    if (!success) {
+        pa_log(_("Send message failed: %s"), pa_strerror(pa_context_errno(c)));
+        quit(1);
+        return;
+    }
+
+    printf("%s\n", response);
+
+    complete_action();
+}
+
 static void volume_relative_adjust(pa_cvolume *cv) {
     pa_assert(volume_flags & VOL_RELATIVE);
 
@@ -1404,6 +1421,10 @@  static void context_state_callback(pa_context *c, void *userdata) {
                     o = pa_context_set_port_latency_offset(c, card_name, port_name, latency_offset, simple_callback, NULL);
                     break;
 
+                case SEND_OBJECT_MESSAGE:
+                    o = pa_context_send_message_to_object(c, object_path, message, message_args, send_message_callback, NULL);
+                    break;
+
                 case SUBSCRIBE:
                     pa_context_set_subscribe_callback(c, context_subscribe_callback, NULL);
 
@@ -1580,6 +1601,7 @@  static void help(const char *argv0) {
     printf("%s %s %s %s\n", argv0, _("[options]"), "set-(sink-input|source-output)-mute", _("#N 1|0|toggle"));
     printf("%s %s %s %s\n", argv0, _("[options]"), "set-sink-formats", _("#N FORMATS"));
     printf("%s %s %s %s\n", argv0, _("[options]"), "set-port-latency-offset", _("CARD-NAME|CARD-#N PORT OFFSET"));
+    printf("%s %s %s %s\n", argv0, _("[options]"), "send-message", _("RECIPIENT MESSAGE [MESSAGE_PARAMETERS]"));
     printf("%s %s %s\n",    argv0, _("[options]"), "subscribe");
     printf(_("\nThe special names @DEFAULT_SINK@, @DEFAULT_SOURCE@ and @DEFAULT_MONITOR@\n"
              "can be used to specify the default sink, source and monitor.\n"));
@@ -2015,6 +2037,22 @@  int main(int argc, char *argv[]) {
                 goto quit;
             }
 
+        } else if (pa_streq(argv[optind], "send-message")) {
+            action = SEND_OBJECT_MESSAGE;
+
+            if (argc < optind+3) {
+                pa_log(_("You have to specify at least an object path and a message name"));
+                goto quit;
+            }
+
+            object_path = pa_xstrdup(argv[optind + 1]);
+            message = pa_xstrdup(argv[optind + 2]);
+            if (argc >= optind+4)
+                message_args = pa_xstrdup(argv[optind + 3]);
+
+            if (argc > optind+4)
+                pa_log(_("Excess arguments given, they will be ignored. Note that all message parameters must be given as a single string."));
+
         } else if (pa_streq(argv[optind], "subscribe"))
 
             action = SUBSCRIBE;
@@ -2108,6 +2146,9 @@  quit:
     pa_xfree(profile_name);
     pa_xfree(port_name);
     pa_xfree(formats);
+    pa_xfree(object_path);
+    pa_xfree(message);
+    pa_xfree(message_args);
 
     if (sndfile)
         sf_close(sndfile);

Comments

On Mon, 2018-04-09 at 19:35 +0200, Georg Chini wrote:
> The patch also adds some API documentation.
> ---
>  doc/messaging_api.txt            | 15 ++++++++++++++
>  man/pactl.1.xml.in               |  7 +++++++
>  man/pulse-cli-syntax.5.xml.in    |  7 +++++++
>  shell-completion/bash/pulseaudio |  5 +++--
>  shell-completion/zsh/_pulseaudio |  2 ++
>  src/pulse/introspect.h           |  3 ++-
>  src/pulsecore/cli-command.c      | 44 ++++++++++++++++++++++++++++++++++++++++
>  src/utils/pacmd.c                |  1 +
>  src/utils/pactl.c                | 43 ++++++++++++++++++++++++++++++++++++++-
>  9 files changed, 123 insertions(+), 4 deletions(-)
>  create mode 100644 doc/messaging_api.txt
> 
> diff --git a/doc/messaging_api.txt b/doc/messaging_api.txt
> new file mode 100644
> index 00000000..cbc06e75
> --- /dev/null
> +++ b/doc/messaging_api.txt
> @@ -0,0 +1,15 @@
> +Message API reference
> +
> +The message API allows any object within pulseaudio to register a message
> +handler. A message handler is a function that can be called by clients using
> +PA_COMMAND_SEND_OBJECT_MESSAGE. A message consists at least of an object path
> +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 also returns a string in
> +the "response" variable. The following reference lists available messages,
> +their parameters and return values.
> +
> +Recipient:
> +Message:
> +Parameters:
> +Return value:
> diff --git a/man/pactl.1.xml.in b/man/pactl.1.xml.in
> index 39569b6b..4052fae3 100644
> --- a/man/pactl.1.xml.in
> +++ b/man/pactl.1.xml.in
> @@ -245,6 +245,13 @@ License along with PulseAudio; if not, see <http://www.gnu.org/licenses/>.
>        'ac3-iec61937, format.rate = "[ 32000, 44100, 48000 ]"').
>        </p></optdesc> </option>
>  
> +    <option>
> +      <p><opt>send-message</opt> <arg>RECIPIENT</arg> <arg>MESSAGE</arg> <arg>MESSAGE_PARAMETERS</arg></p>
> +      <optdesc><p>Send a message string to the specified recipient object. If applicable an additional string containing

I think "a message" is better than "a message string".

> +      message parameters can be specified. A string is returned as a response to the message. For available message
> +      commands see https://cgit.freedesktop.org/pulseaudio/pulseaudio/tree/doc/messaging_api.txt.</p></optdesc>;

I think "available messages" is better than "available message
commands".

> +    </option>
> +
>      <option>
>        <p><opt>subscribe</opt></p>
>        <optdesc><p>Subscribe to events, pactl does not exit by itself, but keeps waiting for new events.</p></optdesc>
> diff --git a/man/pulse-cli-syntax.5.xml.in b/man/pulse-cli-syntax.5.xml.in
> index 0a0fabaf..83f55d6b 100644
> --- a/man/pulse-cli-syntax.5.xml.in
> +++ b/man/pulse-cli-syntax.5.xml.in
> @@ -297,6 +297,13 @@ License along with PulseAudio; if not, see <http://www.gnu.org/licenses/>.
>        <optdesc><p>Debug: Show shared properties.</p></optdesc>
>      </option>
>  
> +    <option>
> +      <p><opt>send-message</opt> <arg>recipient</arg> <arg>message</arg> <arg>message_parameters</arg></p>
> +      <optdesc><p>Send a message string to the specified recipient object. If applicable an additional string containing
> +      message parameters can be specified. A string is returned as a response to the message. For available message
> +      commands see https://cgit.freedesktop.org/pulseaudio/pulseaudio/tree/doc/messaging_api.txt.</p></optdesc>;
> +    </option>

Same as above.

> diff --git a/src/pulse/introspect.h b/src/pulse/introspect.h
> index 7e47e740..fbe5b668 100644
> --- a/src/pulse/introspect.h
> +++ b/src/pulse/introspect.h
> @@ -451,7 +451,8 @@ pa_operation* pa_context_unload_module(pa_context *c, uint32_t idx, pa_context_s
>  /** Callback prototype for pa_context_send_message_to_object() */
>  typedef void (*pa_context_string_cb_t)(pa_context *c, int success, const char *response, void *userdata);
>  
> -/** Send a message to an object that registered a message handler. */
> +/** 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. */
>  pa_operation* pa_context_send_message_to_object(pa_context *c, const char *recipient_name, const char *message, const char *message_parameters, pa_context_string_cb_t cb, void *userdata);

Apparently I didn't notice when reviewing the previous patch that the
documentation is lacking a \since tag.