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 + 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); -- 2.14.1
