summaryrefslogtreecommitdiffstats
path: root/netwerk/mime/nsIMIMEHeaderParam.idl
diff options
context:
space:
mode:
Diffstat (limited to 'netwerk/mime/nsIMIMEHeaderParam.idl')
-rw-r--r--netwerk/mime/nsIMIMEHeaderParam.idl207
1 files changed, 207 insertions, 0 deletions
diff --git a/netwerk/mime/nsIMIMEHeaderParam.idl b/netwerk/mime/nsIMIMEHeaderParam.idl
new file mode 100644
index 000000000..ffe8403d6
--- /dev/null
+++ b/netwerk/mime/nsIMIMEHeaderParam.idl
@@ -0,0 +1,207 @@
+/* -*- 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 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);
+};
+