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.
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"
17 class URL_EXPORT GURL
{
19 typedef url_canon::StdStringReplacements
<std::string
> Replacements
;
20 typedef url_canon::StdStringReplacements
<base::string16
> ReplacementsW
;
22 // Creates an empty, invalid URL.
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
);
29 // The narrow version requires the input be UTF-8. Invalid UTF-8 input will
30 // result in an invalid URL.
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
36 explicit GURL(const std::string
& url_string
/*, output_param_encoding*/);
37 explicit GURL(const base::string16
& url_string
/*, output_param_encoding*/);
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
);
55 GURL
& operator=(const GURL
& other
);
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
62 bool is_valid() const {
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 {
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).
78 // The URL will be ASCII except the reference fragment, which may be UTF-8.
79 // It is guaranteed to be valid UTF-8.
81 // The exception is for empty() URLs (which are !is_valid()) but this will
82 // return the empty string without asserting.
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;
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.
94 // The returned string is guaranteed to be valid UTF-8.
95 const std::string
& possibly_invalid_spec() const {
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.
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 {
111 // Defiant equality operator!
112 bool operator==(const GURL
& other
) const {
113 return spec_
== other
.spec_
;
115 bool operator!=(const GURL
& other
) const {
116 return spec_
!= other
.spec_
;
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_
;
124 // Resolves a URL that's possibly relative to this object's URL, and returns
125 // it. Absolute URLs are also handled according to the rules of URLs on web
128 // It may be impossible to resolve the URLs properly. If the input is not
129 // "standard" (SchemeIsStandard() == false) and the input looks relative, we
130 // can't resolve it. In these cases, the result will be an empty, invalid
133 // The result may also be a nonempty, invalid URL if the input has some kind
134 // of encoding error. In these cases, we will try to construct a "good" URL
135 // that may have meaning to the user, but it will be marked invalid.
137 // It is an error to resolve a URL relative to an invalid URL. The result
138 // will be the empty URL.
139 GURL
Resolve(const std::string
& relative
) const;
140 GURL
Resolve(const base::string16
& relative
) const;
142 // Like Resolve() above but takes a character set encoder which will be used
143 // for any query text specified in the input. The charset converter parameter
144 // may be NULL, in which case it will be treated as UTF-8.
146 // TODO(brettw): These should be replaced with versions that take something
147 // more friendly than a raw CharsetConverter (maybe like an ICU character set
149 GURL
ResolveWithCharsetConverter(
150 const std::string
& relative
,
151 url_canon::CharsetConverter
* charset_converter
) const;
152 GURL
ResolveWithCharsetConverter(
153 const base::string16
& relative
,
154 url_canon::CharsetConverter
* charset_converter
) const;
156 // Creates a new GURL by replacing the current URL's components with the
157 // supplied versions. See the Replacements class in url_canon.h for more.
159 // These are not particularly quick, so avoid doing mutations when possible.
160 // Prefer the 8-bit version when possible.
162 // It is an error to replace components of an invalid URL. The result will
165 // Note that we use the more general url_canon::Replacements type to give
166 // callers extra flexibility rather than our override.
167 GURL
ReplaceComponents(
168 const url_canon::Replacements
<char>& replacements
) const;
169 GURL
ReplaceComponents(
170 const url_canon::Replacements
<base::char16
>& replacements
) const;
172 // A helper function that is equivalent to replacing the path with a slash
173 // and clearing out everything after that. We sometimes need to know just the
174 // scheme and the authority. If this URL is not a standard URL (it doesn't
175 // have the regular authority and path sections), then the result will be
176 // an empty, invalid GURL. Note that this *does* work for file: URLs, which
177 // some callers may want to filter out before calling this.
179 // It is an error to get an empty path on an invalid URL. The result
180 // will be the empty URL.
181 GURL
GetWithEmptyPath() const;
183 // A helper function to return a GURL containing just the scheme, host,
184 // and port from a URL. Equivalent to clearing any username and password,
185 // replacing the path with a slash, and clearing everything after that. If
186 // this URL is not a standard URL, then the result will be an empty,
187 // invalid GURL. If the URL has neither username nor password, this
188 // degenerates to GetWithEmptyPath().
190 // It is an error to get the origin of an invalid URL. The result
191 // will be the empty URL.
192 GURL
GetOrigin() const;
194 // Returns true if the scheme for the current URL is a known "standard"
195 // scheme. Standard schemes have an authority and a path section. This
196 // includes file: and filesystem:, which some callers may want to filter out
197 // explicitly by calling SchemeIsFile[System].
198 bool IsStandard() const;
200 // Returns true if the given parameter (should be lower-case ASCII to match
201 // the canonicalized scheme) is the scheme for this URL. This call is more
202 // efficient than getting the scheme and comparing it because no copies or
203 // object constructions are done.
204 bool SchemeIs(const char* lower_ascii_scheme
) const;
206 // Returns true if the scheme is "http" or "https".
207 bool SchemeIsHTTPOrHTTPS() const;
209 // We often need to know if this is a file URL. File URLs are "standard", but
210 // are often treated separately by some programs.
211 bool SchemeIsFile() const {
212 return SchemeIs("file");
215 // FileSystem URLs need to be treated differently in some cases.
216 bool SchemeIsFileSystem() const {
217 return SchemeIs("filesystem");
220 // If the scheme indicates a secure connection
221 bool SchemeIsSecure() const {
222 return SchemeIs("https") || SchemeIs("wss") ||
223 (SchemeIsFileSystem() && inner_url() && inner_url()->SchemeIsSecure());
226 // Returns true if the hostname is an IP address. Note: this function isn't
227 // as cheap as a simple getter because it re-parses the hostname to verify.
228 // This currently identifies only IPv4 addresses (bug 822685).
229 bool HostIsIPAddress() const;
231 // Getters for various components of the URL. The returned string will be
232 // empty if the component is empty or is not present.
233 std::string
scheme() const { // Not including the colon. See also SchemeIs.
234 return ComponentString(parsed_
.scheme
);
236 std::string
username() const {
237 return ComponentString(parsed_
.username
);
239 std::string
password() const {
240 return ComponentString(parsed_
.password
);
242 // Note that this may be a hostname, an IPv4 address, or an IPv6 literal
243 // surrounded by square brackets, like "[2001:db8::1]". To exclude these
244 // brackets, use HostNoBrackets() below.
245 std::string
host() const {
246 return ComponentString(parsed_
.host
);
248 std::string
port() const { // Returns -1 if "default"
249 return ComponentString(parsed_
.port
);
251 std::string
path() const { // Including first slash following host
252 return ComponentString(parsed_
.path
);
254 std::string
query() const { // Stuff following '?'
255 return ComponentString(parsed_
.query
);
257 std::string
ref() const { // Stuff following '#'
258 return ComponentString(parsed_
.ref
);
261 // Existance querying. These functions will return true if the corresponding
262 // URL component exists in this URL. Note that existance is different than
263 // being nonempty. http://www.google.com/? has a query that just happens to
264 // be empty, and has_query() will return true.
265 bool has_scheme() const {
266 return parsed_
.scheme
.len
>= 0;
268 bool has_username() const {
269 return parsed_
.username
.len
>= 0;
271 bool has_password() const {
272 return parsed_
.password
.len
>= 0;
274 bool has_host() const {
275 // Note that hosts are special, absense of host means length 0.
276 return parsed_
.host
.len
> 0;
278 bool has_port() const {
279 return parsed_
.port
.len
>= 0;
281 bool has_path() const {
282 // Note that http://www.google.com/" has a path, the path is "/". This can
283 // return false only for invalid or nonstandard URLs.
284 return parsed_
.path
.len
>= 0;
286 bool has_query() const {
287 return parsed_
.query
.len
>= 0;
289 bool has_ref() const {
290 return parsed_
.ref
.len
>= 0;
293 // Returns a parsed version of the port. Can also be any of the special
294 // values defined in Parsed for ExtractPort.
297 // Returns the port number of the url, or the default port number.
298 // If the scheme has no concept of port (or unknown default) returns
300 int EffectiveIntPort() const;
302 // Extracts the filename portion of the path and returns it. The filename
303 // is everything after the last slash in the path. This may be empty.
304 std::string
ExtractFileName() const;
306 // Returns the path that should be sent to the server. This is the path,
307 // parameter, and query portions of the URL. It is guaranteed to be ASCII.
308 std::string
PathForRequest() const;
310 // Returns the host, excluding the square brackets surrounding IPv6 address
311 // literals. This can be useful for passing to getaddrinfo().
312 std::string
HostNoBrackets() const;
314 // Returns true if this URL's host matches or is in the same domain as
315 // the given input string. For example if this URL was "www.google.com",
316 // this would match "com", "google.com", and "www.google.com
317 // (input domain should be lower-case ASCII to match the canonicalized
318 // scheme). This call is more efficient than getting the host and check
319 // whether host has the specific domain or not because no copies or
320 // object constructions are done.
322 // If function DomainIs has parameter domain_len, which means the parameter
323 // lower_ascii_domain does not gurantee to terminate with NULL character.
324 bool DomainIs(const char* lower_ascii_domain
, int domain_len
) const;
326 // If function DomainIs only has parameter lower_ascii_domain, which means
327 // domain string should be terminate with NULL character.
328 bool DomainIs(const char* lower_ascii_domain
) const {
329 return DomainIs(lower_ascii_domain
,
330 static_cast<int>(strlen(lower_ascii_domain
)));
333 // Swaps the contents of this GURL object with the argument without doing
334 // any memory allocations.
335 void Swap(GURL
* other
);
337 // Returns a reference to a singleton empty GURL. This object is for callers
338 // who return references but don't have anything to return in some cases.
339 // This function may be called from any thread.
340 static const GURL
& EmptyGURL();
342 // Returns the inner URL of a nested URL [currently only non-null for
343 // filesystem: URLs].
344 const GURL
* inner_url() const {
349 void InitializeFromCanonicalSpec();
351 // Returns the substring of the input identified by the given component.
352 std::string
ComponentString(const url_parse::Component
& comp
) const {
354 return std::string();
355 return std::string(spec_
, comp
.begin
, comp
.len
);
358 // The actual text of the URL, in canonical ASCII form.
361 // Set when the given URL is valid. Otherwise, we may still have a spec and
362 // components, but they may not identify valid resources (for example, an
363 // invalid port number, invalid characters in the scheme, etc.).
366 // Identified components of the canonical spec.
367 url_parse::Parsed parsed_
;
369 // Used for nested schemes [currently only filesystem:].
372 // TODO bug 684583: Add encoding for query params.
375 // Stream operator so GURL can be used in assertion statements.
376 URL_EXPORT
std::ostream
& operator<<(std::ostream
& out
, const GURL
& url
);
378 #endif // URL_GURL_H_