net/base/escape.h

   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 // &lt; &gt; &amp; &quot; &#39;
 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_