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>

1 files changed, 6 insertions, 1 deletions

diff --git a/doc/messaging_api.txt b/doc/messaging_api.txt
index 431a5df27..e0a921da4 100644
--- a/doc/messaging_api.txt
+++ b/doc/messaging_api.txt
@@ -14,10 +14,15 @@ 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 following reference lists available messages,
+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