1 : /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 : /* ***** BEGIN LICENSE BLOCK *****
3 : * Version: MPL 1.1/GPL 2.0/LGPL 2.1
4 : *
5 : * The contents of this file are subject to the Mozilla Public License Version
6 : * 1.1 (the "License"); you may not use this file except in compliance with
7 : * the License. You may obtain a copy of the License at
8 : * http://www.mozilla.org/MPL/
9 : *
10 : * Software distributed under the License is distributed on an "AS IS" basis,
11 : * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12 : * for the specific language governing rights and limitations under the
13 : * License.
14 : *
15 : * The Original Code is mozilla.org code.
16 : *
17 : * The Initial Developer of the Original Code is
18 : * Netscape Communications Corporation.
19 : * Portions created by the Initial Developer are Copyright (C) 1998
20 : * the Initial Developer. All Rights Reserved.
21 : *
22 : * Contributor(s):
23 : *
24 : * Alternatively, the contents of this file may be used under the terms of
25 : * either of the GNU General Public License Version 2 or later (the "GPL"),
26 : * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
27 : * in which case the provisions of the GPL or the LGPL are applicable instead
28 : * of those above. If you wish to allow use of your version of this file only
29 : * under the terms of either the GPL or the LGPL, and not to allow others to
30 : * use your version of this file under the terms of the MPL, indicate your
31 : * decision by deleting the provisions above and replace them with the notice
32 : * and other provisions required by the GPL or the LGPL. If you do not delete
33 : * the provisions above, a recipient may use your version of this file under
34 : * the terms of any one of the MPL, the GPL or the LGPL.
35 : *
36 : * ***** END LICENSE BLOCK ***** */
37 :
38 : /* First checked in on 98/12/03 by John R. McMullen, derived from net.h/mkparse.c. */
39 :
40 : #ifndef _ESCAPE_H_
41 : #define _ESCAPE_H_
42 :
43 : #include "prtypes.h"
44 : #include "nscore.h"
45 : #include "nsError.h"
46 : #include "nsString.h"
47 :
48 : /**
49 : * Valid mask values for nsEscape
50 : * Note: these values are copied in nsINetUtil.idl. Any changes should be kept
51 : * in sync.
52 : */
53 : typedef enum {
54 : url_All = 0 /**< %-escape every byte unconditionally */
55 : , url_XAlphas = PR_BIT(0) /**< Normal escape - leave alphas intact, escape the rest */
56 : , url_XPAlphas = PR_BIT(1) /**< As url_XAlphas, but convert spaces (0x20) to '+' and plus to %2B */
57 : , url_Path = PR_BIT(2) /**< As url_XAlphas, but don't escape slash ('/') */
58 : } nsEscapeMask;
59 :
60 : #ifdef __cplusplus
61 : extern "C" {
62 : #endif
63 :
64 : /**
65 : * Escape the given string according to mask
66 : * @param str The string to escape
67 : * @param mask How to escape the string
68 : * @return A newly allocated escaped string that must be free'd with
69 : * nsCRT::free, or null on failure
70 : */
71 : char * nsEscape(const char * str, nsEscapeMask mask);
72 :
73 : char * nsUnescape(char * str);
74 : /* decode % escaped hex codes into character values,
75 : * modifies the parameter, returns the same buffer
76 : */
77 :
78 : PRInt32 nsUnescapeCount (char * str);
79 : /* decode % escaped hex codes into character values,
80 : * modifies the parameter buffer, returns the length of the result
81 : * (result may contain \0's).
82 : */
83 :
84 : char *
85 : nsEscapeHTML(const char * string);
86 :
87 : PRUnichar *
88 : nsEscapeHTML2(const PRUnichar *aSourceBuffer,
89 : PRInt32 aSourceBufferLen = -1);
90 : /*
91 : * Escape problem char's for HTML display
92 : */
93 :
94 :
95 : #ifdef __cplusplus
96 : }
97 : #endif
98 :
99 :
100 : /**
101 : * NS_EscapeURL/NS_UnescapeURL constants for |flags| parameter:
102 : *
103 : * Note: These values are copied to nsINetUtil.idl
104 : * Any changes should be kept in sync
105 : */
106 : enum EscapeMask {
107 : /** url components **/
108 : esc_Scheme = PR_BIT(0),
109 : esc_Username = PR_BIT(1),
110 : esc_Password = PR_BIT(2),
111 : esc_Host = PR_BIT(3),
112 : esc_Directory = PR_BIT(4),
113 : esc_FileBaseName = PR_BIT(5),
114 : esc_FileExtension = PR_BIT(6),
115 : esc_FilePath = esc_Directory | esc_FileBaseName | esc_FileExtension,
116 : esc_Param = PR_BIT(7),
117 : esc_Query = PR_BIT(8),
118 : esc_Ref = PR_BIT(9),
119 : /** special flags **/
120 : esc_Minimal = esc_Scheme | esc_Username | esc_Password | esc_Host | esc_FilePath | esc_Param | esc_Query | esc_Ref,
121 : esc_Forced = PR_BIT(10), /* forces escaping of existing escape sequences */
122 : esc_OnlyASCII = PR_BIT(11), /* causes non-ascii octets to be skipped */
123 : esc_OnlyNonASCII = PR_BIT(12), /* causes _graphic_ ascii octets (0x20-0x7E)
124 : * to be skipped when escaping. causes all
125 : * ascii octets (<= 0x7F) to be skipped when unescaping */
126 : esc_AlwaysCopy = PR_BIT(13), /* copy input to result buf even if escaping is unnecessary */
127 : esc_Colon = PR_BIT(14), /* forces escape of colon */
128 : esc_SkipControl = PR_BIT(15) /* skips C0 and DEL from unescaping */
129 : };
130 :
131 : /**
132 : * NS_EscapeURL
133 : *
134 : * Escapes invalid char's in an URL segment. Has no side-effect if the URL
135 : * segment is already escaped. Otherwise, the escaped URL segment is appended
136 : * to |result|.
137 : *
138 : * @param str url segment string
139 : * @param len url segment string length (-1 if unknown)
140 : * @param flags url segment type flag
141 : * @param result result buffer, untouched if part is already escaped
142 : *
143 : * @return TRUE if escaping was performed, FALSE otherwise.
144 : */
145 : bool NS_EscapeURL(const char *str,
146 : PRInt32 len,
147 : PRUint32 flags,
148 : nsACString &result);
149 :
150 : /**
151 : * Expands URL escape sequences... beware embedded null bytes!
152 : *
153 : * @param str url string to unescape
154 : * @param len length of |str|
155 : * @param flags only esc_OnlyNonASCII, esc_SkipControl and esc_AlwaysCopy
156 : * are recognized
157 : * @param result result buffer, untouched if |str| is already unescaped
158 : *
159 : * @return TRUE if unescaping was performed, FALSE otherwise.
160 : */
161 : bool NS_UnescapeURL(const char *str,
162 : PRInt32 len,
163 : PRUint32 flags,
164 : nsACString &result);
165 :
166 : /** returns resultant string length **/
167 302 : inline PRInt32 NS_UnescapeURL(char *str) {
168 302 : return nsUnescapeCount(str);
169 : }
170 :
171 : /**
172 : * String friendly versions...
173 : */
174 : inline const nsCSubstring &
175 185883 : NS_EscapeURL(const nsCSubstring &str, PRUint32 flags, nsCSubstring &result) {
176 185883 : if (NS_EscapeURL(str.Data(), str.Length(), flags, result))
177 185858 : return result;
178 25 : return str;
179 : }
180 : inline const nsCSubstring &
181 2242 : NS_UnescapeURL(const nsCSubstring &str, PRUint32 flags, nsCSubstring &result) {
182 2242 : if (NS_UnescapeURL(str.Data(), str.Length(), flags, result))
183 2214 : return result;
184 28 : return str;
185 : }
186 :
187 : /**
188 : * CString version of nsEscape. Returns true on success, false
189 : * on out of memory. To reverse this function, use NS_UnescapeURL.
190 : */
191 : inline bool
192 5421 : NS_Escape(const nsCString& aOriginal, nsCString& aEscaped,
193 : nsEscapeMask aMask)
194 : {
195 5421 : char* esc = nsEscape(aOriginal.get(), aMask);
196 5421 : if (! esc)
197 0 : return false;
198 5421 : aEscaped.Adopt(esc);
199 5421 : return true;
200 : }
201 :
202 : /**
203 : * Inline unescape of mutable string object.
204 : */
205 : inline nsCString &
206 137887 : NS_UnescapeURL(nsCString &str)
207 : {
208 137887 : str.SetLength(nsUnescapeCount(str.BeginWriting()));
209 137887 : return str;
210 : }
211 :
212 : #endif // _ESCAPE_H_
|