michael@0: /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ michael@0: /* vim:expandtab:shiftwidth=4:tabstop=4: michael@0: */ michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: /* michael@0: * This interface allows any module to access the routine michael@0: * for MIME header parameter parsing (RFC 2231/5987) michael@0: */ michael@0: michael@0: #include "nsISupports.idl" michael@0: michael@0: [scriptable, uuid(9c9252a1-fdaf-40a2-9c2b-a3dc45e28dde)] michael@0: interface nsIMIMEHeaderParam : nsISupports { michael@0: michael@0: /** michael@0: * Given the value of a single header field (such as michael@0: * Content-Disposition and Content-Type) and the name of a parameter michael@0: * (e.g. filename, name, charset), returns the value of the parameter. michael@0: * The value is obtained by decoding RFC 2231/5987-style encoding, michael@0: * RFC 2047-style encoding, and converting to UniChar(UTF-16) michael@0: * from charset specified in RFC 2231/2047 encoding, UTF-8, michael@0: * aFallbackCharset, the locale charset as fallback if michael@0: * TryLocaleCharset is set, and null-padding as last resort michael@0: * if all else fails. michael@0: * michael@0: *

michael@0: * This method internally invokes getParameterInternal, michael@0: * However, it does not stop at decoding RFC 2231 (the task for michael@0: * getParameterInternal but tries to cope michael@0: * with several non-standard-compliant cases mentioned below. michael@0: * michael@0: *

michael@0: * Note that a lot of MUAs put RFC 2047-encoded parameters. Unfortunately, michael@0: * this includes Mozilla as of 2003-05-30. Even more standard-ignorant MUAs, michael@0: * web servers and application servers put 'raw 8bit characters'. This will michael@0: * try to cope with all these cases as gracefully as possible. Additionally, michael@0: * it returns the language tag if the parameter is encoded per RFC 2231 and michael@0: * includes lang. michael@0: * michael@0: *

michael@0: * Note that GetParameterHTTP skips some of the workarounds used for michael@0: * mail (MIME) header fields, and thus SHOULD be used from non-mail michael@0: * code. michael@0: * michael@0: * michael@0: * @param aHeaderVal a header string to get the value of a parameter michael@0: * from. michael@0: * @param aParamName the name of a MIME header parameter (e.g. michael@0: * filename, name, charset). If empty, returns michael@0: * the first (possibly) _unnamed_ 'parameter'. michael@0: * @param aFallbackCharset fallback charset to try if the string after michael@0: * RFC 2231/2047 decoding or the raw 8bit michael@0: * string is not UTF-8 michael@0: * @param aTryLocaleCharset If set, makes yet another attempt michael@0: * with the locale charset. michael@0: * @param aLang If non-null, assigns it to a pointer michael@0: * to a string containing the value of language michael@0: * obtained from RFC 2231 parsing. Caller has to michael@0: * nsMemory::Free it. michael@0: * @return the value of aParamName in Unichar(UTF-16). michael@0: */ michael@0: AString getParameter(in ACString aHeaderVal, michael@0: in string aParamName, michael@0: in ACString aFallbackCharset, michael@0: in boolean aTryLocaleCharset, michael@0: out string aLang); michael@0: michael@0: michael@0: /** michael@0: * Like getParameter, but disabling encodings and workarounds specific to michael@0: * MIME (as opposed to HTTP). michael@0: */ michael@0: AString getParameterHTTP(in ACString aHeaderVal, michael@0: in string aParamName, michael@0: in ACString aFallbackCharset, michael@0: in boolean aTryLocaleCharset, michael@0: out string aLang); michael@0: michael@0: /** michael@0: * Given the value of a header field parameter using the encoding michael@0: * defined in RFC 5987, decode the value into a Unicode string, and extract michael@0: * the optional language parameter. michael@0: * michael@0: *

michael@0: * This function is purposefully picky; it will abort for all (most?) michael@0: * invalid inputs. This is by design. In particular, it does not support michael@0: * any character encodings other than UTF-8, in order not to promote michael@0: * non-interoperable usage. michael@0: * michael@0: *

michael@0: * Code that parses HTTP header fields (as opposed to MIME header fields) michael@0: * should use this function. michael@0: * michael@0: * @param aParamVal a header field parameter to decode. michael@0: * @param aLang will be set to the language part (possibly michael@0: * empty). michael@0: * @return the decoded parameter value. michael@0: */ michael@0: AString decodeRFC5987Param(in ACString aParamVal, michael@0: out ACString aLang); michael@0: michael@0: /** michael@0: * Given the value of a single header field (such as michael@0: * Content-Disposition and Content-Type) and the name of a parameter michael@0: * (e.g. filename, name, charset), returns the value of the parameter michael@0: * after decoding RFC 2231-style encoding. michael@0: *

michael@0: * For internal use only. The only other place where michael@0: * this needs to be invoked is |MimeHeaders_get_parameter| in michael@0: * mailnews/mime/src/mimehdrs.cpp defined as michael@0: * char * MimeHeaders_get_parameter (const char *header_value, michael@0: * const char *parm_name, michael@0: * char **charset, char **language) michael@0: * michael@0: * Otherwise, this method would have been made static. michael@0: * michael@0: * @param aHeaderVal a header string to get the value of a parameter from. michael@0: * @param aParamName the name of a MIME header parameter (e.g. michael@0: * filename, name, charset). If empty, returns michael@0: * the first (possibly) _unnamed_ 'parameter'. michael@0: * @param aCharset If non-null, it gets assigned a new pointer michael@0: * to a string containing the value of charset obtained michael@0: * from RFC 2231 parsing. Caller has to nsMemory::Free it. michael@0: * @param aLang If non-null, it gets assigned a new pointer michael@0: * to a string containing the value of language obtained michael@0: * from RFC 2231 parsing. Caller has to nsMemory::Free it. michael@0: * @return the value of aParamName after michael@0: * RFC 2231 decoding but without charset conversion. michael@0: */ michael@0: michael@0: [noscript] michael@0: string getParameterInternal(in string aHeaderVal, michael@0: in string aParamName, michael@0: out string aCharset, michael@0: out string aLang); michael@0: michael@0: michael@0: /** michael@0: * Given a header value, decodes RFC 2047-style encoding and michael@0: * returns the decoded header value in UTF-8 if either it's michael@0: * RFC-2047-encoded or aDefaultCharset is given. Otherwise, michael@0: * returns the input header value (in whatever encoding) michael@0: * as it is except that RFC 822 (using backslash) quotation and michael@0: * CRLF (if aEatContinuation is set) are stripped away michael@0: *

michael@0: * For internal use only. The only other place where this needs to be michael@0: * invoked is MIME_DecodeMimeHeader in michael@0: * mailnews/mime/src/mimehdrs.cpp defined as michael@0: * char * Mime_DecodeMimeHeader(char *header_val, const char *charset, michael@0: * bool override, bool eatcontinuation) michael@0: * michael@0: * @param aHeaderVal a header value to decode michael@0: * @param aDefaultCharset MIME charset to use in place of MIME charset michael@0: * specified in RFC 2047 style encoding michael@0: * when aOverrideCharset is set. michael@0: * @param aOverrideCharset When set, overrides MIME charset specified michael@0: * in RFC 2047 style encoding with aDefaultCharset michael@0: * @param aEatContinuation When set, removes CR/LF michael@0: * @return decoded header value michael@0: */ michael@0: [noscript] michael@0: ACString decodeRFC2047Header(in string aHeaderVal, michael@0: in string aDefaultCharset, michael@0: in boolean aOverrideCharset, michael@0: in boolean aEatContinuation); michael@0: michael@0: michael@0: /** michael@0: * Given a header parameter, decodes RFC 2047 style encoding (if it's michael@0: * not obtained from RFC 2231 encoding), converts it to michael@0: * UTF-8 and returns the result in UTF-8 if an attempt to extract michael@0: * charset info. from a few different sources succeeds. michael@0: * Otherwise, returns the input header value (in whatever encoding) michael@0: * as it is except that RFC 822 (using backslash) quotation is michael@0: * stripped off. michael@0: *

michael@0: * For internal use only. The only other place where this needs to be michael@0: * invoked is mime_decode_filename in michael@0: * mailnews/mime/src/mimehdrs.cpp defined as michael@0: * char * mime_decode_filename(char *name, const char *charset, michael@0: * MimeDisplayOptions *opt) michael@0: * michael@0: * @param aParamValue the value of a parameter to decode and convert michael@0: * @param aCharset charset obtained from RFC 2231 decoding in which michael@0: * aParamValue is encoded. If null, michael@0: * indicates that it needs to try RFC 2047, instead. michael@0: * @param aDefaultCharset MIME charset to use when aCharset is null and michael@0: * cannot be obtained per RFC 2047 (most likely michael@0: * because 'bare' string is used.) Besides, it michael@0: * overrides aCharset/MIME charset obtained from michael@0: * RFC 2047 if aOverrideCharset is set. michael@0: * @param aOverrideCharset When set, overrides MIME charset specified michael@0: * in RFC 2047 style encoding with michael@0: * aDefaultCharset michael@0: * @return decoded parameter michael@0: */ michael@0: michael@0: [noscript] michael@0: ACString decodeParameter(in ACString aParamValue, michael@0: in string aCharset, michael@0: in string aDefaultCharset, michael@0: in boolean aOverrideCharset); michael@0: }; michael@0: