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_UTIL_H_ 6#define URL_URL_UTIL_H_ 7 8#include <string> 9 10#include "base/strings/string16.h" 11#include "url/url_canon.h" 12#include "url/url_constants.h" 13#include "url/url_export.h" 14#include "url/url_parse.h" 15 16namespace url { 17 18// Init ------------------------------------------------------------------------ 19 20// Initialization is NOT required, it will be implicitly initialized when first 21// used. However, this implicit initialization is NOT threadsafe. If you are 22// using this library in a threaded environment and don't have a consistent 23// "first call" (an example might be calling "AddStandardScheme" with your 24// special application-specific schemes) then you will want to call initialize 25// before spawning any threads. 26// 27// It is OK to call this function more than once, subsequent calls will simply 28// "noop", unless Shutdown() was called in the mean time. This will also be a 29// "noop" if other calls to the library have forced an initialization 30// beforehand. 31URL_EXPORT void Initialize(); 32 33// Cleanup is not required, except some strings may leak. For most user 34// applications, this is fine. If you're using it in a library that may get 35// loaded and unloaded, you'll want to unload to properly clean up your 36// library. 37URL_EXPORT void Shutdown(); 38 39// Schemes -------------------------------------------------------------------- 40 41// Adds an application-defined scheme to the internal list of "standard" URL 42// schemes. This function is not threadsafe and can not be called concurrently 43// with any other url_util function. It will assert if the list of standard 44// schemes has been locked (see LockStandardSchemes). 45URL_EXPORT void AddStandardScheme(const char* new_scheme); 46 47// Sets a flag to prevent future calls to AddStandardScheme from succeeding. 48// 49// This is designed to help prevent errors for multithreaded applications. 50// Normal usage would be to call AddStandardScheme for your custom schemes at 51// the beginning of program initialization, and then LockStandardSchemes. This 52// prevents future callers from mistakenly calling AddStandardScheme when the 53// program is running with multiple threads, where such usage would be 54// dangerous. 55// 56// We could have had AddStandardScheme use a lock instead, but that would add 57// some platform-specific dependencies we don't otherwise have now, and is 58// overkill considering the normal usage is so simple. 59URL_EXPORT void LockStandardSchemes(); 60 61// Locates the scheme in the given string and places it into |found_scheme|, 62// which may be NULL to indicate the caller does not care about the range. 63// 64// Returns whether the given |compare| scheme matches the scheme found in the 65// input (if any). The |compare| scheme must be a valid canonical scheme or 66// the result of the comparison is undefined. 67URL_EXPORT bool FindAndCompareScheme(const char* str, 68 int str_len, 69 const char* compare, 70 Component* found_scheme); 71URL_EXPORT bool FindAndCompareScheme(const base::char16* str, 72 int str_len, 73 const char* compare, 74 Component* found_scheme); 75inline bool FindAndCompareScheme(const std::string& str, 76 const char* compare, 77 Component* found_scheme) { 78 return FindAndCompareScheme(str.data(), static_cast<int>(str.size()), 79 compare, found_scheme); 80} 81inline bool FindAndCompareScheme(const base::string16& str, 82 const char* compare, 83 Component* found_scheme) { 84 return FindAndCompareScheme(str.data(), static_cast<int>(str.size()), 85 compare, found_scheme); 86} 87 88// Returns true if the given string represents a standard URL. This means that 89// either the scheme is in the list of known standard schemes. 90URL_EXPORT bool IsStandard(const char* spec, const Component& scheme); 91URL_EXPORT bool IsStandard(const base::char16* spec, const Component& scheme); 92 93// TODO(brettw) remove this. This is a temporary compatibility hack to avoid 94// breaking the WebKit build when this version is synced via Chrome. 95inline bool IsStandard(const char* spec, 96 int spec_len, 97 const Component& scheme) { 98 return IsStandard(spec, scheme); 99} 100 101// URL library wrappers ------------------------------------------------------- 102 103// Parses the given spec according to the extracted scheme type. Normal users 104// should use the URL object, although this may be useful if performance is 105// critical and you don't want to do the heap allocation for the std::string. 106// 107// As with the Canonicalize* functions, the charset converter can 108// be NULL to use UTF-8 (it will be faster in this case). 109// 110// Returns true if a valid URL was produced, false if not. On failure, the 111// output and parsed structures will still be filled and will be consistent, 112// but they will not represent a loadable URL. 113URL_EXPORT bool Canonicalize(const char* spec, 114 int spec_len, 115 bool trim_path_end, 116 CharsetConverter* charset_converter, 117 CanonOutput* output, 118 Parsed* output_parsed); 119URL_EXPORT bool Canonicalize(const base::char16* spec, 120 int spec_len, 121 bool trim_path_end, 122 CharsetConverter* charset_converter, 123 CanonOutput* output, 124 Parsed* output_parsed); 125 126// Resolves a potentially relative URL relative to the given parsed base URL. 127// The base MUST be valid. The resulting canonical URL and parsed information 128// will be placed in to the given out variables. 129// 130// The relative need not be relative. If we discover that it's absolute, this 131// will produce a canonical version of that URL. See Canonicalize() for more 132// about the charset_converter. 133// 134// Returns true if the output is valid, false if the input could not produce 135// a valid URL. 136URL_EXPORT bool ResolveRelative(const char* base_spec, 137 int base_spec_len, 138 const Parsed& base_parsed, 139 const char* relative, 140 int relative_length, 141 CharsetConverter* charset_converter, 142 CanonOutput* output, 143 Parsed* output_parsed); 144URL_EXPORT bool ResolveRelative(const char* base_spec, 145 int base_spec_len, 146 const Parsed& base_parsed, 147 const base::char16* relative, 148 int relative_length, 149 CharsetConverter* charset_converter, 150 CanonOutput* output, 151 Parsed* output_parsed); 152 153// Replaces components in the given VALID input url. The new canonical URL info 154// is written to output and out_parsed. 155// 156// Returns true if the resulting URL is valid. 157URL_EXPORT bool ReplaceComponents(const char* spec, 158 int spec_len, 159 const Parsed& parsed, 160 const Replacements<char>& replacements, 161 CharsetConverter* charset_converter, 162 CanonOutput* output, 163 Parsed* out_parsed); 164URL_EXPORT bool ReplaceComponents( 165 const char* spec, 166 int spec_len, 167 const Parsed& parsed, 168 const Replacements<base::char16>& replacements, 169 CharsetConverter* charset_converter, 170 CanonOutput* output, 171 Parsed* out_parsed); 172 173// String helper functions ---------------------------------------------------- 174 175// Compare the lower-case form of the given string against the given ASCII 176// string. This is useful for doing checking if an input string matches some 177// token, and it is optimized to avoid intermediate string copies. 178// 179// The versions of this function that don't take a b_end assume that the b 180// string is NULL terminated. 181URL_EXPORT bool LowerCaseEqualsASCII(const char* a_begin, 182 const char* a_end, 183 const char* b); 184URL_EXPORT bool LowerCaseEqualsASCII(const char* a_begin, 185 const char* a_end, 186 const char* b_begin, 187 const char* b_end); 188URL_EXPORT bool LowerCaseEqualsASCII(const base::char16* a_begin, 189 const base::char16* a_end, 190 const char* b); 191 192// Unescapes the given string using URL escaping rules. 193URL_EXPORT void DecodeURLEscapeSequences(const char* input, 194 int length, 195 CanonOutputW* output); 196 197// Escapes the given string as defined by the JS method encodeURIComponent. See 198// https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/encodeURIComponent 199URL_EXPORT void EncodeURIComponent(const char* input, 200 int length, 201 CanonOutput* output); 202 203} // namespace url 204 205#endif // URL_URL_UTIL_H_ 206