gurl.h revision 868fa2fe829687343ffae624259930155e16dbd8
1c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// Copyright 2013 The Chromium Authors. All rights reserved. 2c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// Use of this source code is governed by a BSD-style license that can be 3c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// found in the LICENSE file. 4c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 5c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#ifndef URL_GURL_H_ 6c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#define URL_GURL_H_ 7c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 8c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#include <iosfwd> 9c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#include <string> 10c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 11c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#include "base/string16.h" 12c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#include "url/url_canon.h" 13c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#include "url/url_canon_stdstring.h" 14868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles)#include "url/url_export.h" 15c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#include "url/url_parse.h" 16c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 17868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles)class URL_EXPORT GURL { 18c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) public: 19c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) typedef url_canon::StdStringReplacements<std::string> Replacements; 20c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) typedef url_canon::StdStringReplacements<string16> ReplacementsW; 21c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 22c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Creates an empty, invalid URL. 23c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) GURL(); 24c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 25c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Copy construction is relatively inexpensive, with most of the time going 26c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // to reallocating the string. It does not re-parse. 27c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) GURL(const GURL& other); 28c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 29c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // The narrow version requires the input be UTF-8. Invalid UTF-8 input will 30c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // result in an invalid URL. 31c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // 32c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // The wide version should also take an encoding parameter so we know how to 33c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // encode the query parameters. It is probably sufficient for the narrow 34c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // version to assume the query parameter encoding should be the same as the 35c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // input encoding. 36868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) explicit GURL(const std::string& url_string /*, output_param_encoding*/); 37868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) explicit GURL(const string16& url_string /*, output_param_encoding*/); 38c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 39c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Constructor for URLs that have already been parsed and canonicalized. This 40c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // is used for conversions from KURL, for example. The caller must supply all 41c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // information associated with the URL, which must be correct and consistent. 42c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) GURL(const char* canonical_spec, size_t canonical_spec_len, 43c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) const url_parse::Parsed& parsed, bool is_valid); 44c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 45c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) ~GURL(); 46c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 47c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) GURL& operator=(const GURL& other); 48c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 49c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Returns true when this object represents a valid parsed URL. When not 50c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // valid, other functions will still succeed, but you will not get canonical 51c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // data out in the format you may be expecting. Instead, we keep something 52c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // "reasonable looking" so that the user can see how it's busted if 53c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // displayed to them. 54c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool is_valid() const { 55c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return is_valid_; 56c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 57c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 58c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Returns true if the URL is zero-length. Note that empty URLs are also 59c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // invalid, and is_valid() will return false for them. This is provided 60c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // because some users may want to treat the empty case differently. 61c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool is_empty() const { 62c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return spec_.empty(); 63c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 64c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 65c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Returns the raw spec, i.e., the full text of the URL, in canonical UTF-8, 66c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // if the URL is valid. If the URL is not valid, this will assert and return 67c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // the empty string (for safety in release builds, to keep them from being 68c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // misused which might be a security problem). 69c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // 70c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // The URL will be ASCII except the reference fragment, which may be UTF-8. 71c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // It is guaranteed to be valid UTF-8. 72c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // 73c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // The exception is for empty() URLs (which are !is_valid()) but this will 74c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // return the empty string without asserting. 75c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // 76c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Used invalid_spec() below to get the unusable spec of an invalid URL. This 77c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // separation is designed to prevent errors that may cause security problems 78c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // that could result from the mistaken use of an invalid URL. 79c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) const std::string& spec() const; 80c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 81c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Returns the potentially invalid spec for a the URL. This spec MUST NOT be 82c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // modified or sent over the network. It is designed to be displayed in error 83c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // messages to the user, as the apperance of the spec may explain the error. 84c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // If the spec is valid, the valid spec will be returned. 85c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // 86c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // The returned string is guaranteed to be valid UTF-8. 87c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) const std::string& possibly_invalid_spec() const { 88c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return spec_; 89c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 90c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 91c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Getter for the raw parsed structure. This allows callers to locate parts 92c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // of the URL within the spec themselves. Most callers should consider using 93c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // the individual component getters below. 94c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // 95c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // The returned parsed structure will reference into the raw spec, which may 96c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // or may not be valid. If you are using this to index into the spec, BE 97c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // SURE YOU ARE USING possibly_invalid_spec() to get the spec, and that you 98c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // don't do anything "important" with invalid specs. 99c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) const url_parse::Parsed& parsed_for_possibly_invalid_spec() const { 100c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return parsed_; 101c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 102c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 103c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Defiant equality operator! 104c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool operator==(const GURL& other) const { 105c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return spec_ == other.spec_; 106c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 107c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool operator!=(const GURL& other) const { 108c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return spec_ != other.spec_; 109c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 110c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 111c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Allows GURL to used as a key in STL (for example, a std::set or std::map). 112c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool operator<(const GURL& other) const { 113c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return spec_ < other.spec_; 114c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 115c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 116c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Resolves a URL that's possibly relative to this object's URL, and returns 117c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // it. Absolute URLs are also handled according to the rules of URLs on web 118c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // pages. 119c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // 120c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // It may be impossible to resolve the URLs properly. If the input is not 121c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // "standard" (SchemeIsStandard() == false) and the input looks relative, we 122c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // can't resolve it. In these cases, the result will be an empty, invalid 123c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // GURL. 124c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // 125c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // The result may also be a nonempty, invalid URL if the input has some kind 126c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // of encoding error. In these cases, we will try to construct a "good" URL 127c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // that may have meaning to the user, but it will be marked invalid. 128c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // 129c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // It is an error to resolve a URL relative to an invalid URL. The result 130c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // will be the empty URL. 131c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) GURL Resolve(const std::string& relative) const; 132c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) GURL Resolve(const string16& relative) const; 133c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 134c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Like Resolve() above but takes a character set encoder which will be used 135c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // for any query text specified in the input. The charset converter parameter 136c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // may be NULL, in which case it will be treated as UTF-8. 137c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // 138c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // TODO(brettw): These should be replaced with versions that take something 139c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // more friendly than a raw CharsetConverter (maybe like an ICU character set 140c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // name). 141c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) GURL ResolveWithCharsetConverter( 142c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) const std::string& relative, 143c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) url_canon::CharsetConverter* charset_converter) const; 144c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) GURL ResolveWithCharsetConverter( 145c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) const string16& relative, 146c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) url_canon::CharsetConverter* charset_converter) const; 147c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 148c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Creates a new GURL by replacing the current URL's components with the 149c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // supplied versions. See the Replacements class in url_canon.h for more. 150c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // 151c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // These are not particularly quick, so avoid doing mutations when possible. 152c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Prefer the 8-bit version when possible. 153c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // 154c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // It is an error to replace components of an invalid URL. The result will 155c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // be the empty URL. 156c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // 157c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Note that we use the more general url_canon::Replacements type to give 158c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // callers extra flexibility rather than our override. 159c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) GURL ReplaceComponents( 160c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) const url_canon::Replacements<char>& replacements) const; 161c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) GURL ReplaceComponents( 162c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) const url_canon::Replacements<char16>& replacements) const; 163c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 164c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // A helper function that is equivalent to replacing the path with a slash 165c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // and clearing out everything after that. We sometimes need to know just the 166c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // scheme and the authority. If this URL is not a standard URL (it doesn't 167c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // have the regular authority and path sections), then the result will be 168c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // an empty, invalid GURL. Note that this *does* work for file: URLs, which 169c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // some callers may want to filter out before calling this. 170c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // 171c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // It is an error to get an empty path on an invalid URL. The result 172c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // will be the empty URL. 173c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) GURL GetWithEmptyPath() const; 174c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 175c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // A helper function to return a GURL containing just the scheme, host, 176c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // and port from a URL. Equivalent to clearing any username and password, 177c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // replacing the path with a slash, and clearing everything after that. If 178c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // this URL is not a standard URL, then the result will be an empty, 179c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // invalid GURL. If the URL has neither username nor password, this 180c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // degenerates to GetWithEmptyPath(). 181c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // 182c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // It is an error to get the origin of an invalid URL. The result 183c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // will be the empty URL. 184c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) GURL GetOrigin() const; 185c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 186c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Returns true if the scheme for the current URL is a known "standard" 187c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // scheme. Standard schemes have an authority and a path section. This 188c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // includes file: and filesystem:, which some callers may want to filter out 189c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // explicitly by calling SchemeIsFile[System]. 190c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool IsStandard() const; 191c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 192c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Returns true if the given parameter (should be lower-case ASCII to match 193c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // the canonicalized scheme) is the scheme for this URL. This call is more 194c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // efficient than getting the scheme and comparing it because no copies or 195c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // object constructions are done. 196c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool SchemeIs(const char* lower_ascii_scheme) const; 197c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 198c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // We often need to know if this is a file URL. File URLs are "standard", but 199c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // are often treated separately by some programs. 200c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool SchemeIsFile() const { 201c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return SchemeIs("file"); 202c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 203c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 204c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // FileSystem URLs need to be treated differently in some cases. 205c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool SchemeIsFileSystem() const { 206c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return SchemeIs("filesystem"); 207c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 208c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 209c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // If the scheme indicates a secure connection 210c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool SchemeIsSecure() const { 211c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return SchemeIs("https") || SchemeIs("wss") || 212c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) (SchemeIsFileSystem() && inner_url() && inner_url()->SchemeIsSecure()); 213c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 214c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 215c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Returns true if the hostname is an IP address. Note: this function isn't 216c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // as cheap as a simple getter because it re-parses the hostname to verify. 217c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // This currently identifies only IPv4 addresses (bug 822685). 218c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool HostIsIPAddress() const; 219c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 220c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Getters for various components of the URL. The returned string will be 221c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // empty if the component is empty or is not present. 222c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) std::string scheme() const { // Not including the colon. See also SchemeIs. 223c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return ComponentString(parsed_.scheme); 224c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 225c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) std::string username() const { 226c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return ComponentString(parsed_.username); 227c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 228c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) std::string password() const { 229c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return ComponentString(parsed_.password); 230c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 231c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Note that this may be a hostname, an IPv4 address, or an IPv6 literal 232c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // surrounded by square brackets, like "[2001:db8::1]". To exclude these 233c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // brackets, use HostNoBrackets() below. 234c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) std::string host() const { 235c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return ComponentString(parsed_.host); 236c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 237c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) std::string port() const { // Returns -1 if "default" 238c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return ComponentString(parsed_.port); 239c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 240c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) std::string path() const { // Including first slash following host 241c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return ComponentString(parsed_.path); 242c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 243c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) std::string query() const { // Stuff following '?' 244c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return ComponentString(parsed_.query); 245c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 246c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) std::string ref() const { // Stuff following '#' 247c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return ComponentString(parsed_.ref); 248c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 249c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 250c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Existance querying. These functions will return true if the corresponding 251c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // URL component exists in this URL. Note that existance is different than 252c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // being nonempty. http://www.google.com/? has a query that just happens to 253c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // be empty, and has_query() will return true. 254c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool has_scheme() const { 255c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return parsed_.scheme.len >= 0; 256c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 257c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool has_username() const { 258c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return parsed_.username.len >= 0; 259c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 260c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool has_password() const { 261c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return parsed_.password.len >= 0; 262c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 263c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool has_host() const { 264c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Note that hosts are special, absense of host means length 0. 265c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return parsed_.host.len > 0; 266c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 267c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool has_port() const { 268c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return parsed_.port.len >= 0; 269c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 270c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool has_path() const { 271c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Note that http://www.google.com/" has a path, the path is "/". This can 272c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // return false only for invalid or nonstandard URLs. 273c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return parsed_.path.len >= 0; 274c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 275c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool has_query() const { 276c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return parsed_.query.len >= 0; 277c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 278c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool has_ref() const { 279c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return parsed_.ref.len >= 0; 280c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 281c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 282c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Returns a parsed version of the port. Can also be any of the special 283c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // values defined in Parsed for ExtractPort. 284c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) int IntPort() const; 285c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 286c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Returns the port number of the url, or the default port number. 287c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // If the scheme has no concept of port (or unknown default) returns 288c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // PORT_UNSPECIFIED. 289c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) int EffectiveIntPort() const; 290c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 291c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Extracts the filename portion of the path and returns it. The filename 292c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // is everything after the last slash in the path. This may be empty. 293c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) std::string ExtractFileName() const; 294c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 295c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Returns the path that should be sent to the server. This is the path, 296c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // parameter, and query portions of the URL. It is guaranteed to be ASCII. 297c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) std::string PathForRequest() const; 298c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 299c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Returns the host, excluding the square brackets surrounding IPv6 address 300c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // literals. This can be useful for passing to getaddrinfo(). 301c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) std::string HostNoBrackets() const; 302c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 303c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Returns true if this URL's host matches or is in the same domain as 304c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // the given input string. For example if this URL was "www.google.com", 305c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // this would match "com", "google.com", and "www.google.com 306c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // (input domain should be lower-case ASCII to match the canonicalized 307c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // scheme). This call is more efficient than getting the host and check 308c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // whether host has the specific domain or not because no copies or 309c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // object constructions are done. 310c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // 311c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // If function DomainIs has parameter domain_len, which means the parameter 312c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // lower_ascii_domain does not gurantee to terminate with NULL character. 313c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool DomainIs(const char* lower_ascii_domain, int domain_len) const; 314c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 315c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // If function DomainIs only has parameter lower_ascii_domain, which means 316c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // domain string should be terminate with NULL character. 317c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool DomainIs(const char* lower_ascii_domain) const { 318c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return DomainIs(lower_ascii_domain, 319c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) static_cast<int>(strlen(lower_ascii_domain))); 320c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 321c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 322c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Swaps the contents of this GURL object with the argument without doing 323c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // any memory allocations. 324c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) void Swap(GURL* other); 325c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 326c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Returns a reference to a singleton empty GURL. This object is for callers 327c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // who return references but don't have anything to return in some cases. 328c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // This function may be called from any thread. 329c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) static const GURL& EmptyGURL(); 330c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 331c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Returns the inner URL of a nested URL [currently only non-null for 332c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // filesystem: URLs]. 333c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) const GURL* inner_url() const { 334c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return inner_url_; 335c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 336c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 337c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) private: 338c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Returns the substring of the input identified by the given component. 339c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) std::string ComponentString(const url_parse::Component& comp) const { 340c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) if (comp.len <= 0) 341c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return std::string(); 342c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) return std::string(spec_, comp.begin, comp.len); 343c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) } 344c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 345c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // The actual text of the URL, in canonical ASCII form. 346c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) std::string spec_; 347c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 348c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Set when the given URL is valid. Otherwise, we may still have a spec and 349c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // components, but they may not identify valid resources (for example, an 350c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // invalid port number, invalid characters in the scheme, etc.). 351c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) bool is_valid_; 352c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 353c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Identified components of the canonical spec. 354c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) url_parse::Parsed parsed_; 355c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 356c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // Used for nested schemes [currently only filesystem:]. 357c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) GURL* inner_url_; 358c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 359c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) // TODO bug 684583: Add encoding for query params. 360c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)}; 361c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 362c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)// Stream operator so GURL can be used in assertion statements. 363868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles)URL_EXPORT std::ostream& operator<<(std::ostream& out, const GURL& url); 364c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 365c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#endif // URL_GURL_H_ 366