1// Copyright 2007, Google Inc.
2// 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 are
6// met:
7//
8//     * Redistributions of source code must retain the above copyright
9// notice, this list of conditions and the following disclaimer.
10//     * Redistributions in binary form must reproduce the above
11// copyright notice, this list of conditions and the following disclaimer
12// in the documentation and/or other materials provided with the
13// distribution.
14//     * Neither the name of Google Inc. nor the names of its
15// contributors may be used to endorse or promote products derived from
16// this software without specific prior written permission.
17//
18// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29
30#ifndef GOOGLEURL_SRC_URL_PARSE_H__
31#define GOOGLEURL_SRC_URL_PARSE_H__
32
33#include <string>
34
35#include "base/basictypes.h"
36#include "base/string16.h"
37#include "googleurl/src/url_common.h"
38
39namespace url_parse {
40
41// Deprecated, but WebKit/WebCore/platform/KURLGooglePrivate.h and
42// KURLGoogle.cpp still rely on this type.
43typedef char16 UTF16Char;
44
45// Component ------------------------------------------------------------------
46
47// Represents a substring for URL parsing.
48struct Component {
49  Component() : begin(0), len(-1) {}
50
51  // Normal constructor: takes an offset and a length.
52  Component(int b, int l) : begin(b), len(l) {}
53
54  int end() const {
55    return begin + len;
56  }
57
58  // Returns true if this component is valid, meaning the length is given. Even
59  // valid components may be empty to record the fact that they exist.
60  bool is_valid() const {
61    return (len != -1);
62  }
63
64  // Returns true if the given component is specified on false, the component
65  // is either empty or invalid.
66  bool is_nonempty() const {
67    return (len > 0);
68  }
69
70  void reset() {
71    begin = 0;
72    len = -1;
73  }
74
75  bool operator==(const Component& other) const {
76    return begin == other.begin && len == other.len;
77  }
78
79  int begin;  // Byte offset in the string of this component.
80  int len;    // Will be -1 if the component is unspecified.
81};
82
83// Helper that returns a component created with the given begin and ending
84// points. The ending point is non-inclusive.
85inline Component MakeRange(int begin, int end) {
86  return Component(begin, end - begin);
87}
88
89// Parsed ---------------------------------------------------------------------
90
91// A structure that holds the identified parts of an input URL. This structure
92// does NOT store the URL itself. The caller will have to store the URL text
93// and its corresponding Parsed structure separately.
94//
95// Typical usage would be:
96//
97//    url_parse::Parsed parsed;
98//    url_parse::Component scheme;
99//    if (!url_parse::ExtractScheme(url, url_len, &scheme))
100//      return I_CAN_NOT_FIND_THE_SCHEME_DUDE;
101//
102//    if (IsStandardScheme(url, scheme))  // Not provided by this component
103//      url_parseParseStandardURL(url, url_len, &parsed);
104//    else if (IsFileURL(url, scheme))    // Not provided by this component
105//      url_parse::ParseFileURL(url, url_len, &parsed);
106//    else
107//      url_parse::ParsePathURL(url, url_len, &parsed);
108//
109struct Parsed {
110  // Identifies different components.
111  enum ComponentType {
112    SCHEME,
113    USERNAME,
114    PASSWORD,
115    HOST,
116    PORT,
117    PATH,
118    QUERY,
119    REF,
120  };
121
122  // The default constructor is sufficient for the components.
123  GURL_API Parsed();
124
125  // Returns the length of the URL (the end of the last component).
126  //
127  // Note that for some invalid, non-canonical URLs, this may not be the length
128  // of the string. For example "http://": the parsed structure will only
129  // contain an entry for the four-character scheme, and it doesn't know about
130  // the "://". For all other last-components, it will return the real length.
131  GURL_API int Length() const;
132
133  // Returns the number of characters before the given component if it exists,
134  // or where the component would be if it did exist. This will return the
135  // string length if the component would be appended to the end.
136  //
137  // Note that this can get a little funny for the port, query, and ref
138  // components which have a delimiter that is not counted as part of the
139  // component. The |include_delimiter| flag controls if you want this counted
140  // as part of the component or not when the component exists.
141  //
142  // This example shows the difference between the two flags for two of these
143  // delimited components that is present (the port and query) and one that
144  // isn't (the reference). The components that this flag affects are marked
145  // with a *.
146  //                 0         1         2
147  //                 012345678901234567890
148  // Example input:  http://foo:80/?query
149  //              include_delim=true,  ...=false  ("<-" indicates different)
150  //      SCHEME: 0                    0
151  //    USERNAME: 5                    5
152  //    PASSWORD: 5                    5
153  //        HOST: 7                    7
154  //       *PORT: 10                   11 <-
155  //        PATH: 13                   13
156  //      *QUERY: 14                   15 <-
157  //        *REF: 20                   20
158  //
159  GURL_API int CountCharactersBefore(ComponentType type,
160                                     bool include_delimiter) const;
161
162  // Scheme without the colon: "http://foo"/ would have a scheme of "http".
163  // The length will be -1 if no scheme is specified ("foo.com"), or 0 if there
164  // is a colon but no scheme (":foo"). Note that the scheme is not guaranteed
165  // to start at the beginning of the string if there are preceeding whitespace
166  // or control characters.
167  Component scheme;
168
169  // Username. Specified in URLs with an @ sign before the host. See |password|
170  Component username;
171
172  // Password. The length will be -1 if unspecified, 0 if specified but empty.
173  // Not all URLs with a username have a password, as in "http://me@host/".
174  // The password is separated form the username with a colon, as in
175  // "http://me:secret@host/"
176  Component password;
177
178  // Host name.
179  Component host;
180
181  // Port number.
182  Component port;
183
184  // Path, this is everything following the host name. Length will be -1 if
185  // unspecified. This includes the preceeding slash, so the path on
186  // http://www.google.com/asdf" is "/asdf". As a result, it is impossible to
187  // have a 0 length path, it will be -1 in cases like "http://host?foo".
188  // Note that we treat backslashes the same as slashes.
189  Component path;
190
191  // Stuff between the ? and the # after the path. This does not include the
192  // preceeding ? character. Length will be -1 if unspecified, 0 if there is
193  // a question mark but no query string.
194  Component query;
195
196  // Indicated by a #, this is everything following the hash sign (not
197  // including it). If there are multiple hash signs, we'll use the last one.
198  // Length will be -1 if there is no hash sign, or 0 if there is one but
199  // nothing follows it.
200  Component ref;
201};
202
203// Initialization functions ---------------------------------------------------
204//
205// These functions parse the given URL, filling in all of the structure's
206// components. These functions can not fail, they will always do their best
207// at interpreting the input given.
208//
209// The string length of the URL MUST be specified, we do not check for NULLs
210// at any point in the process, and will actually handle embedded NULLs.
211//
212// IMPORTANT: These functions do NOT hang on to the given pointer or copy it
213// in any way. See the comment above the struct.
214//
215// The 8-bit versions require UTF-8 encoding.
216
217// StandardURL is for when the scheme is known to be one that has an
218// authority (host) like "http". This function will not handle weird ones
219// like "about:" and "javascript:", or do the right thing for "file:" URLs.
220GURL_API void ParseStandardURL(const char* url, int url_len, Parsed* parsed);
221GURL_API void ParseStandardURL(const char16* url, int url_len, Parsed* parsed);
222
223// PathURL is for when the scheme is known not to have an authority (host)
224// section but that aren't file URLs either. The scheme is parsed, and
225// everything after the scheme is considered as the path. This is used for
226// things like "about:" and "javascript:"
227GURL_API void ParsePathURL(const char* url, int url_len, Parsed* parsed);
228GURL_API void ParsePathURL(const char16* url, int url_len, Parsed* parsed);
229
230// FileURL is for file URLs. There are some special rules for interpreting
231// these.
232GURL_API void ParseFileURL(const char* url, int url_len, Parsed* parsed);
233GURL_API void ParseFileURL(const char16* url, int url_len, Parsed* parsed);
234
235// MailtoURL is for mailto: urls. They are made up scheme,path,query
236GURL_API void ParseMailtoURL(const char* url, int url_len, Parsed* parsed);
237GURL_API void ParseMailtoURL(const char16* url, int url_len, Parsed* parsed);
238
239// Helper functions -----------------------------------------------------------
240
241// Locates the scheme according to the URL  parser's rules. This function is
242// designed so the caller can find the scheme and call the correct Init*
243// function according to their known scheme types.
244//
245// It also does not perform any validation on the scheme.
246//
247// This function will return true if the scheme is found and will put the
248// scheme's range into *scheme. False means no scheme could be found. Note
249// that a URL beginning with a colon has a scheme, but it is empty, so this
250// function will return true but *scheme will = (0,0).
251//
252// The scheme is found by skipping spaces and control characters at the
253// beginning, and taking everything from there to the first colon to be the
254// scheme. The character at scheme.end() will be the colon (we may enhance
255// this to handle full width colons or something, so don't count on the
256// actual character value). The character at scheme.end()+1 will be the
257// beginning of the rest of the URL, be it the authority or the path (or the
258// end of the string).
259//
260// The 8-bit version requires UTF-8 encoding.
261GURL_API bool ExtractScheme(const char* url, int url_len, Component* scheme);
262GURL_API bool ExtractScheme(const char16* url, int url_len, Component* scheme);
263
264// Returns true if ch is a character that terminates the authority segment
265// of a URL.
266GURL_API bool IsAuthorityTerminator(char16 ch);
267
268// Does a best effort parse of input |spec|, in range |auth|. If a particular
269// component is not found, it will be set to invalid.
270GURL_API void ParseAuthority(const char* spec,
271                             const Component& auth,
272                             Component* username,
273                             Component* password,
274                             Component* hostname,
275                             Component* port_num);
276GURL_API void ParseAuthority(const char16* spec,
277                             const Component& auth,
278                             Component* username,
279                             Component* password,
280                             Component* hostname,
281                             Component* port_num);
282
283// Computes the integer port value from the given port component. The port
284// component should have been identified by one of the init functions on
285// |Parsed| for the given input url.
286//
287// The return value will be a positive integer between 0 and 64K, or one of
288// the two special values below.
289enum SpecialPort { PORT_UNSPECIFIED = -1, PORT_INVALID = -2 };
290GURL_API int ParsePort(const char* url, const Component& port);
291GURL_API int ParsePort(const char16* url, const Component& port);
292
293// Extracts the range of the file name in the given url. The path must
294// already have been computed by the parse function, and the matching URL
295// and extracted path are provided to this function. The filename is
296// defined as being everything from the last slash/backslash of the path
297// to the end of the path.
298//
299// The file name will be empty if the path is empty or there is nothing
300// following the last slash.
301//
302// The 8-bit version requires UTF-8 encoding.
303GURL_API void ExtractFileName(const char* url,
304                              const Component& path,
305                              Component* file_name);
306GURL_API void ExtractFileName(const char16* url,
307                              const Component& path,
308                              Component* file_name);
309
310// Extract the first key/value from the range defined by |*query|. Updates
311// |*query| to start at the end of the extracted key/value pair. This is
312// designed for use in a loop: you can keep calling it with the same query
313// object and it will iterate over all items in the query.
314//
315// Some key/value pairs may have the key, the value, or both be empty (for
316// example, the query string "?&"). These will be returned. Note that an empty
317// last parameter "foo.com?" or foo.com?a&" will not be returned, this case
318// is the same as "done."
319//
320// The initial query component should not include the '?' (this is the default
321// for parsed URLs).
322//
323// If no key/value are found |*key| and |*value| will be unchanged and it will
324// return false.
325GURL_API bool ExtractQueryKeyValue(const char* url,
326                                   Component* query,
327                                   Component* key,
328                                   Component* value);
329GURL_API bool ExtractQueryKeyValue(const char16* url,
330                                   Component* query,
331                                   Component* key,
332                                   Component* value);
333
334}  // namespace url_parse
335
336#endif  // GOOGLEURL_SRC_URL_PARSE_H__
337