LCOV - code coverage report
Current view: directory - objdir/dist/include - nsEscape.h (source / functions) Found Hit Coverage
Test: app.info Lines: 19 18 94.7 %
Date: 2012-06-02 Functions: 5 5 100.0 %

       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_

Generated by: LCOV version 1.7