1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/xpcom/io/nsEscape.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,179 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +/* First checked in on 98/12/03 by John R. McMullen, derived from net.h/mkparse.c. */
1.10 +
1.11 +#ifndef _ESCAPE_H_
1.12 +#define _ESCAPE_H_
1.13 +
1.14 +#include "nscore.h"
1.15 +#include "nsError.h"
1.16 +#include "nsString.h"
1.17 +
1.18 +/**
1.19 + * Valid mask values for nsEscape
1.20 + * Note: these values are copied in nsINetUtil.idl. Any changes should be kept
1.21 + * in sync.
1.22 + */
1.23 +typedef enum {
1.24 + url_All = 0 /**< %-escape every byte unconditionally */
1.25 +, url_XAlphas = 1u << 0 /**< Normal escape - leave alphas intact, escape the rest */
1.26 +, url_XPAlphas = 1u << 1 /**< As url_XAlphas, but convert spaces (0x20) to '+' and plus to %2B */
1.27 +, url_Path = 1u << 2 /**< As url_XAlphas, but don't escape slash ('/') */
1.28 +} nsEscapeMask;
1.29 +
1.30 +#ifdef __cplusplus
1.31 +extern "C" {
1.32 +#endif
1.33 +
1.34 +/**
1.35 + * Escape the given string according to mask
1.36 + * @param str The string to escape
1.37 + * @param mask How to escape the string
1.38 + * @return A newly allocated escaped string that must be free'd with
1.39 + * nsCRT::free, or null on failure
1.40 + */
1.41 +char * nsEscape(const char * str, nsEscapeMask mask);
1.42 +
1.43 +char * nsUnescape(char * str);
1.44 + /* decode % escaped hex codes into character values,
1.45 + * modifies the parameter, returns the same buffer
1.46 + */
1.47 +
1.48 +int32_t nsUnescapeCount (char * str);
1.49 + /* decode % escaped hex codes into character values,
1.50 + * modifies the parameter buffer, returns the length of the result
1.51 + * (result may contain \0's).
1.52 + */
1.53 +
1.54 +char *
1.55 +nsEscapeHTML(const char * string);
1.56 +
1.57 +char16_t *
1.58 +nsEscapeHTML2(const char16_t *aSourceBuffer,
1.59 + int32_t aSourceBufferLen = -1);
1.60 + /*
1.61 + * Escape problem char's for HTML display
1.62 + */
1.63 +
1.64 +
1.65 +#ifdef __cplusplus
1.66 +}
1.67 +#endif
1.68 +
1.69 +
1.70 +/**
1.71 + * NS_EscapeURL/NS_UnescapeURL constants for |flags| parameter:
1.72 + *
1.73 + * Note: These values are copied to nsINetUtil.idl
1.74 + * Any changes should be kept in sync
1.75 + */
1.76 +enum EscapeMask {
1.77 + /** url components **/
1.78 + esc_Scheme = 1u << 0,
1.79 + esc_Username = 1u << 1,
1.80 + esc_Password = 1u << 2,
1.81 + esc_Host = 1u << 3,
1.82 + esc_Directory = 1u << 4,
1.83 + esc_FileBaseName = 1u << 5,
1.84 + esc_FileExtension = 1u << 6,
1.85 + esc_FilePath = esc_Directory | esc_FileBaseName | esc_FileExtension,
1.86 + esc_Param = 1u << 7,
1.87 + esc_Query = 1u << 8,
1.88 + esc_Ref = 1u << 9,
1.89 + /** special flags **/
1.90 + esc_Minimal = esc_Scheme | esc_Username | esc_Password | esc_Host | esc_FilePath | esc_Param | esc_Query | esc_Ref,
1.91 + esc_Forced = 1u << 10, /* forces escaping of existing escape sequences */
1.92 + esc_OnlyASCII = 1u << 11, /* causes non-ascii octets to be skipped */
1.93 + esc_OnlyNonASCII = 1u << 12, /* causes _graphic_ ascii octets (0x20-0x7E)
1.94 + * to be skipped when escaping. causes all
1.95 + * ascii octets (<= 0x7F) to be skipped when unescaping */
1.96 + esc_AlwaysCopy = 1u << 13, /* copy input to result buf even if escaping is unnecessary */
1.97 + esc_Colon = 1u << 14, /* forces escape of colon */
1.98 + esc_SkipControl = 1u << 15 /* skips C0 and DEL from unescaping */
1.99 +};
1.100 +
1.101 +/**
1.102 + * NS_EscapeURL
1.103 + *
1.104 + * Escapes invalid char's in an URL segment. Has no side-effect if the URL
1.105 + * segment is already escaped. Otherwise, the escaped URL segment is appended
1.106 + * to |result|.
1.107 + *
1.108 + * @param str url segment string
1.109 + * @param len url segment string length (-1 if unknown)
1.110 + * @param flags url segment type flag
1.111 + * @param result result buffer, untouched if part is already escaped
1.112 + *
1.113 + * @return TRUE if escaping was performed, FALSE otherwise.
1.114 + */
1.115 +bool NS_EscapeURL(const char *str,
1.116 + int32_t len,
1.117 + uint32_t flags,
1.118 + nsACString &result);
1.119 +
1.120 +/**
1.121 + * Expands URL escape sequences... beware embedded null bytes!
1.122 + *
1.123 + * @param str url string to unescape
1.124 + * @param len length of |str|
1.125 + * @param flags only esc_OnlyNonASCII, esc_SkipControl and esc_AlwaysCopy
1.126 + * are recognized
1.127 + * @param result result buffer, untouched if |str| is already unescaped
1.128 + *
1.129 + * @return TRUE if unescaping was performed, FALSE otherwise.
1.130 + */
1.131 +bool NS_UnescapeURL(const char *str,
1.132 + int32_t len,
1.133 + uint32_t flags,
1.134 + nsACString &result);
1.135 +
1.136 +/** returns resultant string length **/
1.137 +inline int32_t NS_UnescapeURL(char *str) {
1.138 + return nsUnescapeCount(str);
1.139 +}
1.140 +
1.141 +/**
1.142 + * String friendly versions...
1.143 + */
1.144 +inline const nsCSubstring &
1.145 +NS_EscapeURL(const nsCSubstring &str, uint32_t flags, nsCSubstring &result) {
1.146 + if (NS_EscapeURL(str.Data(), str.Length(), flags, result))
1.147 + return result;
1.148 + return str;
1.149 +}
1.150 +inline const nsCSubstring &
1.151 +NS_UnescapeURL(const nsCSubstring &str, uint32_t flags, nsCSubstring &result) {
1.152 + if (NS_UnescapeURL(str.Data(), str.Length(), flags, result))
1.153 + return result;
1.154 + return str;
1.155 +}
1.156 +
1.157 +/**
1.158 + * CString version of nsEscape. Returns true on success, false
1.159 + * on out of memory. To reverse this function, use NS_UnescapeURL.
1.160 + */
1.161 +inline bool
1.162 +NS_Escape(const nsCString& aOriginal, nsCString& aEscaped,
1.163 + nsEscapeMask aMask)
1.164 +{
1.165 + char* esc = nsEscape(aOriginal.get(), aMask);
1.166 + if (! esc)
1.167 + return false;
1.168 + aEscaped.Adopt(esc);
1.169 + return true;
1.170 +}
1.171 +
1.172 +/**
1.173 + * Inline unescape of mutable string object.
1.174 + */
1.175 +inline nsCString &
1.176 +NS_UnescapeURL(nsCString &str)
1.177 +{
1.178 + str.SetLength(nsUnescapeCount(str.BeginWriting()));
1.179 + return str;
1.180 +}
1.181 +
1.182 +#endif // _ESCAPE_H_
