xpcom/io/nsEscape.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 /*      First checked in on 98/12/03 by John R. McMullen, derived from
   8  * net.h/mkparse.c. */
   9
  10 #ifndef _ESCAPE_H_
  11 #define _ESCAPE_H_
  12
  13 #include "nscore.h"
  14 #include "nsError.h"
  15 #include "nsString.h"
  16 #include <functional>
  17
  18 /**
  19  * Valid mask values for nsEscape
  20  * Note: these values are copied in nsINetUtil.idl. Any changes should be kept
  21  * in sync.
  22  */
  23 typedef enum {
  24   url_All = 0,  // %-escape every byte unconditionally
  25   url_XAlphas =
  26       1u << 0,  // Normal escape - leave alphas intact, escape the rest
  27   url_XPAlphas =
  28       1u
  29       << 1,  // As url_XAlphas, but convert spaces (0x20) to '+' and plus to %2B
  30   url_Path = 1u << 2,     // As url_XAlphas, but don't escape slash ('/')
  31   url_NSURLRef = 1u << 3  // Extra URL ref encoding required for Apple's
  32                           // NSURL compatibility
  33 } nsEscapeMask;
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 /**
  40  * Escape the given string according to mask
  41  * @param aSstr The string to escape
  42  * @param aLength The length of the string to escape
  43  * @param aOutputLen A pointer that will be used to store the length of the
  44  *        output string, if not null
  45  * @param aMask How to escape the string
  46  * @return A newly allocated escaped string that must be free'd with
  47  *         nsCRT::free, or null on failure
  48  * @note: Please, don't use this function. Use NS_Escape instead!
  49  */
  50 char* nsEscape(const char* aStr, size_t aLength, size_t* aOutputLen,
  51                nsEscapeMask aMask);
  52
  53 /**
  54  * Decodes '%'-escaped hex codes into character values, modifies the parameter,
  55  * returns the same buffer
  56  */
  57 char* nsUnescape(char* aStr);
  58
  59 /**
  60  * Decodes '%'-escaped hex codes into character values, modifies the parameter
  61  * buffer, returns the length of the result (result may contain \0's).
  62  */
  63 int32_t nsUnescapeCount(char* aStr);
  64
  65 #ifdef __cplusplus
  66 }
  67 #endif
  68
  69 /**
  70  * Infallibly append aSrc to aDst, escaping chars that are problematic for HTML
  71  * display.
  72  */
  73 void nsAppendEscapedHTML(const nsACString& aSrc, nsACString& aDst);
  74
  75 /**
  76  * NS_EscapeURL/NS_UnescapeURL constants for |flags| parameter:
  77  *
  78  * Note: These values are copied to nsINetUtil.idl
  79  *       Any changes should be kept in sync
  80  */
  81 enum EscapeMask {
  82   /** url components **/
  83   esc_Scheme = 1u << 0,
  84   esc_Username = 1u << 1,
  85   esc_Password = 1u << 2,
  86   esc_Host = 1u << 3,
  87   esc_Directory = 1u << 4,
  88   esc_FileBaseName = 1u << 5,
  89   esc_FileExtension = 1u << 6,
  90   esc_FilePath = esc_Directory | esc_FileBaseName | esc_FileExtension,
  91   esc_Param = 1u << 7,
  92   esc_Query = 1u << 8,
  93   esc_Ref = 1u << 9,
  94   /** special flags **/
  95   esc_Minimal = esc_Scheme | esc_Username | esc_Password | esc_Host |
  96                 esc_FilePath | esc_Param | esc_Query | esc_Ref,
  97   esc_Forced = 1u << 10,    /* forces escaping of existing escape sequences */
  98   esc_OnlyASCII = 1u << 11, /* causes non-ascii octets to be skipped */
  99   esc_OnlyNonASCII =
 100       1u << 12, /* causes _graphic_ ascii octets (0x20-0x7E)
 101                  * to be skipped when escaping. causes all
 102                  * ascii octets (<= 0x7F) to be skipped when unescaping */
 103   esc_AlwaysCopy =
 104       1u << 13, /* copy input to result buf even if escaping is unnecessary */
 105   esc_Colon = 1u << 14,       /* forces escape of colon */
 106   esc_SkipControl = 1u << 15, /* skips C0 and DEL from unescaping */
 107   esc_Spaces = 1u << 16,      /* forces escape of spaces */
 108   esc_ExtHandler = 1u << 17   /* For escaping external protocol handler urls.
 109                                * Escapes everything except:
 110                                * a-z, 0-9 and !#$&'()*+,-./:;=?@[]_~ */
 111 };
 112
 113 /**
 114  * NS_EscapeURL
 115  *
 116  * Escapes invalid char's in an URL segment.  Has no side-effect if the URL
 117  * segment is already escaped, unless aFlags has the esc_Forced bit in which
 118  * case % will also be escaped.  Iff some part of aStr is escaped is the
 119  * final result appended to aResult.  You can also request that aStr is
 120  * always appended to aResult with esc_AlwaysCopy.
 121  *
 122  * @param aStr     url segment string
 123  * @param aLen     url segment string length (-1 if unknown)
 124  * @param aFlags   url segment type flag (see EscapeMask above)
 125  * @param aResult  result buffer, untouched if aStr is already escaped unless
 126  *                 aFlags has esc_AlwaysCopy
 127  *
 128  * @return true if aResult was written to (i.e. at least one character was
 129  *              escaped or esc_AlwaysCopy was requested), false otherwise.
 130  */
 131 bool NS_EscapeURL(const char* aStr, int32_t aLen, uint32_t aFlags,
 132                   nsACString& aResult);
 133
 134 bool NS_EscapeURLSpan(mozilla::Span<const char> aStr, uint32_t aFlags,
 135                       nsACString& aResult);
 136
 137 /**
 138  * Expands URL escape sequences... beware embedded null bytes!
 139  *
 140  * @param aStr     url string to unescape
 141  * @param aLen     length of aStr
 142  * @param aFlags   only esc_OnlyNonASCII, esc_SkipControl and esc_AlwaysCopy
 143  *                 are recognized
 144  * @param aResult  result buffer, untouched if aStr is already unescaped unless
 145  *                 aFlags has esc_AlwaysCopy
 146  *
 147  * @return true if aResult was written to (i.e. at least one character was
 148  *              unescaped or esc_AlwaysCopy was requested), false otherwise.
 149  */
 150 bool NS_UnescapeURL(const char* aStr, int32_t aLen, uint32_t aFlags,
 151                     nsACString& aResult);
 152
 153 /**
 154  * Fallible version of |NS_UnescapeURL|. See above for details.
 155  *
 156  * @param aAppended Out param: true if aResult was written to (i.e. at least
 157  *                  one character was unescaped or esc_AlwaysCopy was
 158  *                  requested), false otherwise.
 159  */
 160 nsresult NS_UnescapeURL(const char* aStr, int32_t aLen, uint32_t aFlags,
 161                         nsACString& aResult, bool& aAppended,
 162                         const mozilla::fallible_t&);
 163
 164 /** returns resultant string length **/
 165 inline int32_t NS_UnescapeURL(char* aStr) { return nsUnescapeCount(aStr); }
 166
 167 /**
 168  * String friendly versions...
 169  */
 170 inline const nsACString& NS_EscapeURL(const nsACString& aStr, uint32_t aFlags,
 171                                       nsACString& aResult) {
 172   if (NS_EscapeURLSpan(aStr, aFlags, aResult)) {
 173     return aResult;
 174   }
 175   return aStr;
 176 }
 177
 178 /**
 179  * Fallible version of NS_EscapeURL. On success aResult will point to either
 180  * the original string or an escaped copy.
 181  */
 182 nsresult NS_EscapeURL(const nsACString& aStr, uint32_t aFlags,
 183                       nsACString& aResult, const mozilla::fallible_t&);
 184
 185 // Forward declaration for nsASCIIMask.h
 186 typedef std::array<bool, 128> ASCIIMaskArray;
 187
 188 /**
 189  * The same as NS_EscapeURL, except it also filters out characters that match
 190  * aFilterMask.
 191  */
 192 nsresult NS_EscapeAndFilterURL(const nsACString& aStr, uint32_t aFlags,
 193                                const ASCIIMaskArray* aFilterMask,
 194                                nsACString& aResult, const mozilla::fallible_t&);
 195
 196 inline const nsACString& NS_UnescapeURL(const nsACString& aStr, uint32_t aFlags,
 197                                         nsACString& aResult) {
 198   if (NS_UnescapeURL(aStr.Data(), aStr.Length(), aFlags, aResult)) {
 199     return aResult;
 200   }
 201   return aStr;
 202 }
 203
 204 const nsAString& NS_EscapeURL(const nsAString& aStr, uint32_t aFlags,
 205                               nsAString& aResult);
 206
 207 /**
 208  * Percent-escapes all characters in aStr that occurs in aForbidden.
 209  * @param aStr the input URL string
 210  * @param aFunction returns true for characters that should be escaped
 211  * @param aResult the result if some characters were escaped
 212  * @return aResult if some characters were escaped, or aStr otherwise (aResult
 213  *         is unmodified in that case)
 214  */
 215 const nsAString& NS_EscapeURL(const nsString& aStr,
 216                               const std::function<bool(char16_t)>& aFunction,
 217                               nsAString& aResult);
 218
 219 /**
 220  * CString version of nsEscape. Returns true on success, false
 221  * on out of memory. To reverse this function, use NS_UnescapeURL.
 222  */
 223 inline bool NS_Escape(const nsACString& aOriginal, nsACString& aEscaped,
 224                       nsEscapeMask aMask) {
 225   size_t escLen = 0;
 226   char* esc =
 227       nsEscape(aOriginal.BeginReading(), aOriginal.Length(), &escLen, aMask);
 228   if (!esc) {
 229     return false;
 230   }
 231   aEscaped.Adopt(esc, escLen);
 232   return true;
 233 }
 234
 235 /**
 236  * Inline unescape of mutable string object.
 237  */
 238 inline nsACString& NS_UnescapeURL(nsACString& aStr) {
 239   aStr.SetLength(nsUnescapeCount(aStr.BeginWriting()));
 240   return aStr;
 241 }
 242
 243 #endif  //  _ESCAPE_H_