/work/obj-fuzz/dist/include/nsEscape.h

Source (jump to first uncovered line)
/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

/*  First checked in on 98/12/03 by John R. McMullen, derived from net.h/mkparse.c. */

#ifndef _ESCAPE_H_
#define _ESCAPE_H_

#include "nscore.h"
#include "nsError.h"
#include "nsString.h"

/**
 * Valid mask values for nsEscape
 * Note: these values are copied in nsINetUtil.idl. Any changes should be kept
 * in sync.
 */
typedef enum {
  url_All       = 0,       // %-escape every byte unconditionally
  url_XAlphas   = 1u << 0, // Normal escape - leave alphas intact, escape the rest
  url_XPAlphas  = 1u << 1, // As url_XAlphas, but convert spaces (0x20) to '+' and plus to %2B
  url_Path      = 1u << 2  // As url_XAlphas, but don't escape slash ('/')
} nsEscapeMask;

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Escape the given string according to mask
 * @param aSstr The string to escape
 * @param aLength The length of the string to escape
 * @param aOutputLen A pointer that will be used to store the length of the
 *        output string, if not null
 * @param aMask How to escape the string
 * @return A newly allocated escaped string that must be free'd with
 *         nsCRT::free, or null on failure
 * @note: Please, don't use this function. Use NS_Escape instead!
 */
char* nsEscape(const char* aStr, size_t aLength, size_t* aOutputLen,
               nsEscapeMask aMask);

/**
 * Decodes '%'-escaped hex codes into character values, modifies the parameter,
 * returns the same buffer
 */
char* nsUnescape(char* aStr);

/**
 * Decodes '%'-escaped hex codes into character values, modifies the parameter
 * buffer, returns the length of the result (result may contain \0's).
 */
int32_t nsUnescapeCount(char* aStr);

#ifdef __cplusplus
}
#endif

/**
 * Infallibly append aSrc to aDst, escaping chars that are problematic for HTML
 * display.
 */
void nsAppendEscapedHTML(const nsACString& aSrc, nsACString& aDst);

/**
 * NS_EscapeURL/NS_UnescapeURL constants for |flags| parameter:
 *
 * Note: These values are copied to nsINetUtil.idl
 *       Any changes should be kept in sync
 */
enum EscapeMask {
  /** url components **/
  esc_Scheme         = 1u << 0,
  esc_Username       = 1u << 1,
  esc_Password       = 1u << 2,
  esc_Host           = 1u << 3,
  esc_Directory      = 1u << 4,
  esc_FileBaseName   = 1u << 5,
  esc_FileExtension  = 1u << 6,
  esc_FilePath       = esc_Directory | esc_FileBaseName | esc_FileExtension,
  esc_Param          = 1u << 7,
  esc_Query          = 1u << 8,
  esc_Ref            = 1u << 9,
  /** special flags **/
  esc_Minimal        = esc_Scheme | esc_Username | esc_Password | esc_Host | esc_FilePath | esc_Param | esc_Query | esc_Ref,
  esc_Forced         = 1u << 10, /* forces escaping of existing escape sequences */
  esc_OnlyASCII      = 1u << 11, /* causes non-ascii octets to be skipped */
  esc_OnlyNonASCII   = 1u << 12, /* causes _graphic_ ascii octets (0x20-0x7E)
                                    * to be skipped when escaping. causes all
                                    * ascii octets (<= 0x7F) to be skipped when unescaping */
  esc_AlwaysCopy     = 1u << 13, /* copy input to result buf even if escaping is unnecessary */
  esc_Colon          = 1u << 14, /* forces escape of colon */
  esc_SkipControl    = 1u << 15, /* skips C0 and DEL from unescaping */
  esc_Spaces         = 1u << 16  /* forces escape of spaces */
};

/**
 * NS_EscapeURL
 *
 * Escapes invalid char's in an URL segment.  Has no side-effect if the URL
 * segment is already escaped, unless aFlags has the esc_Forced bit in which
 * case % will also be escaped.  Iff some part of aStr is escaped is the
 * final result appended to aResult.  You can also request that aStr is
 * always appended to aResult with esc_AlwaysCopy.
 *
 * @param aStr     url segment string
 * @param aLen     url segment string length (-1 if unknown)
 * @param aFlags   url segment type flag (see EscapeMask above)
 * @param aResult  result buffer, untouched if aStr is already escaped unless
 *                 aFlags has esc_AlwaysCopy
 *
 * @return true if aResult was written to (i.e. at least one character was
 *              escaped or esc_AlwaysCopy was requested), false otherwise.
 */
bool NS_EscapeURL(const char* aStr,
                  int32_t aLen,
                  uint32_t aFlags,
                  nsACString& aResult);

/**
 * Expands URL escape sequences... beware embedded null bytes!
 *
 * @param aStr     url string to unescape
 * @param aLen     length of aStr
 * @param aFlags   only esc_OnlyNonASCII, esc_SkipControl and esc_AlwaysCopy
 *                 are recognized
 * @param aResult  result buffer, untouched if aStr is already unescaped unless
 *                 aFlags has esc_AlwaysCopy
 *
 * @return true if aResult was written to (i.e. at least one character was
 *              unescaped or esc_AlwaysCopy was requested), false otherwise.
 */
bool NS_UnescapeURL(const char* aStr,
                    int32_t aLen,
                    uint32_t aFlags,
                    nsACString& aResult);

/**
 * Fallible version of |NS_UnescapeURL|. See above for details.
 *
 * @param aAppended Out param: true if aResult was written to (i.e. at least
 *                  one character was unescaped or esc_AlwaysCopy was
 *                  requested), false otherwise.
 */
nsresult NS_UnescapeURL(const char* aStr,
                        int32_t aLen,
                        uint32_t aFlags,
                        nsACString& aResult,
                        bool& aAppended,
                        const mozilla::fallible_t&);

/** returns resultant string length **/
inline int32_t
NS_UnescapeURL(char* aStr)
{
  return nsUnescapeCount(aStr);
}

/**
 * String friendly versions...
 */
inline const nsACString&
NS_EscapeURL(const nsACString& aStr, uint32_t aFlags, nsACString& aResult)
{
  if (NS_EscapeURL(aStr.Data(), aStr.Length(), aFlags, aResult)) {
    return aResult;
  }
  return aStr;
}

/**
 * Fallible version of NS_EscapeURL. On success aResult will point to either
 * the original string or an escaped copy.
 */
nsresult
NS_EscapeURL(const nsACString& aStr, uint32_t aFlags, nsACString& aResult,
             const mozilla::fallible_t&);

// Forward declaration for nsASCIIMask.h
typedef std::array<bool, 128> ASCIIMaskArray;

/**
 * The same as NS_EscapeURL, except it also filters out characters that match
 * aFilterMask.
 */
nsresult
NS_EscapeAndFilterURL(const nsACString& aStr, uint32_t aFlags,
                      const ASCIIMaskArray* aFilterMask,
                      nsACString& aResult, const mozilla::fallible_t&);


inline const nsACString&
NS_UnescapeURL(const nsACString& aStr, uint32_t aFlags, nsACString& aResult)
{
  if (NS_UnescapeURL(aStr.Data(), aStr.Length(), aFlags, aResult)) {
    return aResult;
  }
  return aStr;
}

const nsAString&
NS_EscapeURL(const nsAString& aStr, uint32_t aFlags, nsAString& aResult);

/**
 * Percent-escapes all characters in aStr that occurs in aForbidden.
 * @param aStr the input URL string
 * @param aForbidden the characters that should be escaped if found in aStr
 * @note that aForbidden MUST be sorted (low to high)
 * @param aResult the result if some characters were escaped
 * @return aResult if some characters were escaped, or aStr otherwise (aResult
 *         is unmodified in that case)
 */
const nsAString&
NS_EscapeURL(const nsString& aStr, const nsTArray<char16_t>& aForbidden,
             nsAString& aResult);

/**
 * CString version of nsEscape. Returns true on success, false
 * on out of memory. To reverse this function, use NS_UnescapeURL.
 */
inline bool
NS_Escape(const nsACString& aOriginal, nsACString& aEscaped,
          nsEscapeMask aMask)
{
  size_t escLen = 0;
  char* esc = nsEscape(aOriginal.BeginReading(), aOriginal.Length(), &escLen,
                       aMask);
  if (! esc) {
    return false;
  }
  aEscaped.Adopt(esc, escLen);
  return true;
}

/**
 * Inline unescape of mutable string object.
 */
inline nsACString&
NS_UnescapeURL(nsACString& aStr)
{
  aStr.SetLength(nsUnescapeCount(aStr.BeginWriting()));
  return aStr;
}

#endif //  _ESCAPE_H_

Coverage Report

Created: 2018-09-25 14:53

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