Source/WebCore/platform/URL.h

   1 /*
   2  * Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2011, 2012, 2013 Apple Inc. All rights reserved.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions
   6  * are met:
   7  * 1. Redistributions of source code must retain the above copyright
   8  *    notice, this list of conditions and the following disclaimer.
   9  * 2. Redistributions in binary form must reproduce the above copyright
  10  *    notice, this list of conditions and the following disclaimer in the
  11  *    documentation and/or other materials provided with the distribution.
  12  *
  13  * THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
  14  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  16  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE INC. OR
  17  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  18  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  19  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  20  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
  21  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  22  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  23  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24  */
  25
  26 #ifndef URL_h
  27 #define URL_h
  28
  29 #include <wtf/Forward.h>
  30 #include <wtf/HashMap.h>
  31 #include <wtf/RetainPtr.h>
  32 #include <wtf/text/WTFString.h>
  33
  34 #if USE(CF)
  35 typedef const struct __CFURL* CFURLRef;
  36 #endif
  37
  38 #if USE(SOUP)
  39 #include "GUniquePtrSoup.h"
  40 #endif
  41
  42 #if USE(FOUNDATION)
  43 OBJC_CLASS NSURL;
  44 #endif
  45
  46 namespace WebCore {
  47
  48 class TextEncoding;
  49 struct URLHash;
  50
  51 enum ParsedURLStringTag { ParsedURLString };
  52
  53 class URL {
  54 public:
  55     // Generates a URL which contains a null string.
  56     URL() { invalidate(); }
  57
  58     // The argument is an absolute URL string. The string is assumed to be output of URL::string() called on a valid
  59     // URL object, or indiscernible from such.
  60     // It is usually best to avoid repeatedly parsing a string, unless memory saving outweigh the possible slow-downs.
  61     WEBCORE_EXPORT URL(ParsedURLStringTag, const String&);
  62     explicit URL(WTF::HashTableDeletedValueType) : m_string(WTF::HashTableDeletedValue) { }
  63     bool isHashTableDeletedValue() const { return string().isHashTableDeletedValue(); }
  64
  65     // Resolves the relative URL with the given base URL. If provided, the
  66     // TextEncoding is used to encode non-ASCII characers. The base URL can be
  67     // null or empty, in which case the relative URL will be interpreted as
  68     // absolute.
  69     // FIXME: If the base URL is invalid, this always creates an invalid
  70     // URL. Instead I think it would be better to treat all invalid base URLs
  71     // the same way we treate null and empty base URLs.
  72     WEBCORE_EXPORT URL(const URL& base, const String& relative);
  73     URL(const URL& base, const String& relative, const TextEncoding&);
  74
  75     static URL fakeURLWithRelativePart(const String&);
  76     static URL fileURLWithFileSystemPath(const String&);
  77
  78     String strippedForUseAsReferrer() const;
  79
  80     // FIXME: The above functions should be harmonized so that passing a
  81     // base of null or the empty string gives the same result as the
  82     // standard String constructor.
  83
  84     // Makes a deep copy. Helpful only if you need to use a URL on another
  85     // thread. Since the underlying StringImpl objects are immutable, there's
  86     // no other reason to ever prefer copy() over plain old assignment.
  87     // FIXME: Rename to isolatedCopy to match String.
  88     URL copy() const;
  89
  90     bool isNull() const;
  91     bool isEmpty() const;
  92     bool isValid() const;
  93
  94     // Returns true if you can set the host and port for the URL.
  95     // Non-hierarchical URLs don't have a host and port.
  96     bool canSetHostOrPort() const { return isHierarchical(); }
  97
  98     bool canSetPathname() const { return isHierarchical(); }
  99     bool isHierarchical() const;
 100
 101     const String& string() const { return m_string; }
 102
 103     String stringCenterEllipsizedToLength(unsigned length = 1024) const;
 104
 105     WEBCORE_EXPORT String protocol() const;
 106     WEBCORE_EXPORT String host() const;
 107     WEBCORE_EXPORT unsigned short port() const;
 108     bool hasPort() const;
 109     WEBCORE_EXPORT String user() const;
 110     WEBCORE_EXPORT String pass() const;
 111     WEBCORE_EXPORT String path() const;
 112     WEBCORE_EXPORT String lastPathComponent() const;
 113     WEBCORE_EXPORT String query() const;
 114     WEBCORE_EXPORT String fragmentIdentifier() const;
 115     WEBCORE_EXPORT bool hasFragmentIdentifier() const;
 116
 117     // Unlike user() and pass(), these functions don't decode escape sequences.
 118     // This is necessary for accurate round-tripping, because encoding doesn't encode '%' characters.
 119     String encodedUser() const;
 120     String encodedPass() const;
 121
 122     WEBCORE_EXPORT String baseAsString() const;
 123
 124     WEBCORE_EXPORT String fileSystemPath() const;
 125
 126     // Returns true if the current URL's protocol is the same as the null-
 127     // terminated ASCII argument. The argument must be lower-case.
 128     WEBCORE_EXPORT bool protocolIs(const char*) const;
 129     bool protocolIsData() const { return protocolIs("data"); }
 130     bool protocolIsInHTTPFamily() const;
 131     WEBCORE_EXPORT bool isLocalFile() const;
 132     bool isBlankURL() const;
 133
 134     WEBCORE_EXPORT bool setProtocol(const String&);
 135     void setHost(const String&);
 136
 137     void removePort();
 138     void setPort(unsigned short);
 139
 140     // Input is like "foo.com" or "foo.com:8000".
 141     void setHostAndPort(const String&);
 142
 143     void setUser(const String&);
 144     void setPass(const String&);
 145
 146     // If you pass an empty path for HTTP or HTTPS URLs, the resulting path
 147     // will be "/".
 148     WEBCORE_EXPORT void setPath(const String&);
 149
 150     // The query may begin with a question mark, or, if not, one will be added
 151     // for you. Setting the query to the empty string will leave a "?" in the
 152     // URL (with nothing after it). To clear the query, pass a null string.
 153     void setQuery(const String&);
 154
 155     void setFragmentIdentifier(const String&);
 156     void removeFragmentIdentifier();
 157
 158     WEBCORE_EXPORT friend bool equalIgnoringFragmentIdentifier(const URL&, const URL&);
 159
 160     WEBCORE_EXPORT friend bool protocolHostAndPortAreEqual(const URL&, const URL&);
 161
 162     unsigned hostStart() const;
 163     unsigned hostEnd() const;
 164
 165     unsigned pathStart() const;
 166     unsigned pathEnd() const;
 167     unsigned pathAfterLastSlash() const;
 168
 169     operator const String&() const { return string(); }
 170
 171 #if USE(CF)
 172     WEBCORE_EXPORT URL(CFURLRef);
 173     WEBCORE_EXPORT RetainPtr<CFURLRef> createCFURL() const;
 174 #endif
 175
 176 #if USE(SOUP)
 177     URL(SoupURI*);
 178     GUniquePtr<SoupURI> createSoupURI() const;
 179 #endif
 180
 181 #if USE(FOUNDATION)
 182     WEBCORE_EXPORT URL(NSURL*);
 183     WEBCORE_EXPORT operator NSURL*() const;
 184 #endif
 185 #ifdef __OBJC__
 186     operator NSString*() const { return string(); }
 187 #endif
 188
 189     const URL* innerURL() const { return 0; }
 190
 191 #ifndef NDEBUG
 192     void print() const;
 193 #endif
 194
 195     bool isSafeToSendToAnotherThread() const;
 196
 197 private:
 198     WEBCORE_EXPORT void invalidate();
 199     static bool protocolIs(const String&, const char*);
 200     void init(const URL&, const String&, const TextEncoding&);
 201     void copyToBuffer(Vector<char, 512>& buffer) const;
 202
 203     // Parses the given URL. The originalString parameter allows for an
 204     // optimization: When the source is the same as the fixed-up string,
 205     // it will use the passed-in string instead of allocating a new one.
 206     void parse(const String&);
 207     void parse(const char* url, const String* originalString = 0);
 208
 209     bool hasPath() const;
 210
 211     String m_string;
 212     bool m_isValid : 1;
 213     bool m_protocolIsInHTTPFamily : 1;
 214
 215     int m_schemeEnd;
 216     int m_userStart;
 217     int m_userEnd;
 218     int m_passwordEnd;
 219     int m_hostEnd;
 220     int m_portEnd;
 221     int m_pathAfterLastSlash;
 222     int m_pathEnd;
 223     int m_queryEnd;
 224     int m_fragmentEnd;
 225 };
 226
 227 bool operator==(const URL&, const URL&);
 228 bool operator==(const URL&, const String&);
 229 bool operator==(const String&, const URL&);
 230 bool operator!=(const URL&, const URL&);
 231 bool operator!=(const URL&, const String&);
 232 bool operator!=(const String&, const URL&);
 233
 234 WEBCORE_EXPORT bool equalIgnoringFragmentIdentifier(const URL&, const URL&);
 235 WEBCORE_EXPORT bool protocolHostAndPortAreEqual(const URL&, const URL&);
 236
 237 WEBCORE_EXPORT const URL& blankURL();
 238
 239 // Functions to do URL operations on strings.
 240 // These are operations that aren't faster on a parsed URL.
 241 // These are also different from the URL functions in that they don't require the string to be a valid and parsable URL.
 242 // This is especially important because valid javascript URLs are not necessarily considered valid by URL.
 243
 244 WEBCORE_EXPORT bool protocolIs(const String& url, const char* protocol);
 245 WEBCORE_EXPORT bool protocolIsJavaScript(const String& url);
 246 WEBCORE_EXPORT bool protocolIsInHTTPFamily(const String& url);
 247
 248 bool isDefaultPortForProtocol(unsigned short port, const String& protocol);
 249 bool portAllowed(const URL&); // Blacklist ports that should never be used for Web resources.
 250
 251 bool isValidProtocol(const String&);
 252
 253 String mimeTypeFromDataURL(const String& url);
 254 WEBCORE_EXPORT String mimeTypeFromURL(const URL&);
 255
 256 // Unescapes the given string using URL escaping rules, given an optional
 257 // encoding (defaulting to UTF-8 otherwise). DANGER: If the URL has "%00"
 258 // in it, the resulting string will have embedded null characters!
 259 WEBCORE_EXPORT String decodeURLEscapeSequences(const String&);
 260 String decodeURLEscapeSequences(const String&, const TextEncoding&);
 261
 262 // FIXME: This is a wrong concept to expose, different parts of a URL need different escaping per the URL Standard.
 263 WEBCORE_EXPORT String encodeWithURLEscapeSequences(const String&);
 264
 265 #if PLATFORM(IOS)
 266 WEBCORE_EXPORT void enableURLSchemeCanonicalization(bool);
 267 #endif
 268
 269 // Like StringCapture, but for URLs.
 270 class URLCapture {
 271 public:
 272     explicit URLCapture(const URL&);
 273     explicit URLCapture(URL&&);
 274     URLCapture(const URLCapture&);
 275     const URL& url() const;
 276     URL releaseURL();
 277
 278 private:
 279     void operator=(const URLCapture&) = delete;
 280     URL m_URL;
 281 };
 282
 283 // Inlines.
 284
 285 inline bool operator==(const URL& a, const URL& b)
 286 {
 287     return a.string() == b.string();
 288 }
 289
 290 inline bool operator==(const URL& a, const String& b)
 291 {
 292     return a.string() == b;
 293 }
 294
 295 inline bool operator==(const String& a, const URL& b)
 296 {
 297     return a == b.string();
 298 }
 299
 300 inline bool operator!=(const URL& a, const URL& b)
 301 {
 302     return a.string() != b.string();
 303 }
 304
 305 inline bool operator!=(const URL& a, const String& b)
 306 {
 307     return a.string() != b;
 308 }
 309
 310 inline bool operator!=(const String& a, const URL& b)
 311 {
 312     return a != b.string();
 313 }
 314
 315 // Inline versions of some non-GoogleURL functions so we can get inlining
 316 // without having to have a lot of ugly ifdefs in the class definition.
 317
 318 inline bool URL::isNull() const
 319 {
 320     return m_string.isNull();
 321 }
 322
 323 inline bool URL::isEmpty() const
 324 {
 325     return m_string.isEmpty();
 326 }
 327
 328 inline bool URL::isValid() const
 329 {
 330     return m_isValid;
 331 }
 332
 333 inline bool URL::hasPath() const
 334 {
 335     return m_pathEnd != m_portEnd;
 336 }
 337
 338 inline bool URL::hasPort() const
 339 {
 340     return m_hostEnd < m_portEnd;
 341 }
 342
 343 inline bool URL::protocolIsInHTTPFamily() const
 344 {
 345     return m_protocolIsInHTTPFamily;
 346 }
 347
 348 inline unsigned URL::hostStart() const
 349 {
 350     return (m_passwordEnd == m_userStart) ? m_passwordEnd : m_passwordEnd + 1;
 351 }
 352
 353 inline unsigned URL::hostEnd() const
 354 {
 355     return m_hostEnd;
 356 }
 357
 358 inline unsigned URL::pathStart() const
 359 {
 360     return m_portEnd;
 361 }
 362
 363 inline unsigned URL::pathEnd() const
 364 {
 365     return m_pathEnd;
 366 }
 367
 368 inline unsigned URL::pathAfterLastSlash() const
 369 {
 370     return m_pathAfterLastSlash;
 371 }
 372
 373 inline URLCapture::URLCapture(const URL& url)
 374     : m_URL(url)
 375 {
 376 }
 377
 378 inline URLCapture::URLCapture(URL&& url)
 379     : m_URL(url)
 380 {
 381 }
 382
 383 inline URLCapture::URLCapture(const URLCapture& other)
 384     : m_URL(other.m_URL.copy())
 385 {
 386 }
 387
 388 inline const URL& URLCapture::url() const
 389 {
 390     return m_URL;
 391 }
 392
 393 inline URL URLCapture::releaseURL()
 394 {
 395     return WTF::move(m_URL);
 396 }
 397
 398 } // namespace WebCore
 399
 400 namespace WTF {
 401
 402     // URLHash is the default hash for String
 403     template<typename T> struct DefaultHash;
 404     template<> struct DefaultHash<WebCore::URL> {
 405         typedef WebCore::URLHash Hash;
 406     };
 407
 408 } // namespace WTF
 409
 410 #endif // URL_h