/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ /* vim:expandtab:shiftwidth=4:tabstop=4: */ /* ***** BEGIN LICENSE BLOCK ***** * Version: MPL 1.1/GPL 2.0/LGPL 2.1 * * The contents of this file are subject to the Mozilla Public License Version * 1.1 (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * http://www.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License * for the specific language governing rights and limitations under the * License. * * The Original Code is mozilla.org code. * * The Initial Developer of the Original Code is * Jungshik Shin * Portions created by the Initial Developer are Copyright (C) 2003. * the Initial Developer. All Rights Reserved. * * Contributor(s): * * Alternatively, the contents of this file may be used under the terms of * either the GNU General Public License Version 2 or later (the "GPL"), or * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), * in which case the provisions of the GPL or the LGPL are applicable instead * of those above. If you wish to allow use of your version of this file only * under the terms of either the GPL or the LGPL, and not to allow others to * use your version of this file under the terms of the MPL, indicate your * decision by deleting the provisions above and replace them with the notice * and other provisions required by the GPL or the LGPL. If you do not delete * the provisions above, a recipient may use your version of this file under * the terms of any one of the MPL, the GPL or the LGPL. * * ***** END LICENSE BLOCK ***** */ /* * This interface allows any module to access the routine * for MIME header parameter parsing (RFC 2231) */ #include "nsISupports.idl" [scriptable, uuid(ddbbdfb8-a1c0-4dd5-a31b-5d2a7a3bb6ec)] 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-style encoding, * RFC 2047-style encoding, and converting to UniChar(UTF-16) * from charset specified in RFC 2231/2047 encoding, UTF-8, * aFallbackCharset, the locale charset as fallback if * TryLocaleCharset is set, and null-padding as last resort * if all else fails. * *

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

* Note that a lot of MUAs and HTTP servers put RFC 2047-encoded parameters * in mail headers and HTTP headers. 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. * * * * @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 * nsMemory::Free it. * @return the value of aParamName in Unichar(UTF-16). */ AString getParameter(in ACString aHeaderVal, in string aParamName, in ACString aFallbackCharset, in boolean aTryLocaleCharset, out string 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. *

* For internal use only. 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 nsMemory::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 nsMemory::Free it. * @return the value of aParamName 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 *

* For internal use only. The only other place where this needs to be * invoked is MIME_DecodeMimeHeader in * mailnews/mime/src/mimehdrs.cpp defined as * char * Mime_DecodeMimeHeader(char *header_val, const char *charset, * PRBool override, PRBool 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 aOverrideCharset is set. * @param aOverrideCharset When set, overrides MIME charset specified * in RFC 2047 style encoding with aDefaultCharset * @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. *

* For internal use only. The only other place where this needs to be * invoked is mime_decode_filename 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 * aParamValue 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 aOverrideCharset is set. * @param aOverrideCharset When set, overrides MIME charset specified * in RFC 2047 style encoding with * aDefaultCharset * @return decoded parameter */ [noscript] ACString decodeParameter(in ACString aParamValue, in string aCharset, in string aDefaultCharset, in boolean aOverrideCharset); };