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