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

[Georg Chini]

On 29.09.2017 16:03, Tanu Kaskinen wrote:
> On Sat, 2017-08-19 at 17:48 +0200, Georg Chini wrote:
>> ---
>>   man/pactl.1.xml.in               |  6 +++++
>>   man/pulse-cli-syntax.5.xml.in    |  6 +++++
>>   shell-completion/bash/pulseaudio |  5 +++--
>>   shell-completion/zsh/_pulseaudio |  2 ++
>>   src/pulsecore/cli-command.c      | 47 ++++++++++++++++++++++++++++++++++++++++
>>   src/utils/pacmd.c                |  1 +
>>   src/utils/pactl.c                | 39 ++++++++++++++++++++++++++++++++-
>>   7 files changed, 103 insertions(+), 3 deletions(-)
>>
>> diff --git a/man/pactl.1.xml.in b/man/pactl.1.xml.in
>> index 39569b6b..e868babc 100644
>> --- a/man/pactl.1.xml.in
>> +++ b/man/pactl.1.xml.in
>> @@ -246,6 +246,12 @@ License along with PulseAudio; if not, see <http://www.gnu.org/licenses/>.
>>         </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.</p></optdesc>
>> +    </option>
> Are the message parameters expected to be just one string? I think it
> would be more user-frienly to allow the parameters to be split in
> multiple command line arguments.

I don't understand what you mean. If you want to pass multiple parameters
you can do so with one string "param1=xyz param2=abc". In the end, the
message handler only receives one string and I do not see much difference
if you have to put the parameters in quotes or not. Using one string leaves
you free to choose a separator between the parameters and it would also be
some more overhead to put the string together from multiple arguments.

>
> There should be a pointer to the place where all the messages are
> documented.
>
> We haven't agreed where to put the documentation. I think it would be
> highly desirable to have the documentation in the same repository with
> the code, so the wiki is probably not the best place. A plain text file
> would be the simplest way forward. The pactl man page could then point
> to the text file in cgit.freedesktop.org.

I'm fine with this. Where do you think is the best place for the file?
And what exactly should go in it? A list of possible messages with
arguments and an explanation what each argument does? Or also
some documentation on the message API functions?

>
> I think it would be a good idea to use something like Sphinx for
> generating nice html pages from plain text with some light markup, not
> only for the messaging API documentation but for other documentation as
> well. That requires some work to learn and configure the system,
> however, and while I expect it to be pretty simple, I'm probably not
> going to do that myself anytime soon. Would you be interested in
> working on that? Even if not, what do you think about using something
> like Sphinx for documentation? Would it be better than the wiki? Maybe
> I will some day find the time and motivation to set it up myself.

I don't know Sphinx at all. I'll take a look at it, but at the moment
i do not have the time to start an additional documentation project.


>
>> +static void string_callback(pa_context *c, const char *response, void *userdata) {
>> +    if (!response) {
>> +        pa_log(_("Failure: %s"), pa_strerror(pa_context_errno(c)));
> The callback is not called on failures, and there's nothing preventing
> the message handler from returning a null string as the response, so
> either you shouldn't treat a NULL response as a failure, or you should
> add documentation and some safeguards that prevent NULL responses from
> successful operations.

Mh, the message handler is expected to return a string, if it returns
NULL, then this is an error. So what kind of safeguards do you mean?
A successful operation should always return a string.