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