1 /* 2 * Copyright (C) 1996-2021 The Squid Software Foundation and contributors 3 * 4 * Squid software is distributed under GPLv2+ license and includes 5 * contributions from numerous individuals and organizations. 6 * Please see the COPYING and CONTRIBUTORS files for details. 7 */ 8 9 #ifndef _SQUID_INCLUDE_RFC1738_H 10 #define _SQUID_INCLUDE_RFC1738_H 11 12 #ifdef __cplusplus 13 extern "C" { 14 #endif 15 16 /* Encoder rfc1738_do_escape flag values. */ 17 #define RFC1738_ESCAPE_CTRLS 1 18 #define RFC1738_ESCAPE_UNSAFE 2 19 #define RFC1738_ESCAPE_RESERVED 4 20 #define RFC1738_ESCAPE_ALL (RFC1738_ESCAPE_UNSAFE|RFC1738_ESCAPE_RESERVED|RFC1738_ESCAPE_CTRLS) 21 // exclusions 22 #define RFC1738_ESCAPE_NOSPACE 128 23 #define RFC1738_ESCAPE_NOPERCENT 256 24 // Backward compatibility 25 #define RFC1738_ESCAPE_UNESCAPED (RFC1738_ESCAPE_UNSAFE|RFC1738_ESCAPE_CTRLS|RFC1738_ESCAPE_NOPERCENT) 26 27 /** 28 * \group rfc1738 RFC 1738 URL-escaping library 29 * 30 * Public API is formed of a triplet of encode functions mapping to the rfc1738_do_encode() engine. 31 * 32 * ASCII characters are split into four groups: 33 * \item SAFE Characters which are safe to occur in any URL. For example A,B,C 34 * \item CTRLS Binary control codes. Dangerous to include in URLs. 35 * \item UNSAFE Characters which are completely usafe to occur in any URL. For example; backspace, tab, space, newline. 36 * \item RESERVED Characters which are reserved for special meaning and may only occur in certain parts of a URL. 37 * 38 * Returns a static buffer containing the RFC 1738 compliant, escaped version of the given url. 39 * 40 * \param flags RFC1738_ESCAPE_CTRLS Encode the blatantly dangerous binary codes. 41 * \param flags RFC1738_ESCAPE_UNSAFE Encode printable unsafe characters (excluding CTRLs). 42 * \param flags RFC1738_ESCAPE_RESERVED Encode reserved characters. 43 * \param flags RFC1738_ESCAPE_ALL Encode all binary CTRL, unsafe and reserved characters. 44 * \param flags RFC1738_ESCAPE_NOSPACE Ignore the space whitespace character. 45 * \param flags RFC1738_ESCAPE_NOPERCENT Ignore the escaping delimiter '%'. 46 */ 47 extern char *rfc1738_do_escape(const char *url, int flags); 48 49 /* Old API functions */ 50 51 /* Default RFC 1738 escaping. Escape all UNSAFE characters and binary CTRL codes */ 52 #define rfc1738_escape(x) rfc1738_do_escape(x, RFC1738_ESCAPE_UNSAFE|RFC1738_ESCAPE_CTRLS) 53 54 /* Escape a partial URL. Encoding every binary code, unsafe or reserved character. */ 55 #define rfc1738_escape_part(x) rfc1738_do_escape(x, RFC1738_ESCAPE_ALL) 56 57 /* Escape a URL. Encoding every unsafe characters but skipping reserved and already-encoded bytes. 58 * Suitable for safely encoding an absolute URL which may be encoded but is not trusted. */ 59 #define rfc1738_escape_unescaped(x) rfc1738_do_escape(x, RFC1738_ESCAPE_UNSAFE|RFC1738_ESCAPE_CTRLS|RFC1738_ESCAPE_NOPERCENT) 60 61 /** 62 * Unescape a URL string according to RFC 1738 specification. 63 * String is unescaped in-place 64 */ 65 extern void rfc1738_unescape(char *url); 66 67 #ifdef __cplusplus 68 } 69 #endif 70 #endif /* _SQUID_INCLUDE_RFC1738_H */ 71 72