netwerk/base/public/nsINetUtil.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * the Mozilla Foundation.
  19  * Portions created by the Initial Developer are Copyright (C) 2005
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *   Boris Zbarsky <bzbarsky@mit.edu> (original author)
  24  *   Benjamin Smedberg <benjamin@smedbergs.us>
  25  *   Prasad Sunkari <prasad@medhas.org>
  26  *
  27  * Alternatively, the contents of this file may be used under the terms of
  28  * either the GNU General Public License Version 2 or later (the "GPL"), or
  29  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  30  * in which case the provisions of the GPL or the LGPL are applicable instead
  31  * of those above. If you wish to allow use of your version of this file only
  32  * under the terms of either the GPL or the LGPL, and not to allow others to
  33  * use your version of this file under the terms of the MPL, indicate your
  34  * decision by deleting the provisions above and replace them with the notice
  35  * and other provisions required by the GPL or the LGPL. If you do not delete
  36  * the provisions above, a recipient may use your version of this file under
  37  * the terms of any one of the MPL, the GPL or the LGPL.
  38  *
  39  * ***** END LICENSE BLOCK ***** */
  40
  41 #include "nsISupports.idl"
  42
  43 interface nsIURI;
  44 interface nsIPrefBranch;
  45
  46 /**
  47  * nsINetUtil provides various network-related utility methods.
  48  */
  49 [scriptable, uuid(57322c6f-f4ec-4e46-8253-b74be220de16)]
  50 interface nsINetUtil : nsISupports
  51 {
  52   /**
  53    * Parse a content-type header and return the content type and
  54    * charset (if any).
  55    *
  56    * @param aTypeHeader the header string to parse
  57    * @param [out] aCharset the charset parameter specified in the
  58    *              header, if any.
  59    * @param [out] aHadCharset whether a charset was explicitly specified.
  60    * @return the MIME type specified in the header, in lower-case.
  61    */
  62   AUTF8String parseContentType(in AUTF8String aTypeHeader,
  63                                out AUTF8String aCharset,
  64                                out boolean aHadCharset);
  65
  66   /**
  67    * Test whether the given URI's handler has the given protocol flags.
  68    *
  69    * @param aURI the URI in question
  70    * @param aFlags the flags we're testing for.
  71    *
  72    * @return whether the protocol handler for aURI has all the flags
  73    *         in aFlags.
  74    */
  75   boolean protocolHasFlags(in nsIURI aURI, in unsigned long aFlag);
  76
  77   /**
  78    * Test whether the protocol handler for this URI or that for any of
  79    * its inner URIs has the given protocol flags.  This will QI aURI to
  80    * nsINestedURI and walk the nested URI chain.
  81    *
  82    * @param aURI the URI in question
  83    * @param aFlags the flags we're testing for.
  84    *
  85    * @return whether any of the protocol handlers involved have all the flags
  86    *         in aFlags.
  87    */
  88   boolean URIChainHasFlags(in nsIURI aURI, in unsigned long aFlags);
  89
  90   /**
  91    * Take aURI and produce an immutable version of it for the caller.  If aURI
  92    * is immutable this will be aURI itself; otherwise this will be a clone,
  93    * marked immutable if possible.  Passing null to this method is allowed; in
  94    * that case it will return null.
  95    */
  96   nsIURI toImmutableURI(in nsIURI aURI);
  97
  98   /** Escape every character with its %XX-escaped equivalent */
  99   const unsigned long ESCAPE_ALL = 0;
 100
 101   /** Leave alphanumeric characters intact and %XX-escape all others */
 102   const unsigned long ESCAPE_XALPHAS = 1;
 103
 104   /** Leave alphanumeric characters intact, convert spaces to '+',
 105       %XX-escape all others */
 106   const unsigned long ESCAPE_XPALPHAS = 2;
 107
 108   /** Leave alphanumeric characters and forward slashes intact,
 109       %XX-escape all others */
 110   const unsigned long ESCAPE_URL_PATH = 4;
 111
 112   /**
 113    * escape a string with %00-style escaping
 114    */
 115   ACString escapeString(in ACString aString, in unsigned long aEscapeType);
 116
 117   /** %XX-escape URL scheme */
 118   const unsigned long ESCAPE_URL_SCHEME = 1;
 119
 120   /** %XX-escape username in the URL */
 121   const unsigned long ESCAPE_URL_USERNAME = 1 << 1;
 122
 123   /** %XX-escape password in the URL */
 124   const unsigned long ESCAPE_URL_PASSWORD = 1 << 2;
 125
 126   /** %XX-escape URL host */
 127   const unsigned long ESCAPE_URL_HOST = 1 << 3;
 128
 129   /** %XX-escape URL directory */
 130   const unsigned long ESCAPE_URL_DIRECTORY = 1 << 4;
 131
 132   /** %XX-escape file basename in the URL */
 133   const unsigned long ESCAPE_URL_FILE_BASENAME = 1 << 5;
 134
 135   /** %XX-escape file extension in the URL */
 136   const unsigned long ESCAPE_URL_FILE_EXTENSION = 1 << 6;
 137
 138   /** %XX-escape URL parameters */
 139   const unsigned long ESCAPE_URL_PARAM = 1 << 7;
 140
 141   /** %XX-escape URL query */
 142   const unsigned long ESCAPE_URL_QUERY = 1 << 8;
 143
 144   /** %XX-escape URL ref */
 145   const unsigned long ESCAPE_URL_REF = 1 << 9;
 146
 147   /** %XX-escape URL path - same as escaping directory, basename and extension */
 148   const unsigned long ESCAPE_URL_FILEPATH =
 149     ESCAPE_URL_DIRECTORY | ESCAPE_URL_FILE_BASENAME | ESCAPE_URL_FILE_EXTENSION;
 150
 151   /** %XX-escape scheme, username, password, host, path, params, query and ref */
 152   const unsigned long ESCAPE_URL_MINIMAL =
 153     ESCAPE_URL_SCHEME | ESCAPE_URL_USERNAME | ESCAPE_URL_PASSWORD |
 154     ESCAPE_URL_HOST   | ESCAPE_URL_FILEPATH | ESCAPE_URL_PARAM    |
 155     ESCAPE_URL_QUERY  | ESCAPE_URL_REF;
 156
 157   /** Force %XX-escaping of already escaped sequences */
 158   const unsigned long ESCAPE_URL_FORCED = 1 << 10;
 159
 160   /** Skip non-ascii octets, %XX-escape all others */
 161   const unsigned long ESCAPE_URL_ONLY_ASCII = 1 << 11;
 162
 163   /**
 164    * Skip graphic octets (0x20-0x7E) when escaping
 165    * Skips all ASCII octets (0x00-0x7F) when unescaping
 166    */
 167   const unsigned long ESCAPE_URL_ONLY_NONASCII = 1 << 12;
 168
 169   /** Force %XX-escape of colon */
 170   const unsigned long ESCAPE_URL_COLON = 1 << 14;
 171
 172   /** Skip C0 and DEL from unescaping */
 173   const unsigned long ESCAPE_URL_SKIP_CONTROL = 1 << 15;
 174
 175   /**
 176    * %XX-Escape invalid chars in a URL segment.
 177    *
 178    * @param aStr the URL to be escaped
 179    * @param aFlags the URL segment type flags
 180    *
 181    * @return the escaped string (the string itself if escaping did not happen)
 182    *
 183    */
 184   ACString escapeURL(in ACString aStr, in unsigned long aFlags);
 185
 186   /**
 187    * Expands URL escape sequences
 188    *
 189    * @param aStr the URL to be unescaped
 190    * @param aFlags only ESCAPE_URL_ONLY_NONASCII and ESCAPE_URL_SKIP_CONTROL
 191    *               are recognized.  If |aFlags| is 0 all escape sequences are
 192    *               unescaped
 193    * @return unescaped string
 194    */
 195   ACString unescapeString(in ACString aStr, in unsigned long aFlags);
 196
 197   /**
 198    * Extract the charset parameter location and value from a content-type
 199    * header.
 200    *
 201    * @param aTypeHeader the header string to parse
 202    * @param [out] aCharset the charset parameter specified in the
 203    *              header, if any.
 204    * @param [out] aCharsetStart index of the start of the charset parameter
 205    *              (the ';' separating it from what came before) in aTypeHeader.
 206    *              If this function returns false, this argument will still be
 207    *              set, to the index of the location where a new charset should
 208    *              be inserted.
 209    * @param [out] aCharsetEnd index of the end of the charset parameter (the
 210    *              ';' separating it from what comes after, or the end
 211    *              of the string) in aTypeHeader.  If this function returns
 212    *              false, this argument will still be set, to the index of the
 213    *              location where a new charset should be inserted.
 214    *
 215    * @return whether a charset parameter was found.  This can be false even in
 216    * cases when parseContentType would claim to have a charset, if the type
 217    * that won out does not have a charset parameter specified.
 218    */
 219   boolean extractCharsetFromContentType(in AUTF8String aTypeHeader,
 220                                         out AUTF8String aCharset,
 221                                         out long aCharsetStart,
 222                                         out long aCharsetEnd);
 223 };