dovecot-2.0: lib-storage: Added warning comments about mail_get_...

[dovecot at dovecot.org]

details:   http://hg.dovecot.org/dovecot-2.0/rev/c1e71f579adc
changeset: 12536:c1e71f579adc
user:      Timo Sirainen <tss at iki.fi>
date:      Sat Jan 01 14:34:14 2011 +0200
description:
lib-storage: Added warning comments about mail_get_*header*utf8().

diffstat:

 src/lib-storage/mail-storage.h |  9 +++++++--
 1 files changed, 7 insertions(+), 2 deletions(-)

diffs (26 lines):

diff -r 6813e76eb29e -r c1e71f579adc src/lib-storage/mail-storage.h
--- a/src/lib-storage/mail-storage.h	Sat Jan 01 13:27:16 2011 +0200
+++ b/src/lib-storage/mail-storage.h	Sat Jan 01 14:34:14 2011 +0200
@@ -642,7 +642,11 @@
 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_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. */