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
