netwerk/mime/nsIMIMEHeaderParam.idl@b8a032363ba2
netwerk/mime/nsIMIMEHeaderParam.idl
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /* vim:expandtab:shiftwidth=4:tabstop=4:
3 */
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/. */
8 /*
9 * This interface allows any module to access the routine
10 * for MIME header parameter parsing (RFC 2231/5987)
11 */
13 #include "nsISupports.idl"
15 [scriptable, uuid(9c9252a1-fdaf-40a2-9c2b-a3dc45e28dde)]
16 interface nsIMIMEHeaderParam : nsISupports {
18 /**
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
27 * if all else fails.
28 *
29 * <p>
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.
34 *
35 * <p>
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
41 * includes lang.
42 *
43 * <p>
44 * Note that GetParameterHTTP skips some of the workarounds used for
45 * mail (MIME) header fields, and thus SHOULD be used from non-mail
46 * code.
47 *
48 *
49 * @param aHeaderVal a header string to get the value of a parameter
50 * from.
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
56 * string is not UTF-8
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
62 * nsMemory::Free it.
63 * @return the value of <code>aParamName</code> in Unichar(UTF-16).
64 */
65 AString getParameter(in ACString aHeaderVal,
66 in string aParamName,
67 in ACString aFallbackCharset,
68 in boolean aTryLocaleCharset,
69 out string aLang);
72 /**
73 * Like getParameter, but disabling encodings and workarounds specific to
74 * MIME (as opposed to HTTP).
75 */
76 AString getParameterHTTP(in ACString aHeaderVal,
77 in string aParamName,
78 in ACString aFallbackCharset,
79 in boolean aTryLocaleCharset,
80 out string aLang);
82 /**
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.
86 *
87 * <p>
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.
92 *
93 * <p>
94 * Code that parses HTTP header fields (as opposed to MIME header fields)
95 * should use this function.
96 *
97 * @param aParamVal a header field parameter to decode.
98 * @param aLang will be set to the language part (possibly
99 * empty).
100 * @return the decoded parameter value.
101 */
102 AString decodeRFC5987Param(in ACString aParamVal,
103 out ACString aLang);
105 /**
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.
110 * <p>
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)
117 *
118 * Otherwise, this method would have been made static.
119 *
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.
132 */
134 [noscript]
135 string getParameterInternal(in string aHeaderVal,
136 in string aParamName,
137 out string aCharset,
138 out string aLang);
141 /**
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
148 * <p>
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)
154 *
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
163 */
164 [noscript]
165 ACString decodeRFC2047Header(in string aHeaderVal,
166 in string aDefaultCharset,
167 in boolean aOverrideCharset,
168 in boolean aEatContinuation);
171 /**
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
178 * stripped off.
179 * <p>
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)
185 *
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
199 */
201 [noscript]
202 ACString decodeParameter(in ACString aParamValue,
203 in string aCharset,
204 in string aDefaultCharset,
205 in boolean aOverrideCharset);
206 };
