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. 4 5 #ifndef URL_URL_CANON_H_ 6 #define URL_URL_CANON_H_ 7 8 #include <stdlib.h> 9 #include <string.h> 10 11 #include "base/strings/string16.h" 12 #include "url/url_export.h" 13 #include "url/url_parse.h" 14 15 namespace url_canon { 16 17 // Canonicalizer output ------------------------------------------------------- 18 19 // Base class for the canonicalizer output, this maintains a buffer and 20 // supports simple resizing and append operations on it. 21 // 22 // It is VERY IMPORTANT that no virtual function calls be made on the common 23 // code path. We only have two virtual function calls, the destructor and a 24 // resize function that is called when the existing buffer is not big enough. 25 // The derived class is then in charge of setting up our buffer which we will 26 // manage. 27 template<typename T> 28 class CanonOutputT { 29 public: 30 CanonOutputT() : buffer_(NULL), buffer_len_(0), cur_len_(0) { 31 } 32 virtual ~CanonOutputT() { 33 } 34 35 // Implemented to resize the buffer. This function should update the buffer 36 // pointer to point to the new buffer, and any old data up to |cur_len_| in 37 // the buffer must be copied over. 38 // 39 // The new size |sz| must be larger than buffer_len_. 40 virtual void Resize(int sz) = 0; 41 42 // Accessor for returning a character at a given position. The input offset 43 // must be in the valid range. 44 inline char at(int offset) const { 45 return buffer_[offset]; 46 } 47 48 // Sets the character at the given position. The given position MUST be less 49 // than the length(). 50 inline void set(int offset, int ch) { 51 buffer_[offset] = ch; 52 } 53 54 // Returns the number of characters currently in the buffer. 55 inline int length() const { 56 return cur_len_; 57 } 58 59 // Returns the current capacity of the buffer. The length() is the number of 60 // characters that have been declared to be written, but the capacity() is 61 // the number that can be written without reallocation. If the caller must 62 // write many characters at once, it can make sure there is enough capacity, 63 // write the data, then use set_size() to declare the new length(). 64 int capacity() const { 65 return buffer_len_; 66 } 67 68 // Called by the user of this class to get the output. The output will NOT 69 // be NULL-terminated. Call length() to get the 70 // length. 71 const T* data() const { 72 return buffer_; 73 } 74 T* data() { 75 return buffer_; 76 } 77 78 // Shortens the URL to the new length. Used for "backing up" when processing 79 // relative paths. This can also be used if an external function writes a lot 80 // of data to the buffer (when using the "Raw" version below) beyond the end, 81 // to declare the new length. 82 // 83 // This MUST NOT be used to expand the size of the buffer beyond capacity(). 84 void set_length(int new_len) { 85 cur_len_ = new_len; 86 } 87 88 // This is the most performance critical function, since it is called for 89 // every character. 90 void push_back(T ch) { 91 // In VC2005, putting this common case first speeds up execution 92 // dramatically because this branch is predicted as taken. 93 if (cur_len_ < buffer_len_) { 94 buffer_[cur_len_] = ch; 95 cur_len_++; 96 return; 97 } 98 99 // Grow the buffer to hold at least one more item. Hopefully we won't have 100 // to do this very often. 101 if (!Grow(1)) 102 return; 103 104 // Actually do the insertion. 105 buffer_[cur_len_] = ch; 106 cur_len_++; 107 } 108 109 // Appends the given string to the output. 110 void Append(const T* str, int str_len) { 111 if (cur_len_ + str_len > buffer_len_) { 112 if (!Grow(cur_len_ + str_len - buffer_len_)) 113 return; 114 } 115 for (int i = 0; i < str_len; i++) 116 buffer_[cur_len_ + i] = str[i]; 117 cur_len_ += str_len; 118 } 119 120 protected: 121 // Grows the given buffer so that it can fit at least |min_additional| 122 // characters. Returns true if the buffer could be resized, false on OOM. 123 bool Grow(int min_additional) { 124 static const int kMinBufferLen = 16; 125 int new_len = (buffer_len_ == 0) ? kMinBufferLen : buffer_len_; 126 do { 127 if (new_len >= (1 << 30)) // Prevent overflow below. 128 return false; 129 new_len *= 2; 130 } while (new_len < buffer_len_ + min_additional); 131 Resize(new_len); 132 return true; 133 } 134 135 T* buffer_; 136 int buffer_len_; 137 138 // Used characters in the buffer. 139 int cur_len_; 140 }; 141 142 // Simple implementation of the CanonOutput using new[]. This class 143 // also supports a static buffer so if it is allocated on the stack, most 144 // URLs can be canonicalized with no heap allocations. 145 template<typename T, int fixed_capacity = 1024> 146 class RawCanonOutputT : public CanonOutputT<T> { 147 public: 148 RawCanonOutputT() : CanonOutputT<T>() { 149 this->buffer_ = fixed_buffer_; 150 this->buffer_len_ = fixed_capacity; 151 } 152 virtual ~RawCanonOutputT() { 153 if (this->buffer_ != fixed_buffer_) 154 delete[] this->buffer_; 155 } 156 157 virtual void Resize(int sz) { 158 T* new_buf = new T[sz]; 159 memcpy(new_buf, this->buffer_, 160 sizeof(T) * (this->cur_len_ < sz ? this->cur_len_ : sz)); 161 if (this->buffer_ != fixed_buffer_) 162 delete[] this->buffer_; 163 this->buffer_ = new_buf; 164 this->buffer_len_ = sz; 165 } 166 167 protected: 168 T fixed_buffer_[fixed_capacity]; 169 }; 170 171 // Normally, all canonicalization output is in narrow characters. We support 172 // the templates so it can also be used internally if a wide buffer is 173 // required. 174 typedef CanonOutputT<char> CanonOutput; 175 typedef CanonOutputT<base::char16> CanonOutputW; 176 177 template<int fixed_capacity> 178 class RawCanonOutput : public RawCanonOutputT<char, fixed_capacity> {}; 179 template<int fixed_capacity> 180 class RawCanonOutputW : public RawCanonOutputT<base::char16, fixed_capacity> {}; 181 182 // Character set converter ---------------------------------------------------- 183 // 184 // Converts query strings into a custom encoding. The embedder can supply an 185 // implementation of this class to interface with their own character set 186 // conversion libraries. 187 // 188 // Embedders will want to see the unit test for the ICU version. 189 190 class URL_EXPORT CharsetConverter { 191 public: 192 CharsetConverter() {} 193 virtual ~CharsetConverter() {} 194 195 // Converts the given input string from UTF-16 to whatever output format the 196 // converter supports. This is used only for the query encoding conversion, 197 // which does not fail. Instead, the converter should insert "invalid 198 // character" characters in the output for invalid sequences, and do the 199 // best it can. 200 // 201 // If the input contains a character not representable in the output 202 // character set, the converter should append the HTML entity sequence in 203 // decimal, (such as "你") with escaping of the ampersand, number 204 // sign, and semicolon (in the previous example it would be 205 // "%26%2320320%3B"). This rule is based on what IE does in this situation. 206 virtual void ConvertFromUTF16(const base::char16* input, 207 int input_len, 208 CanonOutput* output) = 0; 209 }; 210 211 // Whitespace ----------------------------------------------------------------- 212 213 // Searches for whitespace that should be removed from the middle of URLs, and 214 // removes it. Removed whitespace are tabs and newlines, but NOT spaces. Spaces 215 // are preserved, which is what most browsers do. A pointer to the output will 216 // be returned, and the length of that output will be in |output_len|. 217 // 218 // This should be called before parsing if whitespace removal is desired (which 219 // it normally is when you are canonicalizing). 220 // 221 // If no whitespace is removed, this function will not use the buffer and will 222 // return a pointer to the input, to avoid the extra copy. If modification is 223 // required, the given |buffer| will be used and the returned pointer will 224 // point to the beginning of the buffer. 225 // 226 // Therefore, callers should not use the buffer, since it may actually be empty, 227 // use the computed pointer and |*output_len| instead. 228 URL_EXPORT const char* RemoveURLWhitespace(const char* input, int input_len, 229 CanonOutputT<char>* buffer, 230 int* output_len); 231 URL_EXPORT const base::char16* RemoveURLWhitespace( 232 const base::char16* input, 233 int input_len, 234 CanonOutputT<base::char16>* buffer, 235 int* output_len); 236 237 // IDN ------------------------------------------------------------------------ 238 239 // Converts the Unicode input representing a hostname to ASCII using IDN rules. 240 // The output must fall in the ASCII range, but will be encoded in UTF-16. 241 // 242 // On success, the output will be filled with the ASCII host name and it will 243 // return true. Unlike most other canonicalization functions, this assumes that 244 // the output is empty. The beginning of the host will be at offset 0, and 245 // the length of the output will be set to the length of the new host name. 246 // 247 // On error, returns false. The output in this case is undefined. 248 URL_EXPORT bool IDNToASCII(const base::char16* src, 249 int src_len, 250 CanonOutputW* output); 251 252 // Piece-by-piece canonicalizers ---------------------------------------------- 253 // 254 // These individual canonicalizers append the canonicalized versions of the 255 // corresponding URL component to the given std::string. The spec and the 256 // previously-identified range of that component are the input. The range of 257 // the canonicalized component will be written to the output component. 258 // 259 // These functions all append to the output so they can be chained. Make sure 260 // the output is empty when you start. 261 // 262 // These functions returns boolean values indicating success. On failure, they 263 // will attempt to write something reasonable to the output so that, if 264 // displayed to the user, they will recognise it as something that's messed up. 265 // Nothing more should ever be done with these invalid URLs, however. 266 267 // Scheme: Appends the scheme and colon to the URL. The output component will 268 // indicate the range of characters up to but not including the colon. 269 // 270 // Canonical URLs always have a scheme. If the scheme is not present in the 271 // input, this will just write the colon to indicate an empty scheme. Does not 272 // append slashes which will be needed before any authority components for most 273 // URLs. 274 // 275 // The 8-bit version requires UTF-8 encoding. 276 URL_EXPORT bool CanonicalizeScheme(const char* spec, 277 const url_parse::Component& scheme, 278 CanonOutput* output, 279 url_parse::Component* out_scheme); 280 URL_EXPORT bool CanonicalizeScheme(const base::char16* spec, 281 const url_parse::Component& scheme, 282 CanonOutput* output, 283 url_parse::Component* out_scheme); 284 285 // User info: username/password. If present, this will add the delimiters so 286 // the output will be "<username>:<password>@" or "<username>@". Empty 287 // username/password pairs, or empty passwords, will get converted to 288 // nonexistant in the canonical version. 289 // 290 // The components for the username and password refer to ranges in the 291 // respective source strings. Usually, these will be the same string, which 292 // is legal as long as the two components don't overlap. 293 // 294 // The 8-bit version requires UTF-8 encoding. 295 URL_EXPORT bool CanonicalizeUserInfo(const char* username_source, 296 const url_parse::Component& username, 297 const char* password_source, 298 const url_parse::Component& password, 299 CanonOutput* output, 300 url_parse::Component* out_username, 301 url_parse::Component* out_password); 302 URL_EXPORT bool CanonicalizeUserInfo(const base::char16* username_source, 303 const url_parse::Component& username, 304 const base::char16* password_source, 305 const url_parse::Component& password, 306 CanonOutput* output, 307 url_parse::Component* out_username, 308 url_parse::Component* out_password); 309 310 311 // This structure holds detailed state exported from the IP/Host canonicalizers. 312 // Additional fields may be added as callers require them. 313 struct CanonHostInfo { 314 CanonHostInfo() : family(NEUTRAL), num_ipv4_components(0), out_host() {} 315 316 // Convenience function to test if family is an IP address. 317 bool IsIPAddress() const { return family == IPV4 || family == IPV6; } 318 319 // This field summarizes how the input was classified by the canonicalizer. 320 enum Family { 321 NEUTRAL, // - Doesn't resemble an IP address. As far as the IP 322 // canonicalizer is concerned, it should be treated as a 323 // hostname. 324 BROKEN, // - Almost an IP, but was not canonicalized. This could be an 325 // IPv4 address where truncation occurred, or something 326 // containing the special characters :[] which did not parse 327 // as an IPv6 address. Never attempt to connect to this 328 // address, because it might actually succeed! 329 IPV4, // - Successfully canonicalized as an IPv4 address. 330 IPV6, // - Successfully canonicalized as an IPv6 address. 331 }; 332 Family family; 333 334 // If |family| is IPV4, then this is the number of nonempty dot-separated 335 // components in the input text, from 1 to 4. If |family| is not IPV4, 336 // this value is undefined. 337 int num_ipv4_components; 338 339 // Location of host within the canonicalized output. 340 // CanonicalizeIPAddress() only sets this field if |family| is IPV4 or IPV6. 341 // CanonicalizeHostVerbose() always sets it. 342 url_parse::Component out_host; 343 344 // |address| contains the parsed IP Address (if any) in its first 345 // AddressLength() bytes, in network order. If IsIPAddress() is false 346 // AddressLength() will return zero and the content of |address| is undefined. 347 unsigned char address[16]; 348 349 // Convenience function to calculate the length of an IP address corresponding 350 // to the current IP version in |family|, if any. For use with |address|. 351 int AddressLength() const { 352 return family == IPV4 ? 4 : (family == IPV6 ? 16 : 0); 353 } 354 }; 355 356 357 // Host. 358 // 359 // The 8-bit version requires UTF-8 encoding. Use this version when you only 360 // need to know whether canonicalization succeeded. 361 URL_EXPORT bool CanonicalizeHost(const char* spec, 362 const url_parse::Component& host, 363 CanonOutput* output, 364 url_parse::Component* out_host); 365 URL_EXPORT bool CanonicalizeHost(const base::char16* spec, 366 const url_parse::Component& host, 367 CanonOutput* output, 368 url_parse::Component* out_host); 369 370 // Extended version of CanonicalizeHost, which returns additional information. 371 // Use this when you need to know whether the hostname was an IP address. 372 // A successful return is indicated by host_info->family != BROKEN. See the 373 // definition of CanonHostInfo above for details. 374 URL_EXPORT void CanonicalizeHostVerbose(const char* spec, 375 const url_parse::Component& host, 376 CanonOutput* output, 377 CanonHostInfo* host_info); 378 URL_EXPORT void CanonicalizeHostVerbose(const base::char16* spec, 379 const url_parse::Component& host, 380 CanonOutput* output, 381 CanonHostInfo* host_info); 382 383 384 // IP addresses. 385 // 386 // Tries to interpret the given host name as an IPv4 or IPv6 address. If it is 387 // an IP address, it will canonicalize it as such, appending it to |output|. 388 // Additional status information is returned via the |*host_info| parameter. 389 // See the definition of CanonHostInfo above for details. 390 // 391 // This is called AUTOMATICALLY from the host canonicalizer, which ensures that 392 // the input is unescaped and name-prepped, etc. It should not normally be 393 // necessary or wise to call this directly. 394 URL_EXPORT void CanonicalizeIPAddress(const char* spec, 395 const url_parse::Component& host, 396 CanonOutput* output, 397 CanonHostInfo* host_info); 398 URL_EXPORT void CanonicalizeIPAddress(const base::char16* spec, 399 const url_parse::Component& host, 400 CanonOutput* output, 401 CanonHostInfo* host_info); 402 403 // Port: this function will add the colon for the port if a port is present. 404 // The caller can pass url_parse::PORT_UNSPECIFIED as the 405 // default_port_for_scheme argument if there is no default port. 406 // 407 // The 8-bit version requires UTF-8 encoding. 408 URL_EXPORT bool CanonicalizePort(const char* spec, 409 const url_parse::Component& port, 410 int default_port_for_scheme, 411 CanonOutput* output, 412 url_parse::Component* out_port); 413 URL_EXPORT bool CanonicalizePort(const base::char16* spec, 414 const url_parse::Component& port, 415 int default_port_for_scheme, 416 CanonOutput* output, 417 url_parse::Component* out_port); 418 419 // Returns the default port for the given canonical scheme, or PORT_UNSPECIFIED 420 // if the scheme is unknown. 421 URL_EXPORT int DefaultPortForScheme(const char* scheme, int scheme_len); 422 423 // Path. If the input does not begin in a slash (including if the input is 424 // empty), we'll prepend a slash to the path to make it canonical. 425 // 426 // The 8-bit version assumes UTF-8 encoding, but does not verify the validity 427 // of the UTF-8 (i.e., you can have invalid UTF-8 sequences, invalid 428 // characters, etc.). Normally, URLs will come in as UTF-16, so this isn't 429 // an issue. Somebody giving us an 8-bit path is responsible for generating 430 // the path that the server expects (we'll escape high-bit characters), so 431 // if something is invalid, it's their problem. 432 URL_EXPORT bool CanonicalizePath(const char* spec, 433 const url_parse::Component& path, 434 CanonOutput* output, 435 url_parse::Component* out_path); 436 URL_EXPORT bool CanonicalizePath(const base::char16* spec, 437 const url_parse::Component& path, 438 CanonOutput* output, 439 url_parse::Component* out_path); 440 441 // Canonicalizes the input as a file path. This is like CanonicalizePath except 442 // that it also handles Windows drive specs. For example, the path can begin 443 // with "c|\" and it will get properly canonicalized to "C:/". 444 // The string will be appended to |*output| and |*out_path| will be updated. 445 // 446 // The 8-bit version requires UTF-8 encoding. 447 URL_EXPORT bool FileCanonicalizePath(const char* spec, 448 const url_parse::Component& path, 449 CanonOutput* output, 450 url_parse::Component* out_path); 451 URL_EXPORT bool FileCanonicalizePath(const base::char16* spec, 452 const url_parse::Component& path, 453 CanonOutput* output, 454 url_parse::Component* out_path); 455 456 // Query: Prepends the ? if needed. 457 // 458 // The 8-bit version requires the input to be UTF-8 encoding. Incorrectly 459 // encoded characters (in UTF-8 or UTF-16) will be replaced with the Unicode 460 // "invalid character." This function can not fail, we always just try to do 461 // our best for crazy input here since web pages can set it themselves. 462 // 463 // This will convert the given input into the output encoding that the given 464 // character set converter object provides. The converter will only be called 465 // if necessary, for ASCII input, no conversions are necessary. 466 // 467 // The converter can be NULL. In this case, the output encoding will be UTF-8. 468 URL_EXPORT void CanonicalizeQuery(const char* spec, 469 const url_parse::Component& query, 470 CharsetConverter* converter, 471 CanonOutput* output, 472 url_parse::Component* out_query); 473 URL_EXPORT void CanonicalizeQuery(const base::char16* spec, 474 const url_parse::Component& query, 475 CharsetConverter* converter, 476 CanonOutput* output, 477 url_parse::Component* out_query); 478 479 // Ref: Prepends the # if needed. The output will be UTF-8 (this is the only 480 // canonicalizer that does not produce ASCII output). The output is 481 // guaranteed to be valid UTF-8. 482 // 483 // This function will not fail. If the input is invalid UTF-8/UTF-16, we'll use 484 // the "Unicode replacement character" for the confusing bits and copy the rest. 485 URL_EXPORT void CanonicalizeRef(const char* spec, 486 const url_parse::Component& path, 487 CanonOutput* output, 488 url_parse::Component* out_path); 489 URL_EXPORT void CanonicalizeRef(const base::char16* spec, 490 const url_parse::Component& path, 491 CanonOutput* output, 492 url_parse::Component* out_path); 493 494 // Full canonicalizer --------------------------------------------------------- 495 // 496 // These functions replace any string contents, rather than append as above. 497 // See the above piece-by-piece functions for information specific to 498 // canonicalizing individual components. 499 // 500 // The output will be ASCII except the reference fragment, which may be UTF-8. 501 // 502 // The 8-bit versions require UTF-8 encoding. 503 504 // Use for standard URLs with authorities and paths. 505 URL_EXPORT bool CanonicalizeStandardURL(const char* spec, 506 int spec_len, 507 const url_parse::Parsed& parsed, 508 CharsetConverter* query_converter, 509 CanonOutput* output, 510 url_parse::Parsed* new_parsed); 511 URL_EXPORT bool CanonicalizeStandardURL(const base::char16* spec, 512 int spec_len, 513 const url_parse::Parsed& parsed, 514 CharsetConverter* query_converter, 515 CanonOutput* output, 516 url_parse::Parsed* new_parsed); 517 518 // Use for file URLs. 519 URL_EXPORT bool CanonicalizeFileURL(const char* spec, 520 int spec_len, 521 const url_parse::Parsed& parsed, 522 CharsetConverter* query_converter, 523 CanonOutput* output, 524 url_parse::Parsed* new_parsed); 525 URL_EXPORT bool CanonicalizeFileURL(const base::char16* spec, 526 int spec_len, 527 const url_parse::Parsed& parsed, 528 CharsetConverter* query_converter, 529 CanonOutput* output, 530 url_parse::Parsed* new_parsed); 531 532 // Use for filesystem URLs. 533 URL_EXPORT bool CanonicalizeFileSystemURL(const char* spec, 534 int spec_len, 535 const url_parse::Parsed& parsed, 536 CharsetConverter* query_converter, 537 CanonOutput* output, 538 url_parse::Parsed* new_parsed); 539 URL_EXPORT bool CanonicalizeFileSystemURL(const base::char16* spec, 540 int spec_len, 541 const url_parse::Parsed& parsed, 542 CharsetConverter* query_converter, 543 CanonOutput* output, 544 url_parse::Parsed* new_parsed); 545 546 // Use for path URLs such as javascript. This does not modify the path in any 547 // way, for example, by escaping it. 548 URL_EXPORT bool CanonicalizePathURL(const char* spec, 549 int spec_len, 550 const url_parse::Parsed& parsed, 551 CanonOutput* output, 552 url_parse::Parsed* new_parsed); 553 URL_EXPORT bool CanonicalizePathURL(const base::char16* spec, 554 int spec_len, 555 const url_parse::Parsed& parsed, 556 CanonOutput* output, 557 url_parse::Parsed* new_parsed); 558 559 // Use for mailto URLs. This "canonicalizes" the url into a path and query 560 // component. It does not attempt to merge "to" fields. It uses UTF-8 for 561 // the query encoding if there is a query. This is because a mailto URL is 562 // really intended for an external mail program, and the encoding of a page, 563 // etc. which would influence a query encoding normally are irrelevant. 564 URL_EXPORT bool CanonicalizeMailtoURL(const char* spec, 565 int spec_len, 566 const url_parse::Parsed& parsed, 567 CanonOutput* output, 568 url_parse::Parsed* new_parsed); 569 URL_EXPORT bool CanonicalizeMailtoURL(const base::char16* spec, 570 int spec_len, 571 const url_parse::Parsed& parsed, 572 CanonOutput* output, 573 url_parse::Parsed* new_parsed); 574 575 // Part replacer -------------------------------------------------------------- 576 577 // Internal structure used for storing separate strings for each component. 578 // The basic canonicalization functions use this structure internally so that 579 // component replacement (different strings for different components) can be 580 // treated on the same code path as regular canonicalization (the same string 581 // for each component). 582 // 583 // A url_parse::Parsed structure usually goes along with this. Those 584 // components identify offsets within these strings, so that they can all be 585 // in the same string, or spread arbitrarily across different ones. 586 // 587 // This structures does not own any data. It is the caller's responsibility to 588 // ensure that the data the pointers point to stays in scope and is not 589 // modified. 590 template<typename CHAR> 591 struct URLComponentSource { 592 // Constructor normally used by callers wishing to replace components. This 593 // will make them all NULL, which is no replacement. The caller would then 594 // override the components they want to replace. 595 URLComponentSource() 596 : scheme(NULL), 597 username(NULL), 598 password(NULL), 599 host(NULL), 600 port(NULL), 601 path(NULL), 602 query(NULL), 603 ref(NULL) { 604 } 605 606 // Constructor normally used internally to initialize all the components to 607 // point to the same spec. 608 explicit URLComponentSource(const CHAR* default_value) 609 : scheme(default_value), 610 username(default_value), 611 password(default_value), 612 host(default_value), 613 port(default_value), 614 path(default_value), 615 query(default_value), 616 ref(default_value) { 617 } 618 619 const CHAR* scheme; 620 const CHAR* username; 621 const CHAR* password; 622 const CHAR* host; 623 const CHAR* port; 624 const CHAR* path; 625 const CHAR* query; 626 const CHAR* ref; 627 }; 628 629 // This structure encapsulates information on modifying a URL. Each component 630 // may either be left unchanged, replaced, or deleted. 631 // 632 // By default, each component is unchanged. For those components that should be 633 // modified, call either Set* or Clear* to modify it. 634 // 635 // The string passed to Set* functions DOES NOT GET COPIED AND MUST BE KEPT 636 // IN SCOPE BY THE CALLER for as long as this object exists! 637 // 638 // Prefer the 8-bit replacement version if possible since it is more efficient. 639 template<typename CHAR> 640 class Replacements { 641 public: 642 Replacements() { 643 } 644 645 // Scheme 646 void SetScheme(const CHAR* s, const url_parse::Component& comp) { 647 sources_.scheme = s; 648 components_.scheme = comp; 649 } 650 // Note: we don't have a ClearScheme since this doesn't make any sense. 651 bool IsSchemeOverridden() const { return sources_.scheme != NULL; } 652 653 // Username 654 void SetUsername(const CHAR* s, const url_parse::Component& comp) { 655 sources_.username = s; 656 components_.username = comp; 657 } 658 void ClearUsername() { 659 sources_.username = Placeholder(); 660 components_.username = url_parse::Component(); 661 } 662 bool IsUsernameOverridden() const { return sources_.username != NULL; } 663 664 // Password 665 void SetPassword(const CHAR* s, const url_parse::Component& comp) { 666 sources_.password = s; 667 components_.password = comp; 668 } 669 void ClearPassword() { 670 sources_.password = Placeholder(); 671 components_.password = url_parse::Component(); 672 } 673 bool IsPasswordOverridden() const { return sources_.password != NULL; } 674 675 // Host 676 void SetHost(const CHAR* s, const url_parse::Component& comp) { 677 sources_.host = s; 678 components_.host = comp; 679 } 680 void ClearHost() { 681 sources_.host = Placeholder(); 682 components_.host = url_parse::Component(); 683 } 684 bool IsHostOverridden() const { return sources_.host != NULL; } 685 686 // Port 687 void SetPort(const CHAR* s, const url_parse::Component& comp) { 688 sources_.port = s; 689 components_.port = comp; 690 } 691 void ClearPort() { 692 sources_.port = Placeholder(); 693 components_.port = url_parse::Component(); 694 } 695 bool IsPortOverridden() const { return sources_.port != NULL; } 696 697 // Path 698 void SetPath(const CHAR* s, const url_parse::Component& comp) { 699 sources_.path = s; 700 components_.path = comp; 701 } 702 void ClearPath() { 703 sources_.path = Placeholder(); 704 components_.path = url_parse::Component(); 705 } 706 bool IsPathOverridden() const { return sources_.path != NULL; } 707 708 // Query 709 void SetQuery(const CHAR* s, const url_parse::Component& comp) { 710 sources_.query = s; 711 components_.query = comp; 712 } 713 void ClearQuery() { 714 sources_.query = Placeholder(); 715 components_.query = url_parse::Component(); 716 } 717 bool IsQueryOverridden() const { return sources_.query != NULL; } 718 719 // Ref 720 void SetRef(const CHAR* s, const url_parse::Component& comp) { 721 sources_.ref = s; 722 components_.ref = comp; 723 } 724 void ClearRef() { 725 sources_.ref = Placeholder(); 726 components_.ref = url_parse::Component(); 727 } 728 bool IsRefOverridden() const { return sources_.ref != NULL; } 729 730 // Getters for the itnernal data. See the variables below for how the 731 // information is encoded. 732 const URLComponentSource<CHAR>& sources() const { return sources_; } 733 const url_parse::Parsed& components() const { return components_; } 734 735 private: 736 // Returns a pointer to a static empty string that is used as a placeholder 737 // to indicate a component should be deleted (see below). 738 const CHAR* Placeholder() { 739 static const CHAR empty_string = 0; 740 return &empty_string; 741 } 742 743 // We support three states: 744 // 745 // Action | Source Component 746 // -----------------------+-------------------------------------------------- 747 // Don't change component | NULL (unused) 748 // Replace component | (replacement string) (replacement component) 749 // Delete component | (non-NULL) (invalid component: (0,-1)) 750 // 751 // We use a pointer to the empty string for the source when the component 752 // should be deleted. 753 URLComponentSource<CHAR> sources_; 754 url_parse::Parsed components_; 755 }; 756 757 // The base must be an 8-bit canonical URL. 758 URL_EXPORT bool ReplaceStandardURL(const char* base, 759 const url_parse::Parsed& base_parsed, 760 const Replacements<char>& replacements, 761 CharsetConverter* query_converter, 762 CanonOutput* output, 763 url_parse::Parsed* new_parsed); 764 URL_EXPORT bool ReplaceStandardURL( 765 const char* base, 766 const url_parse::Parsed& base_parsed, 767 const Replacements<base::char16>& replacements, 768 CharsetConverter* query_converter, 769 CanonOutput* output, 770 url_parse::Parsed* new_parsed); 771 772 // Filesystem URLs can only have the path, query, or ref replaced. 773 // All other components will be ignored. 774 URL_EXPORT bool ReplaceFileSystemURL(const char* base, 775 const url_parse::Parsed& base_parsed, 776 const Replacements<char>& replacements, 777 CharsetConverter* query_converter, 778 CanonOutput* output, 779 url_parse::Parsed* new_parsed); 780 URL_EXPORT bool ReplaceFileSystemURL( 781 const char* base, 782 const url_parse::Parsed& base_parsed, 783 const Replacements<base::char16>& replacements, 784 CharsetConverter* query_converter, 785 CanonOutput* output, 786 url_parse::Parsed* new_parsed); 787 788 // Replacing some parts of a file URL is not permitted. Everything except 789 // the host, path, query, and ref will be ignored. 790 URL_EXPORT bool ReplaceFileURL(const char* base, 791 const url_parse::Parsed& base_parsed, 792 const Replacements<char>& replacements, 793 CharsetConverter* query_converter, 794 CanonOutput* output, 795 url_parse::Parsed* new_parsed); 796 URL_EXPORT bool ReplaceFileURL(const char* base, 797 const url_parse::Parsed& base_parsed, 798 const Replacements<base::char16>& replacements, 799 CharsetConverter* query_converter, 800 CanonOutput* output, 801 url_parse::Parsed* new_parsed); 802 803 // Path URLs can only have the scheme and path replaced. All other components 804 // will be ignored. 805 URL_EXPORT bool ReplacePathURL(const char* base, 806 const url_parse::Parsed& base_parsed, 807 const Replacements<char>& replacements, 808 CanonOutput* output, 809 url_parse::Parsed* new_parsed); 810 URL_EXPORT bool ReplacePathURL(const char* base, 811 const url_parse::Parsed& base_parsed, 812 const Replacements<base::char16>& replacements, 813 CanonOutput* output, 814 url_parse::Parsed* new_parsed); 815 816 // Mailto URLs can only have the scheme, path, and query replaced. 817 // All other components will be ignored. 818 URL_EXPORT bool ReplaceMailtoURL(const char* base, 819 const url_parse::Parsed& base_parsed, 820 const Replacements<char>& replacements, 821 CanonOutput* output, 822 url_parse::Parsed* new_parsed); 823 URL_EXPORT bool ReplaceMailtoURL(const char* base, 824 const url_parse::Parsed& base_parsed, 825 const Replacements<base::char16>& replacements, 826 CanonOutput* output, 827 url_parse::Parsed* new_parsed); 828 829 // Relative URL --------------------------------------------------------------- 830 831 // Given an input URL or URL fragment |fragment|, determines if it is a 832 // relative or absolute URL and places the result into |*is_relative|. If it is 833 // relative, the relevant portion of the URL will be placed into 834 // |*relative_component| (there may have been trimmed whitespace, for example). 835 // This value is passed to ResolveRelativeURL. If the input is not relative, 836 // this value is UNDEFINED (it may be changed by the function). 837 // 838 // Returns true on success (we successfully determined the URL is relative or 839 // not). Failure means that the combination of URLs doesn't make any sense. 840 // 841 // The base URL should always be canonical, therefore is ASCII. 842 URL_EXPORT bool IsRelativeURL(const char* base, 843 const url_parse::Parsed& base_parsed, 844 const char* fragment, 845 int fragment_len, 846 bool is_base_hierarchical, 847 bool* is_relative, 848 url_parse::Component* relative_component); 849 URL_EXPORT bool IsRelativeURL(const char* base, 850 const url_parse::Parsed& base_parsed, 851 const base::char16* fragment, 852 int fragment_len, 853 bool is_base_hierarchical, 854 bool* is_relative, 855 url_parse::Component* relative_component); 856 857 // Given a canonical parsed source URL, a URL fragment known to be relative, 858 // and the identified relevant portion of the relative URL (computed by 859 // IsRelativeURL), this produces a new parsed canonical URL in |output| and 860 // |out_parsed|. 861 // 862 // It also requires a flag indicating whether the base URL is a file: URL 863 // which triggers additional logic. 864 // 865 // The base URL should be canonical and have a host (may be empty for file 866 // URLs) and a path. If it doesn't have these, we can't resolve relative 867 // URLs off of it and will return the base as the output with an error flag. 868 // Becausee it is canonical is should also be ASCII. 869 // 870 // The query charset converter follows the same rules as CanonicalizeQuery. 871 // 872 // Returns true on success. On failure, the output will be "something 873 // reasonable" that will be consistent and valid, just probably not what 874 // was intended by the web page author or caller. 875 URL_EXPORT bool ResolveRelativeURL( 876 const char* base_url, 877 const url_parse::Parsed& base_parsed, 878 bool base_is_file, 879 const char* relative_url, 880 const url_parse::Component& relative_component, 881 CharsetConverter* query_converter, 882 CanonOutput* output, 883 url_parse::Parsed* out_parsed); 884 URL_EXPORT bool ResolveRelativeURL( 885 const char* base_url, 886 const url_parse::Parsed& base_parsed, 887 bool base_is_file, 888 const base::char16* relative_url, 889 const url_parse::Component& relative_component, 890 CharsetConverter* query_converter, 891 CanonOutput* output, 892 url_parse::Parsed* out_parsed); 893 894 } // namespace url_canon 895 896 #endif // URL_URL_CANON_H_ 897
