mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-12-14 02:31:59 +00:00
215 lines
10 KiB
Plaintext
215 lines
10 KiB
Plaintext
/* -*- 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 <jshin@mailaps.org>
|
|
* 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/5987)
|
|
*/
|
|
|
|
#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,
|
|
* <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 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 <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 using RFC 5987 instead of 2231. This removes
|
|
* support for header parameter continuations (foo*0, foo*1, etc).
|
|
*/
|
|
AString getParameter5987(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.
|
|
* <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 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 <code>aParamName</code> 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
|
|
* <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);
|
|
};
|
|
|