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

[Tanu Kaskinen]

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.

-- 
Tanu

https://liberapay.com/tanuk
https://www.patreon.com/tanuk