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 8c5f9f9068bbd9feca6ffef853f0d71aaeedcf44..57dec1b086d4c96384bac441bf4fd0323c896275 100644 (file)
--- 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 c2a64288da3df2ad124d45a0857141714a352998..32169faf5b1f644c20a3d4200032b9c10fddf2aa 100644 (file)
--- 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",