netwerk/mime/nsIMIMEHeaderParam.idl

   1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* vim:expandtab:shiftwidth=4:tabstop=4:
   3  */
   4 /* This Source Code Form is subject to the terms of the Mozilla Public
   5  * License, v. 2.0. If a copy of the MPL was not distributed with this
   6  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   7
   8 /*
   9  * This interface allows any module to access the routine
  10  * for MIME header parameter parsing (RFC 2231/5987)
  11  */
  12
  13 #include "nsISupports.idl"
  14
  15 [scriptable, uuid(9c9252a1-fdaf-40a2-9c2b-a3dc45e28dde)]
  16 interface nsIMIMEHeaderParam : nsISupports {
  17
  18   /**
  19    * Given the value of a single header field  (such as
  20    * Content-Disposition and Content-Type) and the name of a parameter
  21    * (e.g. filename, name, charset), returns the value of the parameter.
  22    * The value is obtained by decoding RFC 2231/5987-style encoding,
  23    * RFC 2047-style encoding, and converting to UniChar(UTF-16)
  24    * from charset specified in RFC 2231/2047 encoding, UTF-8,
  25    * <code>aFallbackCharset</code>, the locale charset as fallback if
  26    * <code>TryLocaleCharset</code> is set, and null-padding as last resort
  27    * if all else fails.
  28    *
  29    * <p>
  30    * This method internally invokes <code>getParameterInternal</code>,
  31    * However, it does not stop at decoding RFC 2231 (the task for
  32    * <code>getParameterInternal</code> but tries to cope
  33    * with several non-standard-compliant cases mentioned below.
  34    *
  35    * <p>
  36    * Note that a lot of MUAs put RFC 2047-encoded parameters. Unfortunately,
  37    * this includes Mozilla as of 2003-05-30. Even more standard-ignorant MUAs,
  38    * web servers and application servers put 'raw 8bit characters'. This will
  39    * try to cope with all these cases as gracefully as possible. Additionally,
  40    * it returns the language tag if the parameter is encoded per RFC 2231 and
  41    * includes lang.
  42    *
  43    * <p>
  44    * Note that GetParameterHTTP skips some of the workarounds used for
  45    * mail (MIME) header fields, and thus SHOULD be used from non-mail
  46    * code.
  47    *
  48    *
  49    * @param  aHeaderVal        a header string to get the value of a parameter
  50    *                           from.
  51    * @param  aParamName        the name of a MIME header parameter (e.g.
  52    *                           filename, name, charset). If empty,  returns
  53    *                           the first (possibly) _unnamed_ 'parameter'.
  54    * @param  aFallbackCharset  fallback charset to try if  the string after
  55    *                           RFC 2231/2047 decoding or the raw 8bit
  56    *                           string is not UTF-8
  57    * @param  aTryLocaleCharset If set, makes yet another attempt
  58    *                           with the locale charset.
  59    * @param  aLang             If non-null, assigns it to a pointer
  60    *                           to a string containing the value of language
  61    *                           obtained from RFC 2231 parsing. Caller has to
  62    *                           free it.
  63    * @return the value of <code>aParamName</code> in Unichar(UTF-16).
  64    */
  65   AString getParameter(in ACString aHeaderVal,
  66                        in string aParamName,
  67                        in ACString aFallbackCharset,
  68                        in boolean aTryLocaleCharset,
  69                        out string aLang);
  70
  71
  72   /**
  73    * Like getParameter, but disabling encodings and workarounds specific to
  74    * MIME (as opposed to HTTP).
  75    */
  76   AString getParameterHTTP(in ACString aHeaderVal,
  77                            in string aParamName,
  78                            in ACString aFallbackCharset,
  79                            in boolean aTryLocaleCharset,
  80                            out string aLang);
  81
  82   /**
  83    * Given the value of a header field parameter using the encoding
  84    * defined in RFC 5987, decode the value into a Unicode string, and extract
  85    * the optional language parameter.
  86    *
  87    * <p>
  88    * This function is purposefully picky; it will abort for all (most?)
  89    * invalid inputs. This is by design. In particular, it does not support
  90    * any character encodings other than UTF-8, in order not to promote
  91    * non-interoperable usage.
  92    *
  93    * <p>
  94    * Code that parses HTTP header fields (as opposed to MIME header fields)
  95    * should use this function.
  96    *
  97    * @param  aParamVal         a header field parameter to decode.
  98    * @param  aLang             will be set to the language part (possibly
  99    *                           empty).
 100    * @return the decoded parameter value.
 101    */
 102   AString decodeRFC5987Param(in ACString aParamVal,
 103                              out ACString aLang);
 104
 105   /**
 106    * Given the value of a single header field  (such as
 107    * Content-Disposition and Content-Type) and the name of a parameter
 108    * (e.g. filename, name, charset), returns the value of the parameter
 109    * after decoding RFC 2231-style encoding.
 110    * <p>
 111    * For <strong>internal use only</strong>. The only other place where
 112    * this needs to be  invoked  is  |MimeHeaders_get_parameter| in
 113    * mailnews/mime/src/mimehdrs.cpp defined as
 114    * char * MimeHeaders_get_parameter (const char *header_value,
 115    *                                   const char *parm_name,
 116    *                                   char **charset, char **language)
 117    *
 118    * Otherwise, this method would have been made static.
 119    *
 120    * @param  aHeaderVal  a header string to get the value of a parameter from.
 121    * @param  aParamName  the name of a MIME header parameter (e.g.
 122    *                     filename, name, charset). If empty,  returns
 123    *                     the first (possibly) _unnamed_ 'parameter'.
 124    * @param  aCharset    If non-null, it gets assigned a new pointer
 125    *                     to a string containing the value of charset obtained
 126    *                     from RFC 2231 parsing. Caller has to free it.
 127    * @param  aLang       If non-null, it gets assigned a new pointer
 128    *                     to a string containing the value of language obtained
 129    *                     from RFC 2231 parsing. Caller has to free it.
 130    * @return             the value of <code>aParamName</code> after
 131    *                     RFC 2231 decoding but without charset conversion.
 132    */
 133
 134   [noscript]
 135   string getParameterInternal(in ACString aHeaderVal,
 136                               in string aParamName,
 137                               out string aCharset,
 138                               out string aLang);
 139
 140
 141   /**
 142    * Given a header value, decodes RFC 2047-style encoding and
 143    * returns the decoded header value in UTF-8 if either it's
 144    * RFC-2047-encoded or aDefaultCharset is given. Otherwise,
 145    * returns the input header value (in whatever encoding)
 146    * as it is except that  RFC 822 (using backslash) quotation and
 147    * CRLF (if aEatContinuation is set) are stripped away
 148    * <p>
 149    * For internal use only. The only other place where this needs to be
 150    * invoked  is  <code>MIME_DecodeMimeHeader</code> in
 151    * mailnews/mime/src/mimehdrs.cpp defined as
 152    * char * Mime_DecodeMimeHeader(char *header_val, const char *charset,
 153    *                              bool override, bool eatcontinuation)
 154    *
 155    * @param aHeaderVal       a header value to decode
 156    * @param aDefaultCharset  MIME charset to use in place of MIME charset
 157    *                         specified in RFC 2047 style encoding
 158    *                         when <code>aOverrideCharset</code> is set.
 159    * @param aOverrideCharset When set, overrides MIME charset specified
 160    *                         in RFC 2047 style encoding with <code>aDefaultCharset</code>
 161    * @param aEatContinuation When set, removes CR/LF
 162    * @return                 decoded header value
 163    */
 164   [noscript]
 165   ACString decodeRFC2047Header(in string aHeaderVal,
 166                                in string aDefaultCharset,
 167                                in boolean aOverrideCharset,
 168                                in boolean aEatContinuation);
 169
 170
 171   /**
 172    * Given a header parameter, decodes RFC 2047 style encoding (if it's
 173    * not obtained from RFC 2231 encoding),  converts it to
 174    * UTF-8 and returns the result in UTF-8 if an attempt to extract
 175    * charset info. from a few different sources succeeds.
 176    * Otherwise,  returns the input header value (in whatever encoding)
 177    * as it is except that  RFC 822 (using backslash) quotation is
 178    * stripped off.
 179    * <p>
 180    * For internal use only. The only other place where this needs to be
 181    * invoked  is  <code>mime_decode_filename</code> in
 182    * mailnews/mime/src/mimehdrs.cpp defined as
 183    * char * mime_decode_filename(char *name, const char *charset,
 184    *                             MimeDisplayOptions *opt)
 185    *
 186    * @param aParamValue      the value of a parameter to decode and convert
 187    * @param aCharset         charset obtained from RFC 2231 decoding  in which
 188    *                         <code>aParamValue</code> is encoded. If null,
 189    *                         indicates that it needs to try RFC 2047, instead.
 190    * @param aDefaultCharset  MIME charset to use when aCharset is null and
 191    *                         cannot be obtained per RFC 2047 (most likely
 192    *                         because 'bare' string is  used.)  Besides, it
 193    *                         overrides aCharset/MIME charset obtained from
 194    *                         RFC 2047 if <code>aOverrideCharset</code>  is set.
 195    * @param aOverrideCharset When set, overrides MIME charset specified
 196    *                         in RFC 2047 style encoding with
 197    *                         <code>aDefaultCharset</code>
 198    * @return                 decoded parameter
 199    */
 200
 201   [noscript]
 202    ACString decodeParameter(in ACString aParamValue,
 203                             in string aCharset,
 204                             in string aDefaultCharset,
 205                             in boolean aOverrideCharset);
 206 };