nsIMIMEHeaderParam.idl (9742B)
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/. */ 7 8 /* 9 * This interface allows any module to access the routine 10 * for MIME header parameter parsing (RFC 2231/5987) 11 */ 12 13 #include "nsISupports.idl" 14 15 [scriptable, uuid(9c9252a1-fdaf-40a2-9c2b-a3dc45e28dde)] 16 interface nsIMIMEHeaderParam : nsISupports { 17 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 * 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); 70 71 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); 81 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); 104 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 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 free it. 130 * @return the value of <code>aParamName</code> after 131 * RFC 2231 decoding but without charset conversion. 132 */ 133 134 [noscript] 135 string getParameterInternal(in ACString aHeaderVal, 136 in string aParamName, 137 out string aCharset, 138 out string aLang); 139 140 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); 169 170 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 */ 200 201 [noscript] 202 ACString decodeParameter(in ACString aParamValue, 203 in string aCharset, 204 in string aDefaultCharset, 205 in boolean aOverrideCharset); 206 };