mirror of
https://gitlab.freedesktop.org/pulseaudio/pulseaudio.git
synced 2025-10-29 05:40:23 -04:00
590fd1ca69
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>
29 lines
1.5 KiB
Text
29 lines
1.5 KiB
Text
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. If the string is not empty it consists of elements.
|
|
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} ...}}{...}
|
|
Any characters that are not enclosed in curly braces are ignored (all characters
|
|
between { and {, between } and } and between } and {). The same syntax is used
|
|
to specify message parameters. The reference further down lists available messages,
|
|
their parameters and return values. If a return value is enclosed in {}, this
|
|
means that multiple elements of the same type may be returned.
|
|
|
|
For string parameters that contain curly braces or backslashes, those characters
|
|
must be escaped by adding a "\" before them.
|
|
|
|
Reference:
|
|
|
|
Object path: /core
|
|
Message: list-handlers
|
|
Parameters: None
|
|
Return value: {{{Handler name} {Description}} ...}
|