1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /* vim:expandtab:shiftwidth=4:tabstop=4:
4 /* This Source Code Form is subject to the terms of the Mozilla Public
5 * License, v. 2.0. If a copy of the MPL was not distributed with this
6 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
9 * This interface allows any module to access the routine
10 * for MIME header parameter parsing (RFC 2231/5987)
13 #include
"nsISupports.idl"
15 [scriptable
, uuid(9c9252a1
-fdaf
-40a2
-9c2b
-a3dc45e28dde
)]
16 interface nsIMIMEHeaderParam
: nsISupports
{
19 * Given the value of a single header field (such as
20 * Content-Disposition and Content-Type) and the name of a parameter
21 * (e.g. filename, name, charset), returns the value of the parameter.
22 * The value is obtained by decoding RFC 2231/5987-style encoding,
23 * RFC 2047-style encoding, and converting to UniChar(UTF-16)
24 * from charset specified in RFC 2231/2047 encoding, UTF-8,
25 * <code>aFallbackCharset</code>, the locale charset as fallback if
26 * <code>TryLocaleCharset</code> is set, and null-padding as last resort
30 * This method internally invokes <code>getParameterInternal</code>,
31 * However, it does not stop at decoding RFC 2231 (the task for
32 * <code>getParameterInternal</code> but tries to cope
33 * with several non-standard-compliant cases mentioned below.
36 * Note that a lot of MUAs put RFC 2047-encoded parameters. Unfortunately,
37 * this includes Mozilla as of 2003-05-30. Even more standard-ignorant MUAs,
38 * web servers and application servers put 'raw 8bit characters'. This will
39 * try to cope with all these cases as gracefully as possible. Additionally,
40 * it returns the language tag if the parameter is encoded per RFC 2231 and
44 * Note that GetParameterHTTP skips some of the workarounds used for
45 * mail (MIME) header fields, and thus SHOULD be used from non-mail
49 * @param aHeaderVal a header string to get the value of a parameter
51 * @param aParamName the name of a MIME header parameter (e.g.
52 * filename, name, charset). If empty, returns
53 * the first (possibly) _unnamed_ 'parameter'.
54 * @param aFallbackCharset fallback charset to try if the string after
55 * RFC 2231/2047 decoding or the raw 8bit
57 * @param aTryLocaleCharset If set, makes yet another attempt
58 * with the locale charset.
59 * @param aLang If non-null, assigns it to a pointer
60 * to a string containing the value of language
61 * obtained from RFC 2231 parsing. Caller has to
63 * @return the value of <code>aParamName</code> in Unichar(UTF-16).
65 AString getParameter
(in ACString aHeaderVal
,
67 in ACString aFallbackCharset
,
68 in boolean aTryLocaleCharset
,
73 * Like getParameter, but disabling encodings and workarounds specific to
74 * MIME (as opposed to HTTP).
76 AString getParameterHTTP
(in ACString aHeaderVal
,
78 in ACString aFallbackCharset
,
79 in boolean aTryLocaleCharset
,
83 * Given the value of a header field parameter using the encoding
84 * defined in RFC 5987, decode the value into a Unicode string, and extract
85 * the optional language parameter.
88 * This function is purposefully picky; it will abort for all (most?)
89 * invalid inputs. This is by design. In particular, it does not support
90 * any character encodings other than UTF-8, in order not to promote
91 * non-interoperable usage.
94 * Code that parses HTTP header fields (as opposed to MIME header fields)
95 * should use this function.
97 * @param aParamVal a header field parameter to decode.
98 * @param aLang will be set to the language part (possibly
100 * @return the decoded parameter value.
102 AString decodeRFC5987Param
(in ACString aParamVal
,
106 * Given the value of a single header field (such as
107 * Content-Disposition and Content-Type) and the name of a parameter
108 * (e.g. filename, name, charset), returns the value of the parameter
109 * after decoding RFC 2231-style encoding.
111 * For <strong>internal use only</strong>. The only other place where
112 * this needs to be invoked is |MimeHeaders_get_parameter| in
113 * mailnews/mime/src/mimehdrs.cpp defined as
114 * char * MimeHeaders_get_parameter (const char *header_value,
115 * const char *parm_name,
116 * char **charset, char **language)
118 * Otherwise, this method would have been made static.
120 * @param aHeaderVal a header string to get the value of a parameter from.
121 * @param aParamName the name of a MIME header parameter (e.g.
122 * filename, name, charset). If empty, returns
123 * the first (possibly) _unnamed_ 'parameter'.
124 * @param aCharset If non-null, it gets assigned a new pointer
125 * to a string containing the value of charset obtained
126 * from RFC 2231 parsing. Caller has to nsMemory::Free it.
127 * @param aLang If non-null, it gets assigned a new pointer
128 * to a string containing the value of language obtained
129 * from RFC 2231 parsing. Caller has to nsMemory::Free it.
130 * @return the value of <code>aParamName</code> after
131 * RFC 2231 decoding but without charset conversion.
135 string getParameterInternal
(in string aHeaderVal
,
136 in string aParamName
,
142 * Given a header value, decodes RFC 2047-style encoding and
143 * returns the decoded header value in UTF-8 if either it's
144 * RFC-2047-encoded or aDefaultCharset is given. Otherwise,
145 * returns the input header value (in whatever encoding)
146 * as it is except that RFC 822 (using backslash) quotation and
147 * CRLF (if aEatContinuation is set) are stripped away
149 * For internal use only. The only other place where this needs to be
150 * invoked is <code>MIME_DecodeMimeHeader</code> in
151 * mailnews/mime/src/mimehdrs.cpp defined as
152 * char * Mime_DecodeMimeHeader(char *header_val, const char *charset,
153 * bool override, bool eatcontinuation)
155 * @param aHeaderVal a header value to decode
156 * @param aDefaultCharset MIME charset to use in place of MIME charset
157 * specified in RFC 2047 style encoding
158 * when <code>aOverrideCharset</code> is set.
159 * @param aOverrideCharset When set, overrides MIME charset specified
160 * in RFC 2047 style encoding with <code>aDefaultCharset</code>
161 * @param aEatContinuation When set, removes CR/LF
162 * @return decoded header value
165 ACString decodeRFC2047Header
(in string aHeaderVal
,
166 in string aDefaultCharset
,
167 in boolean aOverrideCharset
,
168 in boolean aEatContinuation
);
172 * Given a header parameter, decodes RFC 2047 style encoding (if it's
173 * not obtained from RFC 2231 encoding), converts it to
174 * UTF-8 and returns the result in UTF-8 if an attempt to extract
175 * charset info. from a few different sources succeeds.
176 * Otherwise, returns the input header value (in whatever encoding)
177 * as it is except that RFC 822 (using backslash) quotation is
180 * For internal use only. The only other place where this needs to be
181 * invoked is <code>mime_decode_filename</code> in
182 * mailnews/mime/src/mimehdrs.cpp defined as
183 * char * mime_decode_filename(char *name, const char *charset,
184 * MimeDisplayOptions *opt)
186 * @param aParamValue the value of a parameter to decode and convert
187 * @param aCharset charset obtained from RFC 2231 decoding in which
188 * <code>aParamValue</code> is encoded. If null,
189 * indicates that it needs to try RFC 2047, instead.
190 * @param aDefaultCharset MIME charset to use when aCharset is null and
191 * cannot be obtained per RFC 2047 (most likely
192 * because 'bare' string is used.) Besides, it
193 * overrides aCharset/MIME charset obtained from
194 * RFC 2047 if <code>aOverrideCharset</code> is set.
195 * @param aOverrideCharset When set, overrides MIME charset specified
196 * in RFC 2047 style encoding with
197 * <code>aDefaultCharset</code>
198 * @return decoded parameter
202 ACString decodeParameter
(in ACString aParamValue
,
204 in string aDefaultCharset
,
205 in boolean aOverrideCharset
);