From: Timo Sirainen <timo.sirainen@open-xchange.com>
Date: Thu, 14 Jan 2021 15:33:13 +0000 (+0200)
Subject: lib-storage: Update mailbox_list_settings.{vname|storage_name}_escape_char comments
X-Git-Tag: 2.3.14.rc1~40
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=a243cdb7489292c139bc84885b3ad7ea9c9174c7;p=thirdparty%2Fdovecot%2Fcore.git

lib-storage: Update mailbox_list_settings.{vname|storage_name}_escape_char comments

Also add the examples in the comments to unit tests to make sure they really
work.
---

diff --git a/src/lib-storage/mailbox-list.h b/src/lib-storage/mailbox-list.h
index 8c5f9f9068..57dec1b086 100644
--- a/src/lib-storage/mailbox-list.h
+++ b/src/lib-storage/mailbox-list.h
@@ -142,12 +142,24 @@ struct mailbox_list_settings {
 	   this setting contains either "" or "dir/". */
 	const char *mailbox_dir_name;
 
-	/* Encode "bad" characters in mailbox names as <escape_char><hex> */
+	/* Used for escaping the mailbox name in storage (storage_name). If the
+	   UTF-8 vname has characters that can't reversibly (or safely) be
+	   converted to storage_name and back, encode the problematic parts
+	   using <storage_name_escape_char><hex>. The storage_name_escape_char
+	   itself also has to be encoded the same way. For example
+	   { vname="A/B.C%D", storage_name_escape_char='%', namespace_sep='/',
+	   storage_sep='.' } -> storage_name="A.B%2eC%25D". */
 	char storage_name_escape_char;
-	/* If mailbox name can't be changed reversibly to UTF-8 and back,
-	   encode the problematic parts using <escape_char><hex> in the
-	   user-visible UTF-8 name. The vname_escape_char itself also has to be
-	   encoded the same way. */
+	/* Used for escaping the user/client-visible UTF-8 vname. If the
+	   storage_name can't be converted reversibly to the vname and back,
+	   encode the problematic parts using <vname_escape_char><hex>. The
+	   vname_escape_char itself also has to be encoded the same way. For
+	   example { storage_name="A/B.C%D", vname_escape_char='%',
+	   namespace_sep='/', storage_sep='.' } -> vname="A%2fB/C%25D".
+
+	   Note that it's possible for escape_char and broken_char to be the
+	   same character. They're just used for different directions in
+	   conversion. */
 	char vname_escape_char;
 	/* Use UTF-8 mailbox names on filesystem instead of mUTF-7 */
 	bool utf8;
diff --git a/src/lib-storage/test-mailbox-list.c b/src/lib-storage/test-mailbox-list.c
index c2a64288da..32169faf5b 100644
--- a/src/lib-storage/test-mailbox-list.c
+++ b/src/lib-storage/test-mailbox-list.c
@@ -357,6 +357,10 @@ static void test_mailbox_list_get_names(void)
 		  .flags = TEST_FLAG_NO_STORAGE_NAME,
 		  .ns_sep = '/', .list_sep = '.',
 		  .storage_name_escape_char = '%' },
+		{ .vname = "A/B.C%D",
+		  .storage_name = "A.B%2eC%25D",
+		  .storage_name_escape_char='%',
+		  .ns_sep = '/', .list_sep = '.' },
 
 		/* vname escaping: */
 		{ .vname = "%7c|child",
@@ -407,6 +411,10 @@ static void test_mailbox_list_get_names(void)
 		  .flags = TEST_FLAG_NO_VNAME,
 		  .ns_sep = '/', .list_sep = '.',
 		  .vname_escape_char = '%' },
+		{ .vname = "A%2fB/C%25D",
+		  .storage_name = "A/B.C%D",
+		  .ns_sep = '/', .list_sep = '.',
+		  .vname_escape_char = '%' },
 
 		/* INBOX: */
 		{ .vname = "inBox",