netwerk/base/src/nsURLHelper.h

   1 /* -*- Mode: C++; tab-width: 4; 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  * Andreas Otte.
  19  * Portions created by the Initial Developer are Copyright (C) 2000
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #ifndef nsURLHelper_h__
  39 #define nsURLHelper_h__
  40
  41 #include "nsString.h"
  42
  43 class nsIFile;
  44 class nsIURLParser;
  45
  46 enum netCoalesceFlags
  47 {
  48   NET_COALESCE_NORMAL = 0,
  49
  50   /**
  51    * retains /../ that reach above dir root (useful for FTP
  52    * servers in which the root of the FTP URL is not necessarily
  53    * the root of the FTP filesystem).
  54    */
  55   NET_COALESCE_ALLOW_RELATIVE_ROOT = 1<<0,
  56
  57   /**
  58    * recognizes /%2F and // as markers for the root directory
  59    * and handles them properly.
  60    */
  61   NET_COALESCE_DOUBLE_SLASH_IS_ROOT = 1<<1
  62 };
  63
  64 //----------------------------------------------------------------------------
  65 // This module contains some private helper functions related to URL parsing.
  66 //----------------------------------------------------------------------------
  67
  68 /* shutdown frees URL parser */
  69 NS_HIDDEN_(void) net_ShutdownURLHelper();
  70 #ifdef XP_MACOSX
  71 NS_HIDDEN_(void) net_ShutdownURLHelperOSX();
  72 #endif
  73
  74 /* access URL parsers */
  75 NS_HIDDEN_(nsIURLParser *) net_GetAuthURLParser();
  76 NS_HIDDEN_(nsIURLParser *) net_GetNoAuthURLParser();
  77 NS_HIDDEN_(nsIURLParser *) net_GetStdURLParser();
  78
  79 /* convert between nsIFile and file:// URL spec */
  80 NS_HIDDEN_(nsresult) net_GetURLSpecFromFile(nsIFile *, nsACString &);
  81 NS_HIDDEN_(nsresult) net_GetFileFromURLSpec(const nsACString &, nsIFile **);
  82
  83 /* extract file path components from file:// URL */
  84 NS_HIDDEN_(nsresult) net_ParseFileURL(const nsACString &inURL,
  85                                       nsACString &outDirectory,
  86                                       nsACString &outFileBaseName,
  87                                       nsACString &outFileExtension);
  88
  89 /* handle .. in dirs while resolving URLs (path is UTF-8) */
  90 NS_HIDDEN_(void) net_CoalesceDirs(netCoalesceFlags flags, char* path);
  91
  92 /**
  93  * Resolves a relative path string containing "." and ".."
  94  * with respect to a base path (assumed to already be resolved).
  95  * For example, resolving "../../foo/./bar/../baz.html" w.r.t.
  96  * "/a/b/c/d/e/" yields "/a/b/c/foo/baz.html". Attempting to
  97  * ascend above the base results in the NS_ERROR_MALFORMED_URI
  98  * exception. If basePath is null, it treats it as "/".
  99  *
 100  * @param relativePath  a relative URI
 101  * @param basePath      a base URI
 102  *
 103  * @return a new string, representing canonical uri
 104  */
 105 NS_HIDDEN_(nsresult) net_ResolveRelativePath(const nsACString &relativePath,
 106                                              const nsACString &basePath,
 107                                              nsACString &result);
 108
 109 /**
 110  * Extract URI-Scheme if possible
 111  *
 112  * @param inURI     URI spec
 113  * @param startPos  start of scheme (may be null)
 114  * @param endPos    end of scheme; index of colon (may be null)
 115  * @param scheme    scheme copied to this buffer on return (may be null)
 116  */
 117 NS_HIDDEN_(nsresult) net_ExtractURLScheme(const nsACString &inURI,
 118                                           PRUint32 *startPos,
 119                                           PRUint32 *endPos,
 120                                           nsACString *scheme = nsnull);
 121
 122 /* check that the given scheme conforms to RFC 2396 */
 123 NS_HIDDEN_(PRBool) net_IsValidScheme(const char *scheme, PRUint32 schemeLen);
 124
 125 inline PRBool net_IsValidScheme(const nsAFlatCString &scheme)
 126 {
 127     return net_IsValidScheme(scheme.get(), scheme.Length());
 128 }
 129
 130 /**
 131  * Filter out whitespace from a URI string.  The input is the |str|
 132  * pointer. |result| is written to if and only if there is whitespace that has
 133  * to be filtered out.  The return value is true if and only if |result| is
 134  * written to.
 135  *
 136  * This function strips out all whitespace at the beginning and end of the URL
 137  * and strips out \r, \n, \t from the middle of the URL.  This makes it safe to
 138  * call on things like javascript: urls or data: urls, where we may in fact run
 139  * into whitespace that is not properly encoded.
 140  *
 141  * @param str the pointer to the string to filter.  Must be non-null.
 142  * @param result the out param to write to if filtering happens
 143  * @return whether result was written to
 144  */
 145 NS_HIDDEN_(PRBool) net_FilterURIString(const char *str, nsACString& result);
 146
 147 #if defined(XP_WIN) || defined(XP_OS2)
 148 /**
 149  * On Win32 and OS/2 system's a back-slash in a file:// URL is equivalent to a
 150  * forward-slash.  This function maps any back-slashes to forward-slashes.
 151  *
 152  * @param aURL
 153  *        The URL string to normalize (UTF-8 encoded).  This can be a
 154  *        relative URL segment.
 155  * @param aResultBuf
 156  *        The resulting string is appended to this string.  If the input URL
 157  *        is already normalized, then aResultBuf is unchanged.
 158  *
 159  * @returns false if aURL is already normalized.  Otherwise, returns true.
 160  */
 161 NS_HIDDEN_(PRBool) net_NormalizeFileURL(const nsACString &aURL,
 162                                         nsCString &aResultBuf);
 163 #endif
 164
 165 /*****************************************************************************
 166  * generic string routines follow (XXX move to someplace more generic).
 167  */
 168
 169 /* convert to lower case */
 170 NS_HIDDEN_(void) net_ToLowerCase(char* str, PRUint32 length);
 171 NS_HIDDEN_(void) net_ToLowerCase(char* str);
 172
 173 /**
 174  * returns pointer to first character of |str| in the given set.  if not found,
 175  * then |end| is returned.  stops prematurely if a null byte is encountered,
 176  * and returns the address of the null byte.
 177  */
 178 NS_HIDDEN_(char *) net_FindCharInSet(const char *str, const char *end, const char *set);
 179
 180 /**
 181  * returns pointer to first character of |str| NOT in the given set.  if all
 182  * characters are in the given set, then |end| is returned.  if '\0' is not
 183  * included in |set|, then stops prematurely if a null byte is encountered,
 184  * and returns the address of the null byte.
 185  */
 186 NS_HIDDEN_(char *) net_FindCharNotInSet(const char *str, const char *end, const char *set);
 187
 188 /**
 189  * returns pointer to last character of |str| NOT in the given set.  if all
 190  * characters are in the given set, then |str - 1| is returned.
 191  */
 192 NS_HIDDEN_(char *) net_RFindCharNotInSet(const char *str, const char *end, const char *set);
 193
 194 /**
 195  * Parses a content-type header and returns the content type and
 196  * charset (if any).  aCharset is not modified if no charset is
 197  * specified in anywhere in aHeaderStr.  In that case (no charset
 198  * specified), aHadCharset is set to false.  Otherwise, it's set to
 199  * true.  Note that aContentCharset can be empty even if aHadCharset
 200  * is true.
 201  */
 202 NS_HIDDEN_(void) net_ParseContentType(const nsACString &aHeaderStr,
 203                                       nsACString       &aContentType,
 204                                       nsACString       &aContentCharset,
 205                                       PRBool*          aHadCharset);
 206 /**
 207  * As above, but also returns the start and end indexes for the charset
 208  * parameter in aHeaderStr.  These are indices for the entire parameter, NOT
 209  * just the value.  If there is "effectively" no charset parameter (e.g. if an
 210  * earlier type with one is overridden by a later type without one),
 211  * *aHadCharset will be true but *aCharsetStart will be set to -1.  Note that
 212  * it's possible to have aContentCharset empty and *aHadCharset true when
 213  * *aCharsetStart is nonnegative; this corresponds to charset="".
 214  */
 215 NS_HIDDEN_(void) net_ParseContentType(const nsACString &aHeaderStr,
 216                                       nsACString       &aContentType,
 217                                       nsACString       &aContentCharset,
 218                                       PRBool           *aHadCharset,
 219                                       PRInt32          *aCharsetStart,
 220                                       PRInt32          *aCharsetEnd);
 221
 222 /* inline versions */
 223
 224 /* remember the 64-bit platforms ;-) */
 225 #define NET_MAX_ADDRESS (((char*)0)-1)
 226
 227 inline char *net_FindCharInSet(const char *str, const char *set)
 228 {
 229     return net_FindCharInSet(str, NET_MAX_ADDRESS, set);
 230 }
 231 inline char *net_FindCharNotInSet(const char *str, const char *set)
 232 {
 233     return net_FindCharNotInSet(str, NET_MAX_ADDRESS, set);
 234 }
 235 inline char *net_RFindCharNotInSet(const char *str, const char *set)
 236 {
 237     return net_RFindCharNotInSet(str, str + strlen(str), set);
 238 }
 239
 240 /**
 241  * This function returns true if the given hostname does not include any
 242  * restricted characters.  Otherwise, false is returned.
 243  */
 244 NS_HIDDEN_(PRBool) net_IsValidHostName(const nsCSubstring &host);
 245
 246 #endif // !nsURLHelper_h__