granicus.if.org Git - apache/blob - include/ap_expr.h

   1 /* Licensed to the Apache Software Foundation (ASF) under one or more
   2  * contributor license agreements.  See the NOTICE file distributed with
   3  * this work for additional information regarding copyright ownership.
   4  * The ASF licenses this file to You under the Apache License, Version 2.0
   5  * (the "License"); you may not use this file except in compliance with
   6  * the License.  You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file ap_expr.h
  19  * @brief Expression parser
  20  *
  21  * @defgroup AP_EXPR ap_expr
  22  * @ingroup  APACHE_CORE
  23  * @{
  24  */
  25
  26 #ifndef AP_EXPR_H
  27 #define AP_EXPR_H
  28
  29 #include "httpd.h"
  30 #include "http_config.h"
  31 #include "ap_regex.h"
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /** A node in the expression parse tree */
  38 typedef struct ap_expr_node ap_expr_t;
  39
  40 /** Struct describing a parsed expression */
  41 typedef struct {
  42     /** The root of the actual expression parse tree */
  43     ap_expr_t *root_node;
  44     /** The filename where the expression has been defined (for logging).
  45      *  May be NULL
  46      */
  47     const char *filename;
  48     /** The line number where the expression has been defined (for logging). */
  49     unsigned int line_number;
  50     /** Flags relevant for the expression, see AP_EXPR_FLAGS_* */
  51     unsigned int flags;
  52     /** The module that is used for loglevel configuration (XXX put into eval_ctx?) */
  53     int module_index;
  54 } ap_expr_info_t;
  55
  56 /** Use ssl_expr compatibility mode (changes the meaning of the comparison
  57  * operators)
  58  */
  59 #define AP_EXPR_FLAGS_SSL_EXPR_COMPAT       1
  60 /** Don't add siginificant request headers to the Vary response header */
  61 #define AP_EXPR_FLAGS_DONT_VARY             2
  62
  63
  64 /**
  65  * Evaluate a parse tree, simple interface
  66  * @param r The current request
  67  * @param expr The expression to be evaluated
  68  * @param err Where an error message should be stored
  69  * @return > 0 if expression evaluates to true, == 0 if false, < 0 on error
  70  * @note err will be set to NULL on success, or to an error message on error
  71  * @note request headers used during evaluation will be added to the Vary:
  72  *       response header, unless ::AP_EXPR_FLAGS_DONT_VARY is set.
  73  */
  74 AP_DECLARE(int) ap_expr_exec(request_rec *r, const ap_expr_info_t *expr,
  75                              const char **err);
  76
  77 /**
  78  * Evaluate a parse tree, with access to regexp backreference
  79  * @param r The current request
  80  * @param expr The expression to be evaluated
  81  * @param nmatch size of the regex match vector pmatch
  82  * @param pmatch information about regex matches
  83  * @param source the string that pmatch applies to
  84  * @param err Where an error message should be stored
  85  * @return > 0 if expression evaluates to true, == 0 if false, < 0 on error
  86  * @note err will be set to NULL on success, or to an error message on error
  87  * @note nmatch/pmatch/source can be used both to make previous matches
  88  *       available to ap_expr_exec_re and to use ap_expr_exec_re's matches
  89  *       later on.
  90  * @note request headers used during evaluation will be added to the Vary:
  91  *       response header, unless ::AP_EXPR_FLAGS_DONT_VARY is set.
  92  */
  93 AP_DECLARE(int) ap_expr_exec_re(request_rec *r, const ap_expr_info_t *expr,
  94                                 apr_size_t nmatch, ap_regmatch_t *pmatch,
  95                                 const char **source, const char **err);
  96
  97 /** Context used during evaluation of a parse tree, created by ap_expr_exec */
  98 typedef struct {
  99     /** the current request */
 100     request_rec *r;
 101     /** the current connection */
 102     conn_rec *c;
 103     /** the current connection */
 104     server_rec *s;
 105     /** the pool to use */
 106     apr_pool_t *p;
 107     /** where to store the error string */
 108     const char **err;
 109     /** ap_expr_info_t for the expression */
 110     const ap_expr_info_t *info;
 111     /** regex match information for back references */
 112     ap_regmatch_t *re_pmatch;
 113     /** size of the vector pointed to by re_pmatch */
 114     apr_size_t re_nmatch;
 115     /** the string corresponding to the re_pmatch */
 116     const char **re_source;
 117     /** A string where the comma separated names of headers are stored
 118      * to be later added to the Vary: header. If NULL, the caller is not
 119      * interested in this information.
 120      */
 121     const char **vary_this;
 122 } ap_expr_eval_ctx_t;
 123
 124
 125 /**
 126  * The parser can be extended with variable lookup, functions, and
 127  * and operators.
 128  *
 129  * During parsing, the parser calls the lookup function to resolve a
 130  * name into a function pointer and an opaque context for the function.
 131  * If the argument to a function or operator is constant, the lookup function
 132  * may also parse that argument and store the parsed data in the context.
 133  *
 134  * The default lookup function is the hook ::ap_expr_lookup_default which just
 135  * calls ap_run_expr_lookup. Modules can use it to make functions and
 136  * variables generally available.
 137  *
 138  * An ap_expr consumer can also provide its own custom lookup function to
 139  * modify the set of variables and functions that are available. The custom
 140  * lookup function can in turn call 'ap_run_expr_lookup'.
 141  */
 142
 143 /** Unary operator, takes one string argument and returns a bool value.
 144  * The name must have the form '-z' (one letter only).
 145  * @param ctx The evaluation context
 146  * @param data An opaque context provided by the lookup hook function
 147  * @param arg The (right) operand
 148  * @return 0 or 1
 149  */
 150 typedef int ap_expr_op_unary_t(ap_expr_eval_ctx_t *ctx, const void *data,
 151                                const char *arg);
 152
 153 /** Binary operator, takes two string arguments and returns a bool value.
 154  * The name must have the form '-cmp' (at least two letters).
 155  * @param ctx The evaluation context
 156  * @param data An opaque context provided by the lookup hook function
 157  * @param arg1 The left operand
 158  * @param arg2 The right operand
 159  * @return 0 or 1
 160  */
 161 typedef int ap_expr_op_binary_t(ap_expr_eval_ctx_t *ctx, const void *data,
 162                                 const char *arg1, const char *arg2);
 163
 164 /** String valued function, takes a string argument and returns a string
 165  * @param ctx The evaluation context
 166  * @param data An opaque context provided by the lookup hook function
 167  * @param arg The argument
 168  * @return The functions result string, may be NULL for 'empty string'
 169  */
 170 typedef const char *(ap_expr_string_func_t)(ap_expr_eval_ctx_t *ctx,
 171                                             const void *data,
 172                                             const char *arg);
 173
 174 /** List valued function, takes a string argument and returns a list of strings
 175  * Can currently only be called following the builtin '-in' operator.
 176  * @param ctx The evaluation context
 177  * @param data An opaque context provided by the lookup hook function
 178  * @param arg The argument
 179  * @return The functions result list of strings, may be NULL for 'empty array'
 180  */
 181 typedef apr_array_header_t *(ap_expr_list_func_t)(ap_expr_eval_ctx_t *ctx,
 182                                                   const void *data,
 183                                                   const char *arg);
 184
 185 /** Variable lookup function, takes no argument and returns a string
 186  * @param ctx The evaluation context
 187  * @param data An opaque context provided by the lookup hook function
 188  * @return The expanded variable
 189  */
 190 typedef const char *(ap_expr_var_func_t)(ap_expr_eval_ctx_t *ctx,
 191                                          const void *data);
 192
 193 /** parameter struct passed to the lookup hook functions */
 194 typedef struct {
 195     /** type of the looked up object */
 196     int type;
 197 #define AP_EXPR_FUNC_VAR        0
 198 #define AP_EXPR_FUNC_STRING     1
 199 #define AP_EXPR_FUNC_LIST       2
 200 #define AP_EXPR_FUNC_OP_UNARY   3
 201 #define AP_EXPR_FUNC_OP_BINARY  4
 202     /** name of the looked up object */
 203     const char *name;
 204
 205     int flags;
 206
 207     apr_pool_t *pool;
 208     apr_pool_t *ptemp;
 209
 210     /** where to store the function pointer */
 211     const void **func;
 212     /** where to store the function's context */
 213     const void **data;
 214     /** where to store the error message (if any) */
 215     const char **err;
 216
 217     /** arg for pre-parsing (only if a simple string).
 218      *  For binary ops, this is the right argument. */
 219     const char *arg;
 220 } ap_expr_lookup_parms;
 221
 222 /** Function for looking up the provider function for a variable, operator
 223  *  or function in an expression.
 224  *  @param parms The parameter struct, also determins where the result is
 225  *               stored.
 226  *  @return OK on success,
 227  *          !OK on failure,
 228  *          DECLINED if the requested name is not handled by this function
 229  */
 230 typedef int (ap_expr_lookup_fn_t)(ap_expr_lookup_parms *parms);
 231
 232 /** Default lookup function which just calls ap_run_expr_lookup().
 233  *  ap_run_expr_lookup cannot be used directly because it has the wrong
 234  *  calling convention under Windows.
 235  */
 236 AP_DECLARE_NONSTD(int) ap_expr_lookup_default(ap_expr_lookup_parms *parms);
 237
 238 AP_DECLARE_HOOK(int, expr_lookup, (ap_expr_lookup_parms *parms))
 239
 240 /**
 241  * Parse an expression into a parse tree
 242  * @param pool Pool
 243  * @param ptemp temp pool
 244  * @param info The ap_expr_info_t struct (with values filled in)
 245  * @param expr The expression string to parse
 246  * @param lookup_fn The lookup function to use, NULL for default
 247  * @return NULL on success, error message on error.
 248  *         A pointer to the resulting parse tree will be stored in
 249  *         info->root_node.
 250  */
 251 AP_DECLARE(const char *) ap_expr_parse(apr_pool_t *pool, apr_pool_t *ptemp,
 252                                        ap_expr_info_t *info, const char *expr,
 253                                        ap_expr_lookup_fn_t *lookup_fn);
 254
 255 /**
 256  * High level interface to ap_expr_parse that also creates ap_expr_info_t and
 257  * uses info from cmd_parms to fill in most of it.
 258  * @param cmd The cmd_parms struct
 259  * @param expr The expression string to parse
 260  * @param err Set to NULL on success, error message on error
 261  * @param lookup_fn The lookup function used to lookup vars, functions, and
 262  *        operators
 263  * @return The parsed expression
 264  */
 265 AP_DECLARE(ap_expr_info_t *) ap_expr_parse_cmd(const cmd_parms *cmd,
 266                                                const char *expr,
 267                                                const char **err,
 268                                                ap_expr_lookup_fn_t *lookup_fn);
 269
 270
 271  /**
 272   * Internal initialisation of ap_expr (for httpd internal use)
 273   */
 274 void ap_expr_init(apr_pool_t *pool);
 275
 276 #ifdef __cplusplus
 277 }
 278 #endif
 279
 280 #endif /* AP_EXPR_H */
 281 /** @} */