lib-storage: Added warning comments about mail_get_*header*utf8().

diff --git a/src/lib-storage/mail-storage.h b/src/lib-storage/mail-storage.h
index c4413da423c7f578127ca02cb0bab9a32aed8737..d09506ba85119c5d1257a3906ed76a2faef1cda7 100644 (file)
--- a/src/lib-storage/mail-storage.h
+++ b/src/lib-storage/mail-storage.h
@@ -642,7 +642,11 @@ int mail_get_physical_size(struct mail *mail, uoff_t *size_r);
 int mail_get_first_header(struct mail *mail, const char *field,
                          const char **value_r);
 /* Like mail_get_first_header(), but decode MIME encoded words to UTF-8.
-   Also multiline headers are returned unfolded. */
+   Also multiline headers are returned unfolded.
+
+   Do not use this function for getting structured fields (e.g. address fields),
+   because decoding may break the structuring. Instead parse them first and
+   only afterwards decode the encoded words. */
 int mail_get_first_header_utf8(struct mail *mail, const char *field,
                               const char **value_r);
 /* Return a NULL-terminated list of values for each found field.
@@ -650,7 +654,8 @@ int mail_get_first_header_utf8(struct mail *mail, const char *field,
 int mail_get_headers(struct mail *mail, const char *field,
                     const char *const **value_r);
 /* Like mail_get_headers(), but decode MIME encoded words to UTF-8.
-   Also multiline headers are returned unfolded. */
+   Also multiline headers are returned unfolded.
+   Do not use for structured fields (see mail_get_first_header_utf8()). */
 int mail_get_headers_utf8(struct mail *mail, const char *field,
                          const char *const **value_r);
 /* Returns stream containing specified headers. */