DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214
/* -*- 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);
};