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