1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/mime/nsIMIMEHeaderParam.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,207 @@
1.4 +/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* vim:expandtab:shiftwidth=4:tabstop=4:
1.6 + */
1.7 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.8 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.9 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.10 +
1.11 +/*
1.12 + * This interface allows any module to access the routine
1.13 + * for MIME header parameter parsing (RFC 2231/5987)
1.14 + */
1.15 +
1.16 +#include "nsISupports.idl"
1.17 +
1.18 +[scriptable, uuid(9c9252a1-fdaf-40a2-9c2b-a3dc45e28dde)]
1.19 +interface nsIMIMEHeaderParam : nsISupports {
1.20 +
1.21 + /**
1.22 + * Given the value of a single header field (such as
1.23 + * Content-Disposition and Content-Type) and the name of a parameter
1.24 + * (e.g. filename, name, charset), returns the value of the parameter.
1.25 + * The value is obtained by decoding RFC 2231/5987-style encoding,
1.26 + * RFC 2047-style encoding, and converting to UniChar(UTF-16)
1.27 + * from charset specified in RFC 2231/2047 encoding, UTF-8,
1.28 + * <code>aFallbackCharset</code>, the locale charset as fallback if
1.29 + * <code>TryLocaleCharset</code> is set, and null-padding as last resort
1.30 + * if all else fails.
1.31 + *
1.32 + * <p>
1.33 + * This method internally invokes <code>getParameterInternal</code>,
1.34 + * However, it does not stop at decoding RFC 2231 (the task for
1.35 + * <code>getParameterInternal</code> but tries to cope
1.36 + * with several non-standard-compliant cases mentioned below.
1.37 + *
1.38 + * <p>
1.39 + * Note that a lot of MUAs put RFC 2047-encoded parameters. Unfortunately,
1.40 + * this includes Mozilla as of 2003-05-30. Even more standard-ignorant MUAs,
1.41 + * web servers and application servers put 'raw 8bit characters'. This will
1.42 + * try to cope with all these cases as gracefully as possible. Additionally,
1.43 + * it returns the language tag if the parameter is encoded per RFC 2231 and
1.44 + * includes lang.
1.45 + *
1.46 + * <p>
1.47 + * Note that GetParameterHTTP skips some of the workarounds used for
1.48 + * mail (MIME) header fields, and thus SHOULD be used from non-mail
1.49 + * code.
1.50 + *
1.51 + *
1.52 + * @param aHeaderVal a header string to get the value of a parameter
1.53 + * from.
1.54 + * @param aParamName the name of a MIME header parameter (e.g.
1.55 + * filename, name, charset). If empty, returns
1.56 + * the first (possibly) _unnamed_ 'parameter'.
1.57 + * @param aFallbackCharset fallback charset to try if the string after
1.58 + * RFC 2231/2047 decoding or the raw 8bit
1.59 + * string is not UTF-8
1.60 + * @param aTryLocaleCharset If set, makes yet another attempt
1.61 + * with the locale charset.
1.62 + * @param aLang If non-null, assigns it to a pointer
1.63 + * to a string containing the value of language
1.64 + * obtained from RFC 2231 parsing. Caller has to
1.65 + * nsMemory::Free it.
1.66 + * @return the value of <code>aParamName</code> in Unichar(UTF-16).
1.67 + */
1.68 + AString getParameter(in ACString aHeaderVal,
1.69 + in string aParamName,
1.70 + in ACString aFallbackCharset,
1.71 + in boolean aTryLocaleCharset,
1.72 + out string aLang);
1.73 +
1.74 +
1.75 + /**
1.76 + * Like getParameter, but disabling encodings and workarounds specific to
1.77 + * MIME (as opposed to HTTP).
1.78 + */
1.79 + AString getParameterHTTP(in ACString aHeaderVal,
1.80 + in string aParamName,
1.81 + in ACString aFallbackCharset,
1.82 + in boolean aTryLocaleCharset,
1.83 + out string aLang);
1.84 +
1.85 + /**
1.86 + * Given the value of a header field parameter using the encoding
1.87 + * defined in RFC 5987, decode the value into a Unicode string, and extract
1.88 + * the optional language parameter.
1.89 + *
1.90 + * <p>
1.91 + * This function is purposefully picky; it will abort for all (most?)
1.92 + * invalid inputs. This is by design. In particular, it does not support
1.93 + * any character encodings other than UTF-8, in order not to promote
1.94 + * non-interoperable usage.
1.95 + *
1.96 + * <p>
1.97 + * Code that parses HTTP header fields (as opposed to MIME header fields)
1.98 + * should use this function.
1.99 + *
1.100 + * @param aParamVal a header field parameter to decode.
1.101 + * @param aLang will be set to the language part (possibly
1.102 + * empty).
1.103 + * @return the decoded parameter value.
1.104 + */
1.105 + AString decodeRFC5987Param(in ACString aParamVal,
1.106 + out ACString aLang);
1.107 +
1.108 + /**
1.109 + * Given the value of a single header field (such as
1.110 + * Content-Disposition and Content-Type) and the name of a parameter
1.111 + * (e.g. filename, name, charset), returns the value of the parameter
1.112 + * after decoding RFC 2231-style encoding.
1.113 + * <p>
1.114 + * For <strong>internal use only</strong>. The only other place where
1.115 + * this needs to be invoked is |MimeHeaders_get_parameter| in
1.116 + * mailnews/mime/src/mimehdrs.cpp defined as
1.117 + * char * MimeHeaders_get_parameter (const char *header_value,
1.118 + * const char *parm_name,
1.119 + * char **charset, char **language)
1.120 + *
1.121 + * Otherwise, this method would have been made static.
1.122 + *
1.123 + * @param aHeaderVal a header string to get the value of a parameter from.
1.124 + * @param aParamName the name of a MIME header parameter (e.g.
1.125 + * filename, name, charset). If empty, returns
1.126 + * the first (possibly) _unnamed_ 'parameter'.
1.127 + * @param aCharset If non-null, it gets assigned a new pointer
1.128 + * to a string containing the value of charset obtained
1.129 + * from RFC 2231 parsing. Caller has to nsMemory::Free it.
1.130 + * @param aLang If non-null, it gets assigned a new pointer
1.131 + * to a string containing the value of language obtained
1.132 + * from RFC 2231 parsing. Caller has to nsMemory::Free it.
1.133 + * @return the value of <code>aParamName</code> after
1.134 + * RFC 2231 decoding but without charset conversion.
1.135 + */
1.136 +
1.137 + [noscript]
1.138 + string getParameterInternal(in string aHeaderVal,
1.139 + in string aParamName,
1.140 + out string aCharset,
1.141 + out string aLang);
1.142 +
1.143 +
1.144 + /**
1.145 + * Given a header value, decodes RFC 2047-style encoding and
1.146 + * returns the decoded header value in UTF-8 if either it's
1.147 + * RFC-2047-encoded or aDefaultCharset is given. Otherwise,
1.148 + * returns the input header value (in whatever encoding)
1.149 + * as it is except that RFC 822 (using backslash) quotation and
1.150 + * CRLF (if aEatContinuation is set) are stripped away
1.151 + * <p>
1.152 + * For internal use only. The only other place where this needs to be
1.153 + * invoked is <code>MIME_DecodeMimeHeader</code> in
1.154 + * mailnews/mime/src/mimehdrs.cpp defined as
1.155 + * char * Mime_DecodeMimeHeader(char *header_val, const char *charset,
1.156 + * bool override, bool eatcontinuation)
1.157 + *
1.158 + * @param aHeaderVal a header value to decode
1.159 + * @param aDefaultCharset MIME charset to use in place of MIME charset
1.160 + * specified in RFC 2047 style encoding
1.161 + * when <code>aOverrideCharset</code> is set.
1.162 + * @param aOverrideCharset When set, overrides MIME charset specified
1.163 + * in RFC 2047 style encoding with <code>aDefaultCharset</code>
1.164 + * @param aEatContinuation When set, removes CR/LF
1.165 + * @return decoded header value
1.166 + */
1.167 + [noscript]
1.168 + ACString decodeRFC2047Header(in string aHeaderVal,
1.169 + in string aDefaultCharset,
1.170 + in boolean aOverrideCharset,
1.171 + in boolean aEatContinuation);
1.172 +
1.173 +
1.174 + /**
1.175 + * Given a header parameter, decodes RFC 2047 style encoding (if it's
1.176 + * not obtained from RFC 2231 encoding), converts it to
1.177 + * UTF-8 and returns the result in UTF-8 if an attempt to extract
1.178 + * charset info. from a few different sources succeeds.
1.179 + * Otherwise, returns the input header value (in whatever encoding)
1.180 + * as it is except that RFC 822 (using backslash) quotation is
1.181 + * stripped off.
1.182 + * <p>
1.183 + * For internal use only. The only other place where this needs to be
1.184 + * invoked is <code>mime_decode_filename</code> in
1.185 + * mailnews/mime/src/mimehdrs.cpp defined as
1.186 + * char * mime_decode_filename(char *name, const char *charset,
1.187 + * MimeDisplayOptions *opt)
1.188 + *
1.189 + * @param aParamValue the value of a parameter to decode and convert
1.190 + * @param aCharset charset obtained from RFC 2231 decoding in which
1.191 + * <code>aParamValue</code> is encoded. If null,
1.192 + * indicates that it needs to try RFC 2047, instead.
1.193 + * @param aDefaultCharset MIME charset to use when aCharset is null and
1.194 + * cannot be obtained per RFC 2047 (most likely
1.195 + * because 'bare' string is used.) Besides, it
1.196 + * overrides aCharset/MIME charset obtained from
1.197 + * RFC 2047 if <code>aOverrideCharset</code> is set.
1.198 + * @param aOverrideCharset When set, overrides MIME charset specified
1.199 + * in RFC 2047 style encoding with
1.200 + * <code>aDefaultCharset</code>
1.201 + * @return decoded parameter
1.202 + */
1.203 +
1.204 + [noscript]
1.205 + ACString decodeParameter(in ACString aParamValue,
1.206 + in string aCharset,
1.207 + in string aDefaultCharset,
1.208 + in boolean aOverrideCharset);
1.209 +};
1.210 +
