pulseaudio/doc/messaging_api.txt

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 in JSON format, 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. Non-empty response will be in JSON format.

The reference further down lists available messages, their parameters
and return values.

Reference:

Object path: /core
Message: list-handlers
Parameters: None
Return value: JSON array of handler description objects
    [{"name":"Handler name","description":"Description"} ...]

Object path: /card/bluez_card.XX_XX_XX_XX_XX_XX/bluez
Message: list-codecs
Parameters: None
Return value: JSON array of codec description objects
    [{"name":"codec1","description":"Codec 1"} ...]

Object path: /card/bluez_card.XX_XX_XX_XX_XX_XX/bluez
Message: get-codec
Parameters: None
Return value: "codec name"

Object path: /card/bluez_card.XX_XX_XX_XX_XX_XX/bluez
Message: switch-codec
Parameters: "codec name"
Return value: none
pactl, pacmd, cli-command: Add send-message command Part-of: <https://gitlab.freedesktop.org/pulseaudio/pulseaudio/-/merge_requests/51> 2020-01-14 17:24:36 +08:00			`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`
message-params: use JSON instead of custom format Part-of: <https://gitlab.freedesktop.org/pulseaudio/pulseaudio/-/merge_requests/525> 2021-03-14 14:49:05 +08:00			`be specified using a single string in JSON format, but are not mandatory.`
pactl, pacmd, cli-command: Add send-message command Part-of: <https://gitlab.freedesktop.org/pulseaudio/pulseaudio/-/merge_requests/51> 2020-01-14 17:24:36 +08:00
message-params: use JSON instead of custom format Part-of: <https://gitlab.freedesktop.org/pulseaudio/pulseaudio/-/merge_requests/525> 2021-03-14 14:49:05 +08:00			`The message handler returns an error number as defined in def.h and also returns`
			`a string in the "response" variable. Non-empty response will be in JSON format.`

			`The reference further down lists available messages, their parameters`
			`and return values.`
message-params: Allow parameter strings to contain escaped curly braces The patch adds the possibility to escape curly braces within parameter strings and introduces several new functions that can be used for writing parameters. For writing, the structure pa_message_params, which is a wrapper for pa_strbuf has been created. Following new write functions are available: pa_message_params_new() - creates a new pa_message_params structure pa_message_params_free() - frees a pa_message_params structure pa_message_param_to_string_free() - converts a pa_message_param to string and frees the structure pa_message_params_begin_list() - starts a list pa_message_params_end_list() - ends a list pa_message_params_write_string() - writes a string to a pa_message_params structure pa_message_params_write_raw() - writes a raw string to a pa_message_params structure For string parameters that contain curly braces or backslashes, those characters will be escaped when using pa_message_params_write_string(), while write_raw() will put the string into the buffer without any changes. For reading, pa_message_params_read_string() reverts the changes that pa_message_params_write_string() might have introduced. The patch also adds more restrictions on the object path name. Now only alphanumeric characters and one of "_", ".", "-" and "/" are allowed. The path name may not end with a / or contain a double slash. If the user specifies a trailing / when sending a message, it will be silently removed. Part-of: <https://gitlab.freedesktop.org/pulseaudio/pulseaudio/-/merge_requests/51> 2020-01-14 20:24:16 +08:00
			`Reference:`

core: add message handler This patch adds a small message handler to the core which enables clients to list available handlers via the list-handlers message. Command: pacmd send-message /core list-handlers pactl can be used with the same parameters. The patch also introduces a convention for the return string. It consists of a list of elements where curly braces are used to separate elements. Each element can itself contain further elements. For example consider a message that returns multiple elements which each contain an integer and an array of float. A response string would look like that: {{Integer} {{1st float} {2nd float} ...}}{...} Part-of: <https://gitlab.freedesktop.org/pulseaudio/pulseaudio/-/merge_requests/51> 2020-01-14 18:00:20 +08:00			`Object path: /core`
			`Message: list-handlers`
			`Parameters: None`
message-params: use JSON instead of custom format Part-of: <https://gitlab.freedesktop.org/pulseaudio/pulseaudio/-/merge_requests/525> 2021-03-14 14:49:05 +08:00			`Return value: JSON array of handler description objects`
			`[{"name":"Handler name","description":"Description"} ...]`
bluetooth: update messaging api reference Part-of: <https://gitlab.freedesktop.org/pulseaudio/pulseaudio/-/merge_requests/525> 2021-03-26 02:57:50 +08:00
			`Object path: /card/bluez_card.XX_XX_XX_XX_XX_XX/bluez`
			`Message: list-codecs`
			`Parameters: None`
			`Return value: JSON array of codec description objects`
			`[{"name":"codec1","description":"Codec 1"} ...]`

			`Object path: /card/bluez_card.XX_XX_XX_XX_XX_XX/bluez`
			`Message: get-codec`
			`Parameters: None`
			`Return value: "codec name"`

			`Object path: /card/bluez_card.XX_XX_XX_XX_XX_XX/bluez`
			`Message: switch-codec`
			`Parameters: "codec name"`
			`Return value: none`