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 39 namespace url_parse { 40 41 // Deprecated, but WebKit/WebCore/platform/KURLGooglePrivate.h and 42 // KURLGoogle.cpp still rely on this type. 43 typedef char16 UTF16Char; 44 45 // Component ------------------------------------------------------------------ 46 47 // Represents a substring for URL parsing. 48 struct 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. 85 inline 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 // 109 struct 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. 220 GURL_API void ParseStandardURL(const char* url, int url_len, Parsed* parsed); 221 GURL_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:" 227 GURL_API void ParsePathURL(const char* url, int url_len, Parsed* parsed); 228 GURL_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. 232 GURL_API void ParseFileURL(const char* url, int url_len, Parsed* parsed); 233 GURL_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 236 GURL_API void ParseMailtoURL(const char* url, int url_len, Parsed* parsed); 237 GURL_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. 261 GURL_API bool ExtractScheme(const char* url, int url_len, Component* scheme); 262 GURL_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. 266 GURL_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. 270 GURL_API void ParseAuthority(const char* spec, 271 const Component& auth, 272 Component* username, 273 Component* password, 274 Component* hostname, 275 Component* port_num); 276 GURL_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. 289 enum SpecialPort { PORT_UNSPECIFIED = -1, PORT_INVALID = -2 }; 290 GURL_API int ParsePort(const char* url, const Component& port); 291 GURL_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. 303 GURL_API void ExtractFileName(const char* url, 304 const Component& path, 305 Component* file_name); 306 GURL_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. 325 GURL_API bool ExtractQueryKeyValue(const char* url, 326 Component* query, 327 Component* key, 328 Component* value); 329 GURL_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
