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.
5 #ifndef URL_THIRD_PARTY_MOZILLA_URL_PARSE_H_
6 #define URL_THIRD_PARTY_MOZILLA_URL_PARSE_H_
8 #include "base/strings/string16.h"
9 #include "url/url_export.h"
13 // Deprecated, but WebKit/WebCore/platform/KURLGooglePrivate.h and
14 // KURLGoogle.cpp still rely on this type.
15 typedef base::char16 UTF16Char
;
17 // Component ------------------------------------------------------------------
19 // Represents a substring for URL parsing.
21 Component() : begin(0), len(-1) {}
23 // Normal constructor: takes an offset and a length.
24 Component(int b
, int l
) : begin(b
), len(l
) {}
30 // Returns true if this component is valid, meaning the length is given. Even
31 // valid components may be empty to record the fact that they exist.
32 bool is_valid() const {
36 // Returns true if the given component is specified on false, the component
37 // is either empty or invalid.
38 bool is_nonempty() const {
47 bool operator==(const Component
& other
) const {
48 return begin
== other
.begin
&& len
== other
.len
;
51 int begin
; // Byte offset in the string of this component.
52 int len
; // Will be -1 if the component is unspecified.
55 // Helper that returns a component created with the given begin and ending
56 // points. The ending point is non-inclusive.
57 inline Component
MakeRange(int begin
, int end
) {
58 return Component(begin
, end
- begin
);
61 // Parsed ---------------------------------------------------------------------
63 // A structure that holds the identified parts of an input URL. This structure
64 // does NOT store the URL itself. The caller will have to store the URL text
65 // and its corresponding Parsed structure separately.
67 // Typical usage would be:
71 // if (!ExtractScheme(url, url_len, &scheme))
72 // return I_CAN_NOT_FIND_THE_SCHEME_DUDE;
74 // if (IsStandardScheme(url, scheme)) // Not provided by this component
75 // ParseStandardURL(url, url_len, &parsed);
76 // else if (IsFileURL(url, scheme)) // Not provided by this component
77 // ParseFileURL(url, url_len, &parsed);
79 // ParsePathURL(url, url_len, &parsed);
81 struct URL_EXPORT Parsed
{
82 // Identifies different components.
94 // The default constructor is sufficient for the components, but inner_parsed_
95 // requires special handling.
97 Parsed(const Parsed
&);
98 Parsed
& operator=(const Parsed
&);
101 // Returns the length of the URL (the end of the last component).
103 // Note that for some invalid, non-canonical URLs, this may not be the length
104 // of the string. For example "http://": the parsed structure will only
105 // contain an entry for the four-character scheme, and it doesn't know about
106 // the "://". For all other last-components, it will return the real length.
109 // Returns the number of characters before the given component if it exists,
110 // or where the component would be if it did exist. This will return the
111 // string length if the component would be appended to the end.
113 // Note that this can get a little funny for the port, query, and ref
114 // components which have a delimiter that is not counted as part of the
115 // component. The |include_delimiter| flag controls if you want this counted
116 // as part of the component or not when the component exists.
118 // This example shows the difference between the two flags for two of these
119 // delimited components that is present (the port and query) and one that
120 // isn't (the reference). The components that this flag affects are marked
123 // 012345678901234567890
124 // Example input: http://foo:80/?query
125 // include_delim=true, ...=false ("<-" indicates different)
135 int CountCharactersBefore(ComponentType type
, bool include_delimiter
) const;
137 // Scheme without the colon: "http://foo"/ would have a scheme of "http".
138 // The length will be -1 if no scheme is specified ("foo.com"), or 0 if there
139 // is a colon but no scheme (":foo"). Note that the scheme is not guaranteed
140 // to start at the beginning of the string if there are preceeding whitespace
141 // or control characters.
144 // Username. Specified in URLs with an @ sign before the host. See |password|
147 // Password. The length will be -1 if unspecified, 0 if specified but empty.
148 // Not all URLs with a username have a password, as in "http://me@host/".
149 // The password is separated form the username with a colon, as in
150 // "http://me:secret@host/"
159 // Path, this is everything following the host name, stopping at the query of
160 // ref delimiter (if any). Length will be -1 if unspecified. This includes
161 // the preceeding slash, so the path on http://www.google.com/asdf" is
162 // "/asdf". As a result, it is impossible to have a 0 length path, it will
163 // be -1 in cases like "http://host?foo".
164 // Note that we treat backslashes the same as slashes.
167 // Stuff between the ? and the # after the path. This does not include the
168 // preceeding ? character. Length will be -1 if unspecified, 0 if there is
169 // a question mark but no query string.
172 // Indicated by a #, this is everything following the hash sign (not
173 // including it). If there are multiple hash signs, we'll use the last one.
174 // Length will be -1 if there is no hash sign, or 0 if there is one but
175 // nothing follows it.
178 // The URL spec from the character after the scheme: until the end of the
179 // URL, regardless of the scheme. This is mostly useful for 'opaque' non-
180 // hierarchical schemes like data: and javascript: as a convient way to get
181 // the string with the scheme stripped off.
182 Component
GetContent() const;
184 // This is used for nested URL types, currently only filesystem. If you
185 // parse a filesystem URL, the resulting Parsed will have a nested
186 // inner_parsed_ to hold the parsed inner URL's component information.
187 // For all other url types [including the inner URL], it will be NULL.
188 Parsed
* inner_parsed() const {
189 return inner_parsed_
;
192 void set_inner_parsed(const Parsed
& inner_parsed
) {
194 inner_parsed_
= new Parsed(inner_parsed
);
196 *inner_parsed_
= inner_parsed
;
199 void clear_inner_parsed() {
201 delete inner_parsed_
;
202 inner_parsed_
= NULL
;
207 Parsed
* inner_parsed_
; // This object is owned and managed by this struct.
210 // Initialization functions ---------------------------------------------------
212 // These functions parse the given URL, filling in all of the structure's
213 // components. These functions can not fail, they will always do their best
214 // at interpreting the input given.
216 // The string length of the URL MUST be specified, we do not check for NULLs
217 // at any point in the process, and will actually handle embedded NULLs.
219 // IMPORTANT: These functions do NOT hang on to the given pointer or copy it
220 // in any way. See the comment above the struct.
222 // The 8-bit versions require UTF-8 encoding.
224 // StandardURL is for when the scheme is known to be one that has an
225 // authority (host) like "http". This function will not handle weird ones
226 // like "about:" and "javascript:", or do the right thing for "file:" URLs.
227 URL_EXPORT
void ParseStandardURL(const char* url
,
230 URL_EXPORT
void ParseStandardURL(const base::char16
* url
,
234 // PathURL is for when the scheme is known not to have an authority (host)
235 // section but that aren't file URLs either. The scheme is parsed, and
236 // everything after the scheme is considered as the path. This is used for
237 // things like "about:" and "javascript:"
238 URL_EXPORT
void ParsePathURL(const char* url
,
242 URL_EXPORT
void ParsePathURL(const base::char16
* url
,
247 // FileURL is for file URLs. There are some special rules for interpreting
249 URL_EXPORT
void ParseFileURL(const char* url
, int url_len
, Parsed
* parsed
);
250 URL_EXPORT
void ParseFileURL(const base::char16
* url
,
254 // Filesystem URLs are structured differently than other URLs.
255 URL_EXPORT
void ParseFileSystemURL(const char* url
,
258 URL_EXPORT
void ParseFileSystemURL(const base::char16
* url
,
262 // MailtoURL is for mailto: urls. They are made up scheme,path,query
263 URL_EXPORT
void ParseMailtoURL(const char* url
, int url_len
, Parsed
* parsed
);
264 URL_EXPORT
void ParseMailtoURL(const base::char16
* url
,
268 // Helper functions -----------------------------------------------------------
270 // Locates the scheme according to the URL parser's rules. This function is
271 // designed so the caller can find the scheme and call the correct Init*
272 // function according to their known scheme types.
274 // It also does not perform any validation on the scheme.
276 // This function will return true if the scheme is found and will put the
277 // scheme's range into *scheme. False means no scheme could be found. Note
278 // that a URL beginning with a colon has a scheme, but it is empty, so this
279 // function will return true but *scheme will = (0,0).
281 // The scheme is found by skipping spaces and control characters at the
282 // beginning, and taking everything from there to the first colon to be the
283 // scheme. The character at scheme.end() will be the colon (we may enhance
284 // this to handle full width colons or something, so don't count on the
285 // actual character value). The character at scheme.end()+1 will be the
286 // beginning of the rest of the URL, be it the authority or the path (or the
287 // end of the string).
289 // The 8-bit version requires UTF-8 encoding.
290 URL_EXPORT
bool ExtractScheme(const char* url
,
293 URL_EXPORT
bool ExtractScheme(const base::char16
* url
,
297 // Returns true if ch is a character that terminates the authority segment
299 URL_EXPORT
bool IsAuthorityTerminator(base::char16 ch
);
301 // Does a best effort parse of input |spec|, in range |auth|. If a particular
302 // component is not found, it will be set to invalid.
303 URL_EXPORT
void ParseAuthority(const char* spec
,
304 const Component
& auth
,
308 Component
* port_num
);
309 URL_EXPORT
void ParseAuthority(const base::char16
* spec
,
310 const Component
& auth
,
314 Component
* port_num
);
316 // Computes the integer port value from the given port component. The port
317 // component should have been identified by one of the init functions on
318 // |Parsed| for the given input url.
320 // The return value will be a positive integer between 0 and 64K, or one of
321 // the two special values below.
322 enum SpecialPort
{ PORT_UNSPECIFIED
= -1, PORT_INVALID
= -2 };
323 URL_EXPORT
int ParsePort(const char* url
, const Component
& port
);
324 URL_EXPORT
int ParsePort(const base::char16
* url
, const Component
& port
);
326 // Extracts the range of the file name in the given url. The path must
327 // already have been computed by the parse function, and the matching URL
328 // and extracted path are provided to this function. The filename is
329 // defined as being everything from the last slash/backslash of the path
330 // to the end of the path.
332 // The file name will be empty if the path is empty or there is nothing
333 // following the last slash.
335 // The 8-bit version requires UTF-8 encoding.
336 URL_EXPORT
void ExtractFileName(const char* url
,
337 const Component
& path
,
338 Component
* file_name
);
339 URL_EXPORT
void ExtractFileName(const base::char16
* url
,
340 const Component
& path
,
341 Component
* file_name
);
343 // Extract the first key/value from the range defined by |*query|. Updates
344 // |*query| to start at the end of the extracted key/value pair. This is
345 // designed for use in a loop: you can keep calling it with the same query
346 // object and it will iterate over all items in the query.
348 // Some key/value pairs may have the key, the value, or both be empty (for
349 // example, the query string "?&"). These will be returned. Note that an empty
350 // last parameter "foo.com?" or foo.com?a&" will not be returned, this case
351 // is the same as "done."
353 // The initial query component should not include the '?' (this is the default
356 // If no key/value are found |*key| and |*value| will be unchanged and it will
358 URL_EXPORT
bool ExtractQueryKeyValue(const char* url
,
362 URL_EXPORT
bool ExtractQueryKeyValue(const base::char16
* url
,
369 #endif // URL_THIRD_PARTY_MOZILLA_URL_PARSE_H_