1 // Copyright (c) 2009 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 NET_BASE_ESCAPE_H_ 6 #define NET_BASE_ESCAPE_H_ 7 8 #include <string> 9 10 #include "base/basictypes.h" 11 #include "base/string16.h" 12 13 // Escaping -------------------------------------------------------------------- 14 15 // Escape a file. This includes: 16 // non-printable, non-7bit, and (including space) "#%:<>?[\]^`{|} 17 std::string EscapePath(const std::string& path); 18 19 // Escape application/x-www-form-urlencoded content. This includes: 20 // non-printable, non-7bit, and (including space) ?>=<;+'&%$#"![\]^`{|} 21 // Space is escaped as + and other special characters as %XX (hex). 22 std::string EscapeUrlEncodedData(const std::string& path); 23 24 // Escape all non-ASCII input. 25 std::string EscapeNonASCII(const std::string& input); 26 27 // Escapes characters in text suitable for use as an external protocol handler 28 // command. 29 // We %XX everything except alphanumerics and %-_.!~*'() and the restricted 30 // chracters (;/?:@&=+$,). 31 std::string EscapeExternalHandlerValue(const std::string& text); 32 33 // Append the given character to the output string, escaping the character if 34 // the character would be interpretted as an HTML delimiter. 35 void AppendEscapedCharForHTML(char c, std::string* output); 36 37 // Escape chars that might cause this text to be interpretted as HTML tags. 38 std::string EscapeForHTML(const std::string& text); 39 string16 EscapeForHTML(const string16& text); 40 41 // Unescaping ------------------------------------------------------------------ 42 43 class UnescapeRule { 44 public: 45 // A combination of the following flags that is passed to the unescaping 46 // functions. 47 typedef uint32 Type; 48 49 enum { 50 // Don't unescape anything at all. 51 NONE = 0, 52 53 // Don't unescape anything special, but all normal unescaping will happen. 54 // This is a placeholder and can't be combined with other flags (since it's 55 // just the absence of them). All other unescape rules imply "normal" in 56 // addition to their special meaning. Things like escaped letters, digits, 57 // and most symbols will get unescaped with this mode. 58 NORMAL = 1, 59 60 // Convert %20 to spaces. In some places where we're showing URLs, we may 61 // want this. In places where the URL may be copied and pasted out, then 62 // you wouldn't want this since it might not be interpreted in one piece 63 // by other applications. 64 SPACES = 2, 65 66 // Unescapes various characters that will change the meaning of URLs, 67 // including '%', '+', '&', '/', '#'. If we unescaped these characters, the 68 // resulting URL won't be the same as the source one. This flag is used when 69 // generating final output like filenames for URLs where we won't be 70 // interpreting as a URL and want to do as much unescaping as possible. 71 URL_SPECIAL_CHARS = 4, 72 73 // Unescapes control characters such as %01. This INCLUDES NULLs. This is 74 // used for rare cases such as data: URL decoding where the result is binary 75 // data. You should not use this for normal URLs! 76 CONTROL_CHARS = 8, 77 78 // URL queries use "+" for space. This flag controls that replacement. 79 REPLACE_PLUS_WITH_SPACE = 16, 80 }; 81 }; 82 83 // Unescapes |escaped_text| and returns the result. 84 // Unescaping consists of looking for the exact pattern "%XX", where each X is 85 // a hex digit, and converting to the character with the numerical value of 86 // those digits. Thus "i%20=%203%3b" unescapes to "i = 3;". 87 // 88 // Watch out: this doesn't necessarily result in the correct final result, 89 // because the encoding may be unknown. For example, the input might be ASCII, 90 // which, after unescaping, is supposed to be interpreted as UTF-8, and then 91 // converted into full wide chars. This function won't tell you if any 92 // conversions need to take place, it only unescapes. 93 std::string UnescapeURLComponent(const std::string& escaped_text, 94 UnescapeRule::Type rules); 95 string16 UnescapeURLComponent(const string16& escaped_text, 96 UnescapeRule::Type rules); 97 98 // Unescapes the given substring as a URL, and then tries to interpret the 99 // result as being encoded as UTF-8. If the result is convertable into UTF-8, it 100 // will be returned as converted. If it is not, the original escaped string will 101 // be converted into a string16 and returned. 102 // 103 // |offset_for_adjustment| may be NULL; if not, it is an offset into |text| that 104 // will be adjusted to point at the same logical place in the result string. If 105 // this isn't possible because it points into the middle of an escape sequence 106 // or past the end of the string, it will be set to string16::npos. 107 string16 UnescapeAndDecodeUTF8URLComponent(const std::string& text, 108 UnescapeRule::Type rules, 109 size_t* offset_for_adjustment); 110 111 // Unescape the following ampersand character codes from |text|: 112 // < > & " ' 113 string16 UnescapeForHTML(const string16& text); 114 115 // Deprecated ------------------------------------------------------------------ 116 117 // Escapes characters in text suitable for use as a query parameter value. 118 // We %XX everything except alphanumerics and -_.!~*'() 119 // Spaces change to "+" unless you pass usePlus=false. 120 // This is basically the same as encodeURIComponent in javascript. 121 // For the string16 version, we do a conversion to charset before encoding the 122 // string. If the charset doesn't exist, we return false. 123 // 124 // TODO(brettw) bug 1201094: This function should be removed. See the bug for 125 // why and what callers should do instead. 126 std::string EscapeQueryParamValue(const std::string& text, bool use_plus); 127 bool EscapeQueryParamValue(const string16& text, const char* codepage, 128 bool use_plus, string16* escaped); 129 130 // A specialized version of EscapeQueryParamValue for wide strings that 131 // assumes the codepage is UTF8. This is provided as a convenience. 132 // 133 // TODO(brettw) bug 1201094: This function should be removed. See the bug for 134 // why and what callers should do instead. 135 std::wstring EscapeQueryParamValueUTF8(const std::wstring& text, bool use_plus); 136 137 #endif // NET_BASE_ESCAPE_H_ 138
