Apache Portable Runtime
apr_escape.h
Go to the documentation of this file.
00001 /* Licensed to the Apache Software Foundation (ASF) under one or more
00002  * contributor license agreements.  See the NOTICE file distributed with
00003  * this work for additional information regarding copyright ownership.
00004  * The ASF licenses this file to You under the Apache License, Version 2.0
00005  * (the "License"); you may not use this file except in compliance with
00006  * the License.  You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 /**
00017  * @file apr_escape.h
00018  * @brief APR-UTIL Escaping
00019  */
00020 #ifndef APR_ESCAPE_H
00021 #define APR_ESCAPE_H
00022 #include "apr.h"
00023 #include "apr_general.h"
00024 #ifdef __cplusplus
00025 extern "C" {
00026 #endif
00027 
00028 /**
00029  * @defgroup APR_Util_Escaping Escape functions
00030  * @ingroup APR
00031  * @{
00032  */
00033 
00034 /* Simple escape/unescape functions.
00035  *
00036  */
00037 
00038 /**
00039  * When passing a string to one of the escape functions, this value can be
00040  * passed to indicate a string-valued key, and have the length computed
00041  * automatically.
00042  */
00043 #define APR_ESCAPE_STRING     (-1)
00044 
00045 /**
00046  * Perform shell escaping on the provided string.
00047  * 
00048  * Shell escaping causes characters to be prefixed with a '\' character.
00049  * @param escaped Optional buffer to write the encoded string, can be
00050  * NULL
00051  * @param str The original string
00052  * @param slen The length of the original string, or APR_ESCAPE_STRING
00053  * @param len If present, returns the length of the string
00054  * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were
00055  * detected or the string was NULL
00056  */
00057 APR_DECLARE(apr_status_t) apr_escape_shell(char *escaped, const char *str,
00058         apr_ssize_t slen, apr_size_t *len);
00059 
00060 /**
00061  * Perform shell escaping on the provided string, returning the result
00062  * from the pool.
00063  *
00064  * Shell escaping causes characters to be prefixed with a '\' character.
00065  *
00066  * If no characters were escaped, the original string is returned.
00067  * @param p Pool to allocate from
00068  * @param str The original string
00069  * @return the encoded string, allocated from the pool, or the original
00070  * string if no escaping took place or the string was NULL.
00071  */
00072 APR_DECLARE(const char *) apr_pescape_shell(apr_pool_t *p, const char *str)
00073         __attribute__((nonnull(1)));
00074 
00075 /**
00076  * Unescapes a URL, leaving reserved characters intact.
00077  * @param escaped Optional buffer to write the encoded string, can be
00078  * NULL
00079  * @param url String to be unescaped
00080  * @param slen The length of the original url, or APR_ESCAPE_STRING
00081  * @param forbid Optional list of forbidden characters, in addition to
00082  * 0x00
00083  * @param reserved Optional list of reserved characters that will be
00084  * left unescaped
00085  * @param plus If non zero, '+' is converted to ' ' as per
00086  * application/x-www-form-urlencoded encoding
00087  * @param len If set, the length of the escaped string will be returned
00088  * @return APR_SUCCESS on success, APR_NOTFOUND if no characters are
00089  * decoded or the string is NULL, APR_EINVAL if a bad escape sequence is
00090  * found, APR_BADCH if a character on the forbid list is found.
00091  */
00092 APR_DECLARE(apr_status_t) apr_unescape_url(char *escaped, const char *url,
00093         apr_ssize_t slen, const char *forbid, const char *reserved, int plus,
00094         apr_size_t *len);
00095 
00096 /**
00097  * Unescapes a URL, leaving reserved characters intact, returning the
00098  * result from a pool.
00099  * @param p Pool to allocate from
00100  * @param url String to be unescaped in place
00101  * @param forbid Optional list of forbidden characters, in addition to
00102  * 0x00
00103  * @param reserved Optional list of reserved characters that will be
00104  * left unescaped
00105  * @param plus If non zero, '+' is converted to ' ' as per
00106  * application/x-www-form-urlencoded encoding
00107  * @return A string allocated from the pool on success, the original string
00108  * if no characters are decoded, or NULL if a bad escape sequence is found
00109  * or if a character on the forbid list is found, or if the original string
00110  * was NULL.
00111  */
00112 APR_DECLARE(const char *) apr_punescape_url(apr_pool_t *p, const char *url,
00113         const char *forbid, const char *reserved, int plus)
00114         __attribute__((nonnull(1)));
00115 
00116 /**
00117  * Escape a path segment, as defined in RFC1808.
00118  * @param escaped Optional buffer to write the encoded string, can be
00119  * NULL
00120  * @param str The original string
00121  * @param slen The length of the original string, or APR_ESCAPE_STRING
00122  * @param len If present, returns the length of the string
00123  * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were
00124  * detected or the string was NULL
00125  */
00126 APR_DECLARE(apr_status_t) apr_escape_path_segment(char *escaped,
00127         const char *str, apr_ssize_t slen, apr_size_t *len);
00128 
00129 /**
00130  * Escape a path segment, as defined in RFC1808, returning the result from a
00131  * pool.
00132  * @param p Pool to allocate from
00133  * @param str String to be escaped
00134  * @return A string allocated from the pool on success, the original string
00135  * if no characters are encoded or the string is NULL.
00136  */
00137 APR_DECLARE(const char *) apr_pescape_path_segment(apr_pool_t *p,
00138         const char *str) __attribute__((nonnull(1)));
00139 
00140 /**
00141  * Converts an OS path to a URL, in an OS dependent way, as defined in RFC1808.
00142  * In all cases if a ':' occurs before the first '/' in the URL, the URL should
00143  * be prefixed with "./" (or the ':' escaped). In the case of Unix, this means
00144  * leaving '/' alone, but otherwise doing what escape_path_segment() does. For
00145  * efficiency reasons, we don't use escape_path_segment(), which is provided for
00146  * reference. Again, RFC 1808 is where this stuff is defined.
00147  *
00148  * If partial is set, os_escape_path() assumes that the path will be appended to
00149  * something with a '/' in it (and thus does not prefix "./").
00150  * @param escaped Optional buffer to write the encoded string, can be
00151  * NULL
00152  * @param path The original string
00153  * @param slen The length of the original string, or APR_ESCAPE_STRING
00154  * @param partial If non zero, suppresses the prepending of "./"
00155  * @param len If present, returns the length of the string
00156  * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were
00157  * detected or if the string was NULL
00158  */
00159 APR_DECLARE(apr_status_t) apr_escape_path(char *escaped, const char *path,
00160         apr_ssize_t slen, int partial, apr_size_t *len);
00161 
00162 /**
00163  * Converts an OS path to a URL, in an OS dependent way, as defined in RFC1808,
00164  * returning the result from a pool.
00165  *
00166  * In all cases if a ':' occurs before the first '/' in the URL, the URL should
00167  * be prefixed with "./" (or the ':' escaped). In the case of Unix, this means
00168  * leaving '/' alone, but otherwise doing what escape_path_segment() does. For
00169  * efficiency reasons, we don't use escape_path_segment(), which is provided for
00170  * reference. Again, RFC 1808 is where this stuff is defined.
00171  *
00172  * If partial is set, os_escape_path() assumes that the path will be appended to
00173  * something with a '/' in it (and thus does not prefix "./").
00174  * @param p Pool to allocate from
00175  * @param str The original string
00176  * @param partial If non zero, suppresses the prepending of "./"
00177  * @return A string allocated from the pool on success, the original string
00178  * if no characters are encoded or if the string was NULL.
00179  */
00180 APR_DECLARE(const char *) apr_pescape_path(apr_pool_t *p, const char *str,
00181         int partial) __attribute__((nonnull(1)));
00182 
00183 /**
00184  * Urlencode a string, as defined in
00185  * http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1.
00186  * @param escaped Optional buffer to write the encoded string, can be
00187  * NULL
00188  * @param str The original string
00189  * @param slen The length of the original string, or APR_ESCAPE_STRING
00190  * @param len If present, returns the length of the string
00191  * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were
00192  * detected or if the stirng was NULL
00193  */
00194 APR_DECLARE(apr_status_t) apr_escape_urlencoded(char *escaped, const char *str,
00195         apr_ssize_t slen, apr_size_t *len);
00196 
00197 /**
00198  * Urlencode a string, as defined in
00199  * http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1, returning
00200  * the result from a pool.
00201  * @param p Pool to allocate from
00202  * @param str String to be escaped
00203  * @return A string allocated from the pool on success, the original string
00204  * if no characters are encoded or if the string was NULL.
00205  */
00206 APR_DECLARE(const char *) apr_pescape_urlencoded(apr_pool_t *p,
00207         const char *str) __attribute__((nonnull(1)));
00208 
00209 /**
00210  * Apply entity encoding to a string. Characters are replaced as follows:
00211  * '<' becomes '&lt;', '>' becomes '&gt;', '&' becomes '&amp;', the
00212  * double quote becomes '&quot;" and the single quote becomes '&apos;'.
00213  *
00214  * If toasc is not zero, any non ascii character will be encoded as
00215  * '%\#ddd;', where ddd is the decimal code of the character.
00216  * @param escaped Optional buffer to write the encoded string, can be
00217  * NULL
00218  * @param str The original string
00219  * @param slen The length of the original string, or APR_ESCAPE_STRING
00220  * @param toasc If non zero, encode non ascii characters
00221  * @param len If present, returns the length of the string
00222  * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were
00223  * detected or the string was NULL
00224  */
00225 APR_DECLARE(apr_status_t) apr_escape_entity(char *escaped, const char *str,
00226         apr_ssize_t slen, int toasc, apr_size_t *len);
00227 
00228 /**
00229  * Apply entity encoding to a string, returning the result from a pool.
00230  * Characters are replaced as follows: '<' becomes '&lt;', '>' becomes
00231  * '&gt;', '&' becomes '&amp;', the double quote becomes '&quot;" and the
00232  * single quote becomes '&apos;'.
00233  * @param p Pool to allocate from
00234  * @param str The original string
00235  * @param toasc If non zero, encode non ascii characters
00236  * @return A string allocated from the pool on success, the original string
00237  * if no characters are encoded or the string is NULL.
00238  */
00239 APR_DECLARE(const char *) apr_pescape_entity(apr_pool_t *p, const char *str,
00240         int toasc) __attribute__((nonnull(1)));
00241 
00242 /**
00243  * Decodes html entities or numeric character references in a string. If
00244  * the string to be unescaped is syntactically incorrect, then the
00245  * following fixups will be made:
00246  * unknown entities will be left undecoded;
00247  * references to unused numeric characters will be deleted.
00248  * In particular, &#00; will not be decoded, but will be deleted.
00249  * @param unescaped Optional buffer to write the encoded string, can be
00250  * NULL
00251  * @param str The original string
00252  * @param slen The length of the original string, or APR_ESCAPE_STRING
00253  * @param len If present, returns the length of the string
00254  * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were
00255  * detected or the string was NULL
00256  */
00257 APR_DECLARE(apr_status_t) apr_unescape_entity(char *unescaped, const char *str,
00258         apr_ssize_t slen, apr_size_t *len);
00259 
00260 /**
00261  * Decodes html entities or numeric character references in a string. If
00262  * the string to be unescaped is syntactically incorrect, then the
00263  * following fixups will be made:
00264  * unknown entities will be left undecoded;
00265  * references to unused numeric characters will be deleted.
00266  * In particular, &#00; will not be decoded, but will be deleted.
00267  * @param p Pool to allocate from
00268  * @param str The original string
00269  * @return A string allocated from the pool on success, the original string
00270  * if no characters are encoded or the string is NULL.
00271  */
00272 APR_DECLARE(const char *) apr_punescape_entity(apr_pool_t *p, const char *str)
00273         __attribute__((nonnull(1)));
00274 
00275 /**
00276  * Escape control characters in a string, as performed by the shell's
00277  * 'echo' command. Characters are replaced as follows:
00278  * \\a alert (bell), \\b backspace, \\f form feed, \\n new line, \\r carriage
00279  * return, \\t horizontal tab, \\v vertical tab, \\ backslash.
00280  *
00281  * Any non ascii character will be encoded as '\\xHH', where HH is the hex
00282  * code of the character.
00283  *
00284  * If quote is not zero, the double quote character will also be escaped.
00285  * @param escaped Optional buffer to write the encoded string, can be
00286  * NULL
00287  * @param str The original string
00288  * @param slen The length of the original string, or APR_ESCAPE_STRING
00289  * @param quote If non zero, encode double quotes
00290  * @param len If present, returns the length of the string
00291  * @return APR_SUCCESS, or APR_NOTFOUND if no changes to the string were
00292  * detected or the string was NULL
00293  */
00294 APR_DECLARE(apr_status_t) apr_escape_echo(char *escaped, const char *str,
00295         apr_ssize_t slen, int quote, apr_size_t *len);
00296 
00297 /**
00298  * Escape control characters in a string, as performed by the shell's
00299  * 'echo' command, and return the results from a pool. Characters are
00300  * replaced as follows: \\a alert (bell), \\b backspace, \\f form feed,
00301  * \\n new line, \\r carriage return, \\t horizontal tab, \\v vertical tab,
00302  * \\ backslash.
00303  *
00304  * Any non ascii character will be encoded as '\\xHH', where HH is the hex
00305  * code of the character.
00306  *
00307  * If quote is not zero, the double quote character will also be escaped.
00308  * @param p Pool to allocate from
00309  * @param str The original string
00310  * @param quote If non zero, encode double quotes
00311  * @return A string allocated from the pool on success, the original string
00312  * if no characters are encoded or the string is NULL.
00313  */
00314 APR_DECLARE(const char *) apr_pescape_echo(apr_pool_t *p, const char *str,
00315         int quote);
00316 
00317 /**
00318  * Convert binary data to a hex encoding.
00319  * @param dest The destination buffer, can be NULL
00320  * @param src The original buffer
00321  * @param srclen The length of the original buffer
00322  * @param colon If not zero, insert colon characters between hex digits.
00323  * @param len If present, returns the length of the string
00324  * @return APR_SUCCESS, or APR_NOTFOUND if the string was NULL
00325  */
00326 APR_DECLARE(apr_status_t) apr_escape_hex(char *dest, const void *src,
00327         apr_size_t srclen, int colon, apr_size_t *len);
00328 
00329 /**
00330  * Convert binary data to a hex encoding, and return the results from a
00331  * pool.
00332  * @param p Pool to allocate from
00333  * @param src The original buffer
00334  * @param slen The length of the original buffer
00335  * @param colon If not zero, insert colon characters between hex digits.
00336  * @return A zero padded buffer allocated from the pool on success, or
00337  * NULL if src was NULL.
00338  */
00339 APR_DECLARE(const char *) apr_pescape_hex(apr_pool_t *p, const void *src,
00340         apr_size_t slen, int colon) __attribute__((nonnull(1)));
00341 
00342 /**
00343  * Convert hex encoded string to binary data.
00344  * @param dest The destination buffer, can be NULL
00345  * @param str The original buffer
00346  * @param slen The length of the original buffer
00347  * @param colon If not zero, ignore colon characters between hex digits.
00348  * @param len If present, returns the length of the string
00349  * @return APR_SUCCESS, or APR_NOTFOUND if the string was NULL, or APR_BADCH
00350  * if a non hex character is present.
00351  */
00352 APR_DECLARE(apr_status_t) apr_unescape_hex(void *dest, const char *str,
00353         apr_ssize_t slen, int colon, apr_size_t *len);
00354 
00355 /**
00356  * Convert hex encoding to binary data, and return the results from a pool.
00357  * If the colon character appears between pairs of hex digits, it will be
00358  * ignored.
00359  * @param p Pool to allocate from
00360  * @param str The original string
00361  * @param colon If not zero, ignore colon characters between hex digits.
00362  * @param len If present, returns the length of the final buffer
00363  * @return A buffer allocated from the pool on success, or NULL if src was
00364  * NULL, or a bad character was present.
00365  */
00366 APR_DECLARE(const void *) apr_punescape_hex(apr_pool_t *p, const char *str,
00367         int colon, apr_size_t *len);
00368 
00369 /** @} */
00370 #ifdef __cplusplus
00371 }
00372 #endif
00373 
00374 #endif  /* !APR_ESCAPE_H */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines