netwerk/base/nsINetUtil.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 interface nsIURI;
   9 interface nsIPrefBranch;
  10
  11 /**
  12  * nsINetUtil provides various network-related utility methods.
  13  */
  14 [scriptable, uuid(fe2625ec-b884-4df1-b39c-9e830e47aa94)]
  15 interface nsINetUtil : nsISupports
  16 {
  17   /**
  18    * Parse a Content-Type header value in strict mode.  This is a more
  19    * conservative parser that reject things that violate RFC 7231 section
  20    * 3.1.1.1.  This is typically useful for parsing Content-Type header values
  21    * that are used for HTTP requests, and those that are used to make security
  22    * decisions.
  23    *
  24    * @param aTypeHeader the header string to parse
  25    * @param [out] aCharset the charset parameter specified in the
  26    *              header, if any.
  27    * @param [out] aHadCharset whether a charset was explicitly specified.
  28    * @return the MIME type specified in the header, in lower-case.
  29    */
  30   AUTF8String parseRequestContentType(in AUTF8String aTypeHeader,
  31                                       out AUTF8String aCharset,
  32                                       out boolean aHadCharset);
  33
  34   /**
  35    * Parse a Content-Type header value in relaxed mode.  This is a more
  36    * permissive parser that ignores things that go against RFC 7231 section
  37    * 3.1.1.1.  This is typically useful for parsing Content-Type header values
  38    * received from web servers where we want to make a best effort attempt
  39    * at extracting a useful MIME type and charset.
  40    *
  41    * NOTE: DO NOT USE THIS if you're going to make security decisions
  42    * based on the result.
  43    *
  44    * @param aTypeHeader the header string to parse
  45    * @param [out] aCharset the charset parameter specified in the
  46    *              header, if any.
  47    * @param [out] aHadCharset whether a charset was explicitly specified.
  48    * @return the MIME type specified in the header, in lower-case.
  49    */
  50   AUTF8String parseResponseContentType(in AUTF8String aTypeHeader,
  51                                        out AUTF8String aCharset,
  52                                        out boolean aHadCharset);
  53
  54   /**
  55    * Test whether the given URI's handler has the given protocol flags.
  56    *
  57    * @param aURI the URI in question
  58    * @param aFlags the flags we're testing for.
  59    *
  60    * @return whether the protocol handler for aURI has all the flags
  61    *         in aFlags.
  62    */
  63   boolean protocolHasFlags(in nsIURI aURI, in unsigned long aFlag);
  64
  65   /**
  66    * Test whether the protocol handler for this URI or that for any of
  67    * its inner URIs has the given protocol flags.  This will QI aURI to
  68    * nsINestedURI and walk the nested URI chain.
  69    *
  70    * @param aURI the URI in question
  71    * @param aFlags the flags we're testing for.
  72    *
  73    * @return whether any of the protocol handlers involved have all the flags
  74    *         in aFlags.
  75    */
  76   boolean URIChainHasFlags(in nsIURI aURI, in unsigned long aFlags);
  77
  78   /** Escape every character with its %XX-escaped equivalent */
  79   const unsigned long ESCAPE_ALL = 0;
  80
  81   /** Leave alphanumeric characters intact and %XX-escape all others */
  82   const unsigned long ESCAPE_XALPHAS = 1;
  83
  84   /** Leave alphanumeric characters intact, convert spaces to '+',
  85       %XX-escape all others */
  86   const unsigned long ESCAPE_XPALPHAS = 2;
  87
  88   /** Leave alphanumeric characters and forward slashes intact,
  89       %XX-escape all others */
  90   const unsigned long ESCAPE_URL_PATH = 4;
  91
  92   /** Additional encoding for Apple's NSURL compatibility.
  93       Like XALPHAS, but leave '%' to avoid double encoding, '+', and '/'.
  94       %XX-escape all others */
  95   const unsigned long ESCAPE_URL_APPLE_EXTRA = 8;
  96
  97   /**
  98    * escape a string with %00-style escaping
  99    */
 100   ACString escapeString(in ACString aString, in unsigned long aEscapeType);
 101
 102   /** %XX-escape URL scheme */
 103   const unsigned long ESCAPE_URL_SCHEME = 1;
 104
 105   /** %XX-escape username in the URL */
 106   const unsigned long ESCAPE_URL_USERNAME = 1 << 1;
 107
 108   /** %XX-escape password in the URL */
 109   const unsigned long ESCAPE_URL_PASSWORD = 1 << 2;
 110
 111   /** %XX-escape URL host */
 112   const unsigned long ESCAPE_URL_HOST = 1 << 3;
 113
 114   /** %XX-escape URL directory */
 115   const unsigned long ESCAPE_URL_DIRECTORY = 1 << 4;
 116
 117   /** %XX-escape file basename in the URL */
 118   const unsigned long ESCAPE_URL_FILE_BASENAME = 1 << 5;
 119
 120   /** %XX-escape file extension in the URL */
 121   const unsigned long ESCAPE_URL_FILE_EXTENSION = 1 << 6;
 122
 123   /** %XX-escape URL parameters */
 124   const unsigned long ESCAPE_URL_PARAM = 1 << 7;
 125
 126   /** %XX-escape URL query */
 127   const unsigned long ESCAPE_URL_QUERY = 1 << 8;
 128
 129   /** %XX-escape URL ref */
 130   const unsigned long ESCAPE_URL_REF = 1 << 9;
 131
 132   /** %XX-escape URL path - same as escaping directory, basename and extension */
 133   const unsigned long ESCAPE_URL_FILEPATH =
 134     ESCAPE_URL_DIRECTORY | ESCAPE_URL_FILE_BASENAME | ESCAPE_URL_FILE_EXTENSION;
 135
 136   /** %XX-escape scheme, username, password, host, path, params, query and ref */
 137   const unsigned long ESCAPE_URL_MINIMAL =
 138     ESCAPE_URL_SCHEME | ESCAPE_URL_USERNAME | ESCAPE_URL_PASSWORD |
 139     ESCAPE_URL_HOST   | ESCAPE_URL_FILEPATH | ESCAPE_URL_PARAM    |
 140     ESCAPE_URL_QUERY  | ESCAPE_URL_REF;
 141
 142   /** Force %XX-escaping of already escaped sequences */
 143   const unsigned long ESCAPE_URL_FORCED = 1 << 10;
 144
 145   /** Skip non-ascii octets, %XX-escape all others */
 146   const unsigned long ESCAPE_URL_ONLY_ASCII = 1 << 11;
 147
 148   /**
 149    * Skip graphic octets (0x20-0x7E) when escaping
 150    * Skips all ASCII octets (0x00-0x7F) when unescaping
 151    */
 152   const unsigned long ESCAPE_URL_ONLY_NONASCII = 1 << 12;
 153
 154   /** Force %XX-escape of colon */
 155   const unsigned long ESCAPE_URL_COLON = 1 << 14;
 156
 157   /** Skip C0 and DEL from unescaping */
 158   const unsigned long ESCAPE_URL_SKIP_CONTROL = 1 << 15;
 159
 160   /** %XX-escape external protocol handler URL */
 161   const unsigned long ESCAPE_URL_EXT_HANDLER = 1 << 17;
 162
 163   /**
 164    * %XX-Escape invalid chars in a URL segment.
 165    *
 166    * @param aStr the URL to be escaped
 167    * @param aFlags the URL segment type flags
 168    *
 169    * @return the escaped string (the string itself if escaping did not happen)
 170    *
 171    */
 172   ACString escapeURL(in ACString aStr, in unsigned long aFlags);
 173
 174   /**
 175    * Expands URL escape sequences
 176    *
 177    * @param aStr the URL to be unescaped
 178    * @param aFlags only ESCAPE_URL_ONLY_NONASCII and ESCAPE_URL_SKIP_CONTROL
 179    *               are recognized.  If |aFlags| is 0 all escape sequences are
 180    *               unescaped
 181    * @return unescaped string
 182    */
 183   ACString unescapeString(in AUTF8String aStr, in unsigned long aFlags);
 184
 185   /**
 186    * Extract the charset parameter location and value from a content-type
 187    * header.
 188    *
 189    * @param aTypeHeader the header string to parse
 190    * @param [out] aCharset the charset parameter specified in the
 191    *              header, if any.
 192    * @param [out] aCharsetStart index of the start of the charset parameter
 193    *              (the ';' separating it from what came before) in aTypeHeader.
 194    *              If this function returns false, this argument will still be
 195    *              set, to the index of the location where a new charset should
 196    *              be inserted.
 197    * @param [out] aCharsetEnd index of the end of the charset parameter (the
 198    *              ';' separating it from what comes after, or the end
 199    *              of the string) in aTypeHeader.  If this function returns
 200    *              false, this argument will still be set, to the index of the
 201    *              location where a new charset should be inserted.
 202    *
 203    * @return whether a charset parameter was found.  This can be false even in
 204    * cases when parseContentType would claim to have a charset, if the type
 205    * that won out does not have a charset parameter specified.
 206    */
 207   boolean extractCharsetFromContentType(in AUTF8String aTypeHeader,
 208                                         out AUTF8String aCharset,
 209                                         out long aCharsetStart,
 210                                         out long aCharsetEnd);
 211
 212   /**
 213    * This is test-only. Send an IPC message to let socket process send a
 214    * telemetry.
 215    */
 216   void socketProcessTelemetryPing();
 217
 218   /**
 219    * This is a void method that is C++ implemented and always
 220    * returns NS_ERROR_NOT_IMPLEMENTED. To be used for testing.
 221    */
 222   void notImplemented();
 223 };