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.
