[PATCH v5 6/7] message-params: Allow parameter strings to contain escaped curly braces

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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_param, which is a wrapper for pa_strbuf
has been created. Following new write functions are available:

pa_message_param_new() - creates a new pa_message_param structure
pa_message_param_to_string() - converts a pa_message_param to string and frees
the structure
pa_message_param_begin_list() - starts a list
pa_message_param_end_list() - ends a list
pa_message_param_write_string() - writes a string to a pa_message_param structure

For string parameters that contain curly braces, those braces must be escaped
by adding a "\" before them. This however means that a trailing backslash would
falsely escape the closing bracket. To avoid this, single quotes must be added
at start and end of the string. The function pa_message_param_write_string()
has a parameter do_escape. If true, the necessary escaping is added. Escaping
is only needed if a string might fulfill one of the following conditions:

- It contains curly braces
- It contains a trailing "\"
- It is enclosed in single quotes

Other strings can be passed without modification.

For reading, pa_message_param_read_string() reverts the changes that
pa_message_param_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 /. If the user specifies a trailing / when
sending a message, it will be removed.
---
 doc/messaging_api.txt           |  34 +++++++-
 src/Makefile.am                 |   3 +-
 src/map-file                    |   5 ++
 src/pulse/message-params.c      | 181 ++++++++++++++++++++++++++++++++++++++--
 src/pulse/message-params.h      |  23 ++++-
 src/pulsecore/core.c            |  20 ++---
 src/pulsecore/message-handler.c |  53 +++++++-----
 src/utils/pactl.c               |   4 +-
 8 files changed, 279 insertions(+), 44 deletions(-)

diff --git a/doc/messaging_api.txt b/doc/messaging_api.txt
index 431a5df2..0e6be53f 100644
--- a/doc/messaging_api.txt
+++ b/doc/messaging_api.txt
@@ -14,10 +14,42 @@ 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.
 
+There are several functions that simplify reading and writing message parameter
+strings. For writing, the structure pa_message_param can be used. Following
+functions are available:
+pa_message_param_new() - creates a new pa_message_param structure
+pa_message_param_to_string() - converts a pa_message_param to string and frees
+the structure
+pa_message_param_begin_list() - starts a list
+pa_message_param_end_list() - ends a list
+pa_message_param_write_string() - writes a string to a pa_message_param structure
+
+For string parameters that contain curly braces, those braces must be escaped
+by adding a "\" before them. This however means that a trailing backslash would
+falsely escape the closing bracket. To avoid this, single quotes must be added
+at start and end of the string. The function pa_message_param_write_string()
+has a parameter do_escape. If true, the necessary escaping is added. Escaping
+is only needed if a string might fulfill one of the following conditions:
+
+- It contains curly braces
+- It contains a trailing "\"
+- It is enclosed in single quotes
+
+Other strings can be passed without modification.
+
+For reading, the following functions are available:
+pa_message_param_split_list() - parse message parameter string
+pa_message_param_read_string() - read a string from a parameter list
+
+pa_message_param_read_string() also reverts the changes that
+pa_message_param_write_string() might have introduced.
+
+Reference:
+
 Object path: /core
 Message: list-handlers
 Parameters: None
diff --git a/src/Makefile.am b/src/Makefile.am
index d4e34482..7e4933ae 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -673,6 +673,7 @@ libpulsecommon_ at PA_MAJORMINOR@_la_SOURCES = \
 		pulse/timeval.c pulse/timeval.h \
 		pulse/rtclock.c pulse/rtclock.h \
 		pulse/volume.c pulse/volume.h \
+		pulse/message-params.c pulse/message-params.h \
 		pulsecore/atomic.h \
 		pulsecore/authkey.c pulsecore/authkey.h \
 		pulsecore/conf-parser.c pulsecore/conf-parser.h \
@@ -881,6 +882,7 @@ libpulse_la_SOURCES = \
 		pulse/mainloop-api.c pulse/mainloop-api.h \
 		pulse/mainloop-signal.c pulse/mainloop-signal.h \
 		pulse/mainloop.c pulse/mainloop.h \
+		pulse/message-params.c pulse/message-params.h \
 		pulse/operation.c pulse/operation.h \
 		pulse/proplist.c pulse/proplist.h \
 		pulse/pulseaudio.h \
@@ -893,7 +895,6 @@ libpulse_la_SOURCES = \
 		pulse/timeval.c pulse/timeval.h \
 		pulse/utf8.c pulse/utf8.h \
 		pulse/util.c pulse/util.h \
-		pulse/message-params.c pulse/message-params.h \
 		pulse/volume.c pulse/volume.h \
 		pulse/xmalloc.c pulse/xmalloc.h
 
diff --git a/src/map-file b/src/map-file
index 385731dc..372d190d 100644
--- a/src/map-file
+++ b/src/map-file
@@ -225,8 +225,13 @@ pa_mainloop_quit;
 pa_mainloop_run;
 pa_mainloop_set_poll_func;
 pa_mainloop_wakeup;
+pa_message_param_begin_list;
+pa_message_param_end_list;
+pa_message_param_new;
 pa_message_param_read_string;
 pa_message_param_split_list;
+pa_message_param_to_string;
+pa_message_param_write_string;
 pa_msleep;
 pa_operation_cancel;
 pa_operation_get_state;
diff --git a/src/pulse/message-params.c b/src/pulse/message-params.c
index cb080c33..a644c173 100644
--- a/src/pulse/message-params.c
+++ b/src/pulse/message-params.c
@@ -28,20 +28,55 @@
 #include <pulse/xmalloc.h>
 
 #include <pulsecore/macro.h>
+#include <pulsecore/strbuf.h>
 
 #include "message-params.h"
 
+/* Message parameter structure, a wrapper for pa_strbuf */
+struct pa_message_param {
+    pa_strbuf *buffer;
+};
+
+/* Remove escaping from a string */
+static char *unescape(char *value) {
+    char *tmp;
+
+    if (!value)
+        return NULL;
+
+    /* If the string is enclosed in single quotes, remove them */
+    if (*value == '\'' && value[strlen(value) - 1] == '\'') {
+
+        memmove(value, value + 1, strlen(value));
+        value[strlen(value) - 1] = 0;
+    }
+
+    /* Remove escape character from curly braces if present. */
+    while ((tmp = strstr(value, "\\{")))
+        memmove(tmp, tmp + 1, strlen(value) - (size_t)(tmp  - value));
+    while ((tmp = strstr(value, "\\}")))
+        memmove(tmp, tmp + 1, strlen(value) - (size_t)(tmp  - value));
+
+    /* Return the pointer that was passed in. */
+    return value;
+}
+
+/* Read functions */
+
 /* Split the specified string into elements. An element is defined as
  * a sub-string between curly braces. The function is needed to parse
  * the parameters of messages. Each time it is called returns the position
  * of the current element in result and the state pointer is advanced to
- * the next list element.
+ * the next list element. On return, the parameter *is_unpacked indicates
+ * if the string is plain text or contains a sub-list. is_unpacked may
+ * be NULL.
  * The variable state points to, should be initialized to NULL before
  * the first call. The function returns 1 on success, 0 if end of string
  * is encountered and -1 on parse error. */
-int pa_message_param_split_list(char *c, char **result, void **state) {
+int pa_message_param_split_list(char *c, char **result, bool *is_unpacked, void **state) {
     char *current = *state ? *state : c;
     uint32_t open_braces;
+    bool found_backslash = false;
 
     pa_assert(result);
 
@@ -54,29 +89,52 @@ int pa_message_param_split_list(char *c, char **result, void **state) {
     /* Find opening brace */
     while (*current != 0) {
 
-        if (*current == '{')
+        /* Skip escaped curly braces. */
+        if (*current == '\\') {
+            found_backslash = true;
+            current++;
+            continue;
+        }
+
+        if (*current == '{' && !found_backslash)
             break;
 
         /* unexpected closing brace, parse error */
-        if (*current == '}')
+        if (*current == '}' && !found_backslash)
             return -1;
 
+        found_backslash = false;
         current++;
     }
 
     /* No opening brace found, end of string */
     if (*current == 0)
-         return 0;
+        return 0;
 
+    if (is_unpacked)
+        *is_unpacked = true;
     *result = current + 1;
+    found_backslash = false;
     open_braces = 1;
 
     while (open_braces != 0 && *current != 0) {
         current++;
-        if (*current == '{')
+
+        /* Skip escaped curly braces. */
+        if (*current == '\\') {
+            found_backslash = true;
+            continue;
+        }
+
+        if (*current == '{' && !found_backslash) {
             open_braces++;
-        if (*current == '}')
+            if (is_unpacked)
+                *is_unpacked = false;
+        }
+        if (*current == '}' && !found_backslash)
             open_braces--;
+
+        found_backslash = false;
     }
 
     /* Parse error, closing brace missing */
@@ -96,21 +154,126 @@ int pa_message_param_split_list(char *c, char **result, void **state) {
 /* Read a string from the parameter list. The state pointer is
  * advanced to the next element of the list. If allocate is
  * true, a newly allocated string will be returned, else a
- * pointer to a sub-string within c. */
+ * pointer to a sub-string within c. Escaping will be removed
+ * if the string does not contain another list. */
 int pa_message_param_read_string(char *c, char **result, bool allocate, void **state) {
     char *start_pos;
     int err;
+    bool is_unpacked;
 
     pa_assert(result);
 
     *result = NULL;
 
-    if ((err = pa_message_param_split_list(c, &start_pos, state)) != 1)
+    if ((err = pa_message_param_split_list(c, &start_pos, &is_unpacked, state)) != 1)
         return err;
 
     *result = start_pos;
+
+    if (is_unpacked)
+        *result = unescape(*result);
+
     if (allocate)
         *result = pa_xstrdup(*result);
 
     return err;
 }
+
+/* Write functions. The functions are wrapper functions around pa_strbuf,
+ * so that the client does not need to use pa_strbuf directly. */
+
+/* Creates a new pa_message_param structure */
+pa_message_param *pa_message_param_new(void) {
+    pa_message_param *param;
+
+    param = pa_xnew(pa_message_param, 1);
+    param->buffer = pa_strbuf_new();
+
+    return param;
+}
+
+/* Converts a pa_message_param structure to string and frees the structure */
+char *pa_message_param_to_string(pa_message_param *param) {
+    char *result;
+
+    pa_assert(param);
+
+    result = pa_strbuf_to_string_free(param->buffer);
+
+    pa_xfree(param);
+    return result;
+}
+
+/* Writes an opening curly brace */
+void pa_message_param_begin_list(pa_message_param *param) {
+
+    pa_assert(param);
+
+    pa_strbuf_putc(param->buffer, '{');
+}
+
+/* Writes a closing curly brace */
+void pa_message_param_end_list(pa_message_param *param) {
+
+    pa_assert(param);
+
+    pa_strbuf_putc(param->buffer, '}');
+}
+
+/* Writes a string to a message_param structure, adding curly braces
+ * around the string. If do_escape is true, leading and trailing single
+ * quotes and also a "\" before curly braces are added to the input string.
+ * Escaping only needs to be used if the original string might fulfill any
+ * of the following conditions:
+ * - It contains curly braces
+ * - It is enclosed in single quotes
+ * - It ends with a "\" */
+void pa_message_param_write_string(pa_message_param *param, const char *value, bool do_escape) {
+    const char *s;
+    char *output, *out_char;
+    size_t brace_count;
+
+    pa_assert(param);
+
+    /* Null value is written as empty element */
+    if (!value)
+        value = "";
+
+    if (!do_escape) {
+        pa_strbuf_printf(param->buffer, "{%s}", value);
+        return;
+    }
+
+    /* Using pa_strbuf_putc() to write to the strbuf while iterating over
+     * the input string would cause the allocation of a linked list element
+     * for each character of the input string. Therefore the output string
+     * is constructed locally before writing it to the buffer */
+
+    /* Count number of characters to escape */
+    brace_count = 0;
+    for (s = value; *s; ++s) {
+        if (*s == '{' || *s == '}')
+            brace_count++;
+    }
+
+    /* allocate output string */
+    output = pa_xmalloc(strlen(value) + brace_count + 5);
+    out_char = output;
+
+    *out_char++ = '{';
+    *out_char++ = '\'';
+
+    for (s = value; *s; ++s) {
+        if (*s == '{' || *s == '}')
+            *out_char++ = '\\';
+
+        *out_char++ = *s;
+    }
+
+    *out_char++ = '\'';
+    *out_char++ = '}';
+    *out_char = 0;
+
+    pa_strbuf_puts(param->buffer, output);
+    pa_xfree(output);
+}
diff --git a/src/pulse/message-params.h b/src/pulse/message-params.h
index 02e08363..c0675c6e 100644
--- a/src/pulse/message-params.h
+++ b/src/pulse/message-params.h
@@ -30,12 +30,33 @@
 
 PA_C_DECL_BEGIN
 
+typedef struct pa_message_param pa_message_param;
+
+/** Read functions */
+
 /** Split message parameter string into list elements */
-int pa_message_param_split_list(char *c, char **result, void **state);
+int pa_message_param_split_list(char *c, char **result, bool * is_unpacked, void **state);
 
 /** Read a string from the parameter list. */
 int pa_message_param_read_string(char *c, char **result, bool allocate, void **state);
 
+/** Write functions */
+
+/** Create a new pa_message_param structure */
+pa_message_param *pa_message_param_new(void);
+
+/** Convert pa_message_param to string, free pa_message_param structure */
+char *pa_message_param_to_string(pa_message_param *param);
+
+/** Write an opening brace */
+void pa_message_param_begin_list(pa_message_param *param);
+
+/** Write a closing brace */
+void pa_message_param_end_list(pa_message_param *param);
+
+/** Append string to parameter list */
+void pa_message_param_write_string(pa_message_param *param, const char *value, bool do_escape);
+
 PA_C_DECL_END
 
 #endif
diff --git a/src/pulsecore/core.c b/src/pulsecore/core.c
index 94717a4f..e34306bb 100644
--- a/src/pulsecore/core.c
+++ b/src/pulsecore/core.c
@@ -29,6 +29,7 @@
 #include <pulse/rtclock.h>
 #include <pulse/timeval.h>
 #include <pulse/xmalloc.h>
+#include <pulse/message-params.h>
 
 #include <pulsecore/module.h>
 #include <pulsecore/core-rtclock.h>
@@ -65,25 +66,24 @@ static void core_free(pa_object *o);
 
 /* Returns a list of handlers. */
 static char *message_handler_list(pa_core *c) {
-    pa_strbuf *buf;
+    pa_message_param *param;
     void *state = NULL;
     struct pa_message_handler *handler;
 
-    buf = pa_strbuf_new();
+    param = pa_message_param_new();
 
-    pa_strbuf_putc(buf, '{');
+    pa_message_param_begin_list(param);
     PA_HASHMAP_FOREACH(handler, c->message_handlers, state) {
-        pa_strbuf_putc(buf, '{');
+        pa_message_param_begin_list(param);
 
-        pa_strbuf_printf(buf, "{%s} {", handler->object_path);
-        if (handler->description)
-            pa_strbuf_puts(buf, handler->description);
+        pa_message_param_write_string(param, handler->object_path, false);
+        pa_message_param_write_string(param, handler->description, true);
 
-        pa_strbuf_puts(buf, "}}");
+        pa_message_param_end_list(param);
     }
-    pa_strbuf_putc(buf, '}');
+    pa_message_param_end_list(param);
 
-    return pa_strbuf_to_string_free(buf);
+    return pa_message_param_to_string(param);
 }
 
 static int core_message_handler(const char *object_path, const char *message, char *message_parameters, char **response, void *userdata) {
diff --git a/src/pulsecore/message-handler.c b/src/pulsecore/message-handler.c
index a9187b41..747f343c 100644
--- a/src/pulsecore/message-handler.c
+++ b/src/pulsecore/message-handler.c
@@ -31,15 +31,29 @@
 
 #include "message-handler.h"
 
-/* Check if a string does not contain control characters. Currently these are
- * only "{" and "}". */
-static bool string_is_valid(const char *test_string) {
+/* Check if a path string starts with a / and only contains valid characters */
+static bool object_path_is_valid(const char *test_string) {
     uint32_t i;
 
+    if (!test_string)
+        return false;
+
+    /* Make sure the string starts with / and does not end with a / */
+    if (test_string[0] != '/' || test_string[strlen(test_string) - 1] == '/')
+        return false;
+
     for (i = 0; test_string[i]; i++) {
-        if (test_string[i] == '{' ||
-            test_string[i] == '}')
-            return false;
+
+        if ((test_string[i] >= 'a' && test_string[i] <= 'z') ||
+            (test_string[i] >= 'A' && test_string[i] <= 'Z') ||
+            (test_string[i] >= '0' && test_string[i] <= '9') ||
+            test_string[i] == '.' ||
+            test_string[i] == '_' ||
+            test_string[i] == '-' ||
+            test_string[i] == '/')
+            continue;
+
+        return false;
     }
 
     return true;
@@ -56,13 +70,8 @@ void pa_message_handler_register(pa_core *c, const char *object_path, const char
     pa_assert(cb);
     pa_assert(userdata);
 
-    /* Ensure that the object path is not empty and starts with "/". */
-    pa_assert(object_path[0] == '/');
-
-    /* Ensure that object path and description are valid strings */
-    pa_assert(string_is_valid(object_path));
-    if (description)
-        pa_assert(string_is_valid(description));
+    /* Ensure that object path is valid */
+    pa_assert(object_path_is_valid(object_path));
 
     handler = pa_xnew0(struct pa_message_handler, 1);
     handler->userdata = userdata;
@@ -91,7 +100,7 @@ void pa_message_handler_unregister(pa_core *c, const char *object_path) {
 int pa_message_handler_send_message(pa_core *c, const char *object_path, const char *message, const char *message_parameters, char **response) {
     struct pa_message_handler *handler;
     int ret;
-    char *parameter_copy;
+    char *parameter_copy, *path_copy;
 
     pa_assert(c);
     pa_assert(object_path);
@@ -100,8 +109,16 @@ int pa_message_handler_send_message(pa_core *c, const char *object_path, const c
 
     *response = NULL;
 
-    if (!(handler = pa_hashmap_get(c->message_handlers, object_path)))
+    path_copy = pa_xstrdup(object_path);
+
+    /* Remove trailing / from path name if present */
+    if (path_copy[strlen(path_copy) - 1] == '/')
+        path_copy[strlen(path_copy) - 1] = 0;
+
+    if (!(handler = pa_hashmap_get(c->message_handlers, path_copy))) {
+        pa_xfree(path_copy);
         return -PA_ERR_NOENTITY;
+    }
 
     parameter_copy = pa_xstrdup(message_parameters);
 
@@ -110,6 +127,7 @@ int pa_message_handler_send_message(pa_core *c, const char *object_path, const c
     ret = handler->callback(handler->object_path, message, parameter_copy, response, handler->userdata);
 
     pa_xfree(parameter_copy);
+    pa_xfree(path_copy);
     return ret;
 }
 
@@ -123,11 +141,6 @@ int pa_message_handler_set_description(pa_core *c, const char *object_path, cons
     if (!(handler = pa_hashmap_get(c->message_handlers, object_path)))
         return -PA_ERR_NOENTITY;
 
-    if (description) {
-        if (!string_is_valid(description))
-            return -PA_ERR_INVALID;
-    }
-
     pa_xfree(handler->description);
     handler->description = pa_xstrdup(description);
 
diff --git a/src/utils/pactl.c b/src/utils/pactl.c
index fdafe57b..1f13e60c 100644
--- a/src/utils/pactl.c
+++ b/src/utils/pactl.c
@@ -864,14 +864,14 @@ static void list_handlers_callback(pa_context *c, int success, char *response, v
         return;
     }
 
-    if (pa_message_param_split_list(response, &param_list, &state) <= 0) {
+    if (pa_message_param_split_list(response, &param_list, NULL, &state) <= 0) {
         pa_log(_("list-handlers message response could not be parsed correctly"));
         quit(1);
         return;
     }
 
     state = NULL;
-    while ((err = pa_message_param_split_list(param_list, &start_pos, &state)) > 0) {
+    while ((err = pa_message_param_split_list(param_list, &start_pos, NULL, &state)) > 0) {
         void *state2 = NULL;
         char *path;
         char *description;
-- 
2.14.1



[Index of Archives]     [Linux Audio Users]     [AMD Graphics]     [Linux USB Devel]     [Linux Audio Users]     [Yosemite News]     [Linux Kernel]     [Linux SCSI]

  Powered by Linux