From: Timo Sirainen <tss@iki.fi>
Date: Sat, 1 Jan 2011 12:34:14 +0000 (+0200)
Subject: lib-storage: Added warning comments about mail_get_*header*utf8().
X-Git-Tag: 2.0.9~23
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=afff56f1266ba321b115584141bbb056267f4818;p=thirdparty%2Fdovecot%2Fcore.git

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 c4413da423..d09506ba85 100644
--- 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. */