diff options
Diffstat (limited to 'netwerk/mime/nsIMIMEHeaderParam.idl')
| -rw-r--r-- | netwerk/mime/nsIMIMEHeaderParam.idl | 206 |
1 files changed, 206 insertions, 0 deletions
diff --git a/netwerk/mime/nsIMIMEHeaderParam.idl b/netwerk/mime/nsIMIMEHeaderParam.idl new file mode 100644 index 0000000000..cdc28b7e90 --- /dev/null +++ b/netwerk/mime/nsIMIMEHeaderParam.idl @@ -0,0 +1,206 @@ +/* -*- 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 ACString 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); +}; |