netwerk/base/nsURLHelper.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   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 #ifndef nsURLHelper_h__
   7 #define nsURLHelper_h__
   8
   9 #include "nsString.h"
  10 #include "nsTArray.h"
  11 #include "nsASCIIMask.h"
  12 #include <mozilla/Maybe.h>
  13 #include <mozilla/CompactPair.h>
  14
  15 class nsIFile;
  16 class nsIURLParser;
  17
  18 enum netCoalesceFlags {
  19   NET_COALESCE_NORMAL = 0,
  20
  21   /**
  22    * retains /../ that reach above dir root (useful for FTP
  23    * servers in which the root of the FTP URL is not necessarily
  24    * the root of the FTP filesystem).
  25    */
  26   NET_COALESCE_ALLOW_RELATIVE_ROOT = 1 << 0,
  27
  28   /**
  29    * recognizes /%2F and // as markers for the root directory
  30    * and handles them properly.
  31    */
  32   NET_COALESCE_DOUBLE_SLASH_IS_ROOT = 1 << 1
  33 };
  34
  35 //----------------------------------------------------------------------------
  36 // This module contains some private helper functions related to URL parsing.
  37 //----------------------------------------------------------------------------
  38
  39 /* shutdown frees URL parser */
  40 void net_ShutdownURLHelper();
  41 #ifdef XP_MACOSX
  42 void net_ShutdownURLHelperOSX();
  43 #endif
  44
  45 /* access URL parsers */
  46 nsIURLParser* net_GetAuthURLParser();
  47 nsIURLParser* net_GetNoAuthURLParser();
  48 nsIURLParser* net_GetStdURLParser();
  49
  50 /* convert between nsIFile and file:// URL spec
  51  * net_GetURLSpecFromFile does an extra stat, so callers should
  52  * avoid it if possible in favor of net_GetURLSpecFromActualFile
  53  * and net_GetURLSpecFromDir */
  54 nsresult net_GetURLSpecFromFile(nsIFile*, nsACString&);
  55 nsresult net_GetURLSpecFromDir(nsIFile*, nsACString&);
  56 nsresult net_GetURLSpecFromActualFile(nsIFile*, nsACString&);
  57 nsresult net_GetFileFromURLSpec(const nsACString&, nsIFile**);
  58
  59 /* extract file path components from file:// URL */
  60 nsresult net_ParseFileURL(const nsACString& inURL, nsACString& outDirectory,
  61                           nsACString& outFileBaseName,
  62                           nsACString& outFileExtension);
  63
  64 // handle .. in dirs while resolving URLs (path is UTF-8)
  65 // Return a tuple containing:
  66 // (index of the last slash, index of the end of the basename)
  67 mozilla::Maybe<mozilla::CompactPair<uint32_t, uint32_t>> net_CoalesceDirs(
  68     netCoalesceFlags flags, char* path);
  69
  70 /**
  71  * Check if a URL is absolute
  72  *
  73  * @param inURL     URL spec
  74  * @return true if the given spec represents an absolute URL
  75  */
  76 bool net_IsAbsoluteURL(const nsACString& uri);
  77
  78 /**
  79  * Extract URI-Scheme if possible
  80  *
  81  * @param inURI     URI spec
  82  * @param scheme    scheme copied to this buffer on return. Is lowercase.
  83  */
  84 nsresult net_ExtractURLScheme(const nsACString& inURI, nsACString& scheme);
  85
  86 /* check that the given scheme conforms to RFC 2396 */
  87 bool net_IsValidScheme(const nsACString& scheme);
  88
  89 /**
  90  * This function strips out all C0 controls and space at the beginning and end
  91  * of the URL and filters out \r, \n, \t from the middle of the URL.  This makes
  92  * it safe to call on things like javascript: urls or data: urls, where we may
  93  * in fact run into whitespace that is not properly encoded.
  94  *
  95  * @param input the URL spec we want to filter
  96  * @param result the out param to write to if filtering happens
  97  */
  98 void net_FilterURIString(const nsACString& input, nsACString& result);
  99
 100 /**
 101  * This function performs character stripping just like net_FilterURIString,
 102  * with the added benefit of also performing percent escaping of dissallowed
 103  * characters, all in one pass. Saving one pass is very important when operating
 104  * on really large strings.
 105  *
 106  * @param aInput the URL spec we want to filter
 107  * @param aFlags the flags which control which characters we escape
 108  * @param aFilterMask a mask of characters that should excluded from the result
 109  * @param aResult the out param to write to if filtering happens
 110  */
 111 nsresult net_FilterAndEscapeURI(const nsACString& aInput, uint32_t aFlags,
 112                                 const ASCIIMaskArray& aFilterMask,
 113                                 nsACString& aResult);
 114
 115 #if defined(XP_WIN)
 116 /**
 117  * On Win32 and OS/2 system's a back-slash in a file:// URL is equivalent to a
 118  * forward-slash.  This function maps any back-slashes to forward-slashes.
 119  *
 120  * @param aURL
 121  *        The URL string to normalize (UTF-8 encoded).  This can be a
 122  *        relative URL segment.
 123  * @param aResultBuf
 124  *        The resulting string is appended to this string.  If the input URL
 125  *        is already normalized, then aResultBuf is unchanged.
 126  *
 127  * @returns false if aURL is already normalized.  Otherwise, returns true.
 128  */
 129 bool net_NormalizeFileURL(const nsACString& aURL, nsCString& aResultBuf);
 130 #endif
 131
 132 /*****************************************************************************
 133  * generic string routines follow (XXX move to someplace more generic).
 134  */
 135
 136 /* convert to lower case */
 137 void net_ToLowerCase(char* str, uint32_t length);
 138 void net_ToLowerCase(char* str);
 139
 140 /**
 141  * returns pointer to first character of |str| in the given set.  if not found,
 142  * then |end| is returned.  stops prematurely if a null byte is encountered,
 143  * and returns the address of the null byte.
 144  */
 145 char* net_FindCharInSet(const char* iter, const char* stop, const char* set);
 146
 147 /**
 148  * returns pointer to first character of |str| NOT in the given set.  if all
 149  * characters are in the given set, then |end| is returned.  if '\0' is not
 150  * included in |set|, then stops prematurely if a null byte is encountered,
 151  * and returns the address of the null byte.
 152  */
 153 char* net_FindCharNotInSet(const char* iter, const char* stop, const char* set);
 154
 155 /**
 156  * returns pointer to last character of |str| NOT in the given set.  if all
 157  * characters are in the given set, then |str - 1| is returned.
 158  */
 159 char* net_RFindCharNotInSet(const char* stop, const char* iter,
 160                             const char* set);
 161
 162 /**
 163  * Parses a content-type header and returns the content type and
 164  * charset (if any).  aCharset is not modified if no charset is
 165  * specified in anywhere in aHeaderStr.  In that case (no charset
 166  * specified), aHadCharset is set to false.  Otherwise, it's set to
 167  * true.  Note that aContentCharset can be empty even if aHadCharset
 168  * is true.
 169  *
 170  * This parsing is suitable for HTTP request.  Use net_ParseContentType
 171  * for parsing this header in HTTP responses.
 172  */
 173 void net_ParseRequestContentType(const nsACString& aHeaderStr,
 174                                  nsACString& aContentType,
 175                                  nsACString& aContentCharset,
 176                                  bool* aHadCharset);
 177
 178 /**
 179  * Parses a content-type header and returns the content type and
 180  * charset (if any).  aCharset is not modified if no charset is
 181  * specified in anywhere in aHeaderStr.  In that case (no charset
 182  * specified), aHadCharset is set to false.  Otherwise, it's set to
 183  * true.  Note that aContentCharset can be empty even if aHadCharset
 184  * is true.
 185  */
 186 void net_ParseContentType(const nsACString& aHeaderStr,
 187                           nsACString& aContentType, nsACString& aContentCharset,
 188                           bool* aHadCharset);
 189 /**
 190  * As above, but also returns the start and end indexes for the charset
 191  * parameter in aHeaderStr.  These are indices for the entire parameter, NOT
 192  * just the value.  If there is "effectively" no charset parameter (e.g. if an
 193  * earlier type with one is overridden by a later type without one),
 194  * *aHadCharset will be true but *aCharsetStart will be set to -1.  Note that
 195  * it's possible to have aContentCharset empty and *aHadCharset true when
 196  * *aCharsetStart is nonnegative; this corresponds to charset="".
 197  */
 198 void net_ParseContentType(const nsACString& aHeaderStr,
 199                           nsACString& aContentType, nsACString& aContentCharset,
 200                           bool* aHadCharset, int32_t* aCharsetStart,
 201                           int32_t* aCharsetEnd);
 202
 203 /* inline versions */
 204
 205 /* remember the 64-bit platforms ;-) */
 206 #define NET_MAX_ADDRESS ((char*)UINTPTR_MAX)
 207
 208 inline char* net_FindCharInSet(const char* str, const char* set) {
 209   return net_FindCharInSet(str, NET_MAX_ADDRESS, set);
 210 }
 211 inline char* net_FindCharNotInSet(const char* str, const char* set) {
 212   return net_FindCharNotInSet(str, NET_MAX_ADDRESS, set);
 213 }
 214 inline char* net_RFindCharNotInSet(const char* str, const char* set) {
 215   return net_RFindCharNotInSet(str, str + strlen(str), set);
 216 }
 217
 218 /**
 219  * This function returns true if the given hostname does not include any
 220  * restricted characters.  Otherwise, false is returned.
 221  */
 222 bool net_IsValidHostName(const nsACString& host);
 223
 224 /**
 225  * Checks whether the IPv4 address is valid according to RFC 3986 section 3.2.2.
 226  */
 227 bool net_IsValidIPv4Addr(const nsACString& aAddr);
 228
 229 /**
 230  * Checks whether the IPv6 address is valid according to RFC 3986 section 3.2.2.
 231  */
 232 bool net_IsValidIPv6Addr(const nsACString& aAddr);
 233
 234 /**
 235  * Returns the default status text for a given HTTP status code (useful if HTTP2
 236  * does not provide one, for instance).
 237  */
 238 bool net_GetDefaultStatusTextForCode(uint16_t aCode, nsACString& aOutText);
 239
 240 namespace mozilla {
 241 /**
 242  * A class for handling form-urlencoded query strings.
 243  *
 244  * Manages an ordered list of name-value pairs, and allows conversion from and
 245  * to the string representation.
 246  *
 247  * In addition, there are static functions for handling one-shot use cases.
 248  */
 249 class URLParams final {
 250  public:
 251   /**
 252    * \brief Parses a query string and calls a parameter handler for each
 253    * name/value pair. The parameter handler can stop processing early by
 254    * returning false.
 255    *
 256    * \param aInput the query string to parse
 257    * \param aParamHandler the parameter handler as desribed above
 258    * \tparam ParamHandler a function type compatible with signature
 259    * bool(nsCString, nsCString)
 260    *
 261    * \return false if the parameter handler returned false for any parameter,
 262    * true otherwise
 263    */
 264   template <typename ParamHandler>
 265   static bool Parse(const nsACString& aInput, bool aShouldDecode,
 266                     ParamHandler aParamHandler) {
 267     const char* start = aInput.BeginReading();
 268     const char* const end = aInput.EndReading();
 269
 270     while (start != end) {
 271       nsAutoCString name;
 272       nsAutoCString value;
 273
 274       if (!ParseNextInternal(start, end, aShouldDecode, &name, &value)) {
 275         continue;
 276       }
 277
 278       if (!aParamHandler(std::move(name), std::move(value))) {
 279         return false;
 280       }
 281     }
 282     return true;
 283   }
 284
 285   /**
 286    * \brief Parses a query string and returns the value of a single parameter
 287    * specified by name.
 288    *
 289    * If there are multiple parameters with the same name, the value of the first
 290    * is returned.
 291    *
 292    * \param aInput the query string to parse
 293    * \param aName the name of the parameter to extract
 294    * \param[out] aValue will be assigned the parameter value, set to void if
 295    * there is no match \return true iff there was a parameter with with name
 296    * \paramref aName
 297    */
 298   static bool Extract(const nsACString& aInput, const nsACString& aName,
 299                       nsACString& aValue);
 300
 301   /**
 302    * \brief Resets the state of this instance and parses a new query string.
 303    *
 304    * \param aInput the query string to parse
 305    */
 306   void ParseInput(const nsACString& aInput);
 307
 308   /**
 309    * Serializes the current state to a query string.
 310    *
 311    * \param[out] aValue will be assigned the result of the serialization
 312    * \param aEncode If this is true, the serialization will encode the string.
 313    */
 314   void Serialize(nsACString& aValue, bool aEncode) const;
 315
 316   static void SerializeString(const nsACString& aInput, nsACString& aValue);
 317   void Get(const nsACString& aName, nsACString& aRetval);
 318
 319   void GetAll(const nsACString& aName, nsTArray<nsCString>& aRetval);
 320
 321   /**
 322    * \brief Sets the value of a given parameter.
 323    *
 324    * If one or more parameters of the name exist, the value of the first is
 325    * replaced, and all further parameters of the name are deleted. Otherwise,
 326    * the behaviour is the same as \ref Append.
 327    */
 328   void Set(const nsACString& aName, const nsACString& aValue);
 329
 330   void Append(const nsACString& aName, const nsACString& aValue);
 331
 332   bool Has(const nsACString& aName);
 333
 334   bool Has(const nsACString& aName, const nsACString& aValue);
 335
 336   /**
 337    * \brief Deletes all parameters with the given name.
 338    */
 339   void Delete(const nsACString& aName);
 340
 341   void Delete(const nsACString& aName, const nsACString& aValue);
 342
 343   void DeleteAll() { mParams.Clear(); }
 344
 345   uint32_t Length() const { return mParams.Length(); }
 346
 347   static void DecodeString(const nsACString& aInput, nsACString& aOutput);
 348   const nsACString& GetKeyAtIndex(uint32_t aIndex) const {
 349     MOZ_ASSERT(aIndex < mParams.Length());
 350     return mParams[aIndex].mKey;
 351   }
 352
 353   const nsACString& GetValueAtIndex(uint32_t aIndex) const {
 354     MOZ_ASSERT(aIndex < mParams.Length());
 355     return mParams[aIndex].mValue;
 356   }
 357
 358   /**
 359    * \brief Performs a stable sort of the parameters, maintaining the order of
 360    * multiple parameters with the same name.
 361    */
 362   void Sort();
 363
 364  private:
 365   static bool ParseNextInternal(const char*& aStart, const char* aEnd,
 366                                 bool aShouldDecode, nsACString* aOutputName,
 367                                 nsACString* aOutputValue);
 368
 369   struct Param {
 370     nsCString mKey;
 371     nsCString mValue;
 372   };
 373
 374   nsTArray<Param> mParams;
 375 };
 376 }  // namespace mozilla
 377
 378 #endif  // !nsURLHelper_h__