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