The Tor Browser / file comparison
comparison: netwerk/mime/nsIMIMEHeaderParam.idl
netwerk/mime/nsIMIMEHeaderParam.idl
- changeset 0
- 6474c204b198
equal
deleted
inserted
replaced
| -1:000000000000 | 0:0acc52e6aa7e |
|---|---|
| 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 * 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); | |
| 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 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 */ | |
| 133 | |
| 134 [noscript] | |
| 135 string getParameterInternal(in string 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 }; | |
| 207 |
