chan_websocket: Allow additional URI parameters to be added to the outgoing URI.

* Added a new option to the WebSocket dial string to capture the additional
  URI parameters.
* Added a new API ast_uri_verify_encoded() that verifies that a string
  either doesn't need URI encoding or that it has already been encoded.
* Added a new API ast_websocket_client_add_uri_params() to add the params
  to the client websocket session.
* Added XML documentation that will show up with `core show application Dial`
  that shows how to use it.

Resolves: #1352

UserNote: A new WebSocket channel driver option `v` has been added to the
Dial application that allows you to specify additional URI parameters on
outgoing connections. Run `core show application Dial` from the Asterisk CLI
to see how to use it.

(cherry picked from commit de6aaa9623)

res/res_websocket_client.c

@@ -237,19 +237,40 @@ verify_server_hostname = no
 
 static struct ast_sorcery *sorcery = NULL;
 
+void ast_websocket_client_add_uri_params(struct ast_websocket_client *wc,
+	const char *uri_params)
+{
+	ast_string_field_set(wc, uri_params, uri_params);
+}
+
 struct ast_websocket *ast_websocket_client_connect(struct ast_websocket_client *wc,
 	void *lock_obj, const char *display_name, enum ast_websocket_result *result)
 {
 	int reconnect_counter = wc->reconnect_attempts;
+	char *uri = NULL;
 
 	if (ast_strlen_zero(display_name)) {
 		display_name = ast_sorcery_object_get_id(wc);
 	}
 
+	if (!ast_strlen_zero(wc->uri_params)) {
+		/*
+		 * If the configured URI doesn't already contain parameters, we append the
+		 * new ones to the URI path component with '?'.  If it does, we append the
+		 * new ones to the existing ones with a '&'.
+		 */
+		char sep = '?';
+		uri = ast_alloca(strlen(wc->uri) + strlen(wc->uri_params) + 2);
+		if (strchr(wc->uri, '?')) {
+			sep = '&';
+		}
+		sprintf(uri, "%s%c%s", wc->uri, sep, wc->uri_params); /*Safe */
+	}
+
 	while (1) {
 		struct ast_websocket *astws = NULL;
 		struct ast_websocket_client_options options = {
-			.uri = wc->uri,
+			.uri = S_OR(uri, wc->uri),
 			.protocols = wc->protocols,
 			.username = wc->username,
 			.password = wc->password,
@@ -357,6 +378,11 @@ static void *wc_alloc(const char *id)
 		return NULL;
 	}
 
+	if (ast_string_field_init_extended(wc, uri_params) != 0) {
+		ao2_cleanup(wc);
+		return NULL;
+	}
+
 	ast_debug(2, "%s: Allocated websocket client config\n", id);
 	return wc;
 }