granicus.if.org Git - apache/blob - include/util_script.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  util_script.h
  19  * @brief Apache script tools
  20  *
  21  * @defgroup APACHE_CORE_SCRIPT Script Tools
  22  * @ingroup  APACHE_CORE
  23  * @{
  24  */
  25
  26 #ifndef APACHE_UTIL_SCRIPT_H
  27 #define APACHE_UTIL_SCRIPT_H
  28
  29 #include "apr_buckets.h"
  30 #include "ap_config.h"
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 #ifndef APACHE_ARG_MAX
  37 #ifdef _POSIX_ARG_MAX
  38 #define APACHE_ARG_MAX _POSIX_ARG_MAX
  39 #else
  40 #define APACHE_ARG_MAX 512
  41 #endif
  42 #endif
  43
  44 /**
  45  * Create an environment variable out of an Apache table of key-value pairs
  46  * @param p pool to allocate out of
  47  * @param t Apache table of key-value pairs
  48  * @return An array containing the same key-value pairs suitable for
  49  *         use with an exec call.
  50  * @fn char **ap_create_environment(apr_pool_t *p, apr_table_t *t)
  51  */
  52 AP_DECLARE(char **) ap_create_environment(apr_pool_t *p, apr_table_t *t);
  53
  54 /**
  55  * This "cute" little function comes about because the path info on
  56  * filenames and URLs aren't always the same. So we take the two,
  57  * and find as much of the two that match as possible.
  58  * @param uri The uri we are currently parsing
  59  * @param path_info The current path info
  60  * @return The length of the path info
  61  * @fn int ap_find_path_info(const char *uri, const char *path_info)
  62  */
  63 AP_DECLARE(int) ap_find_path_info(const char *uri, const char *path_info);
  64
  65 /**
  66  * Add CGI environment variables required by HTTP/1.1 to the request's
  67  * environment table
  68  * @param r the current request
  69  * @fn void ap_add_cgi_vars(request_rec *r)
  70  */
  71 AP_DECLARE(void) ap_add_cgi_vars(request_rec *r);
  72
  73 /**
  74  * Add common CGI environment variables to the requests environment table
  75  * @param r The current request
  76  * @fn void ap_add_common_vars(request_rec *r)
  77  */
  78 AP_DECLARE(void) ap_add_common_vars(request_rec *r);
  79
  80 /**
  81  * Read headers output from a script, ensuring that the output is valid.  If
  82  * the output is valid, then the headers are added to the headers out of the
  83  * current request. If the request method is GET or HEAD and the script's
  84  * response will not meet the request's HTTP conditions, a conditional status
  85  * code is returned.
  86  * @param r The current request
  87  * @param f The file to read from
  88  * @param buffer Empty when calling the function.  On output, if there was an
  89  *               error, the string that cause the error is stored here.
  90  * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR or other 5xx status
  91  *         code on failure, or a conditional status code (HTTP_NOT_MODIFIED or
  92  *         HTTP_PRECONDITION_FAILED) to indicate that the script's response does
  93  *         not meet the request's conditions
  94  * @fn int ap_scan_script_header_err(request_rec *r, apr_file_t *f, char *buffer)
  95  */
  96 AP_DECLARE(int) ap_scan_script_header_err(request_rec *r, apr_file_t *f, char *buffer);
  97
  98 /**
  99  * Read headers output from a script, ensuring that the output is valid.  If
 100  * the output is valid, then the headers are added to the headers out of the
 101  * current request. If the request method is GET or HEAD and the script's
 102  * response will not meet the request's HTTP conditions, a conditional status
 103  * code is returned.
 104  * @param r The current request
 105  * @param f The file to read from
 106  * @param buffer Empty when calling the function.  On output, if there was an
 107  *               error, the string that cause the error is stored here.
 108  * @param module_index The module index to be used for logging
 109  * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR or other 5xx status
 110  *         code on failure, or a conditional status code (HTTP_NOT_MODIFIED or
 111  *         HTTP_PRECONDITION_FAILED) to indicate that the script's response does
 112  *         not meet the request's conditions
 113  */
 114 AP_DECLARE(int) ap_scan_script_header_err_ex(request_rec *r, apr_file_t *f,
 115                                              char *buffer, int module_index);
 116
 117
 118 /**
 119  * Read headers output from a script, ensuring that the output is valid.  If
 120  * the output is valid, then the headers are added to the headers out of the
 121  * current request. If the request method is GET or HEAD and the script's
 122  * response will not meet the request's HTTP conditions, a conditional status
 123  * code is returned.
 124  * @param r The current request
 125  * @param bb The brigade from which to read
 126  * @param buffer Empty when calling the function.  On output, if there was an
 127  *               error, the string that cause the error is stored here.
 128  * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR or other 5xx status
 129  *         code on failure, or a conditional status code (HTTP_NOT_MODIFIED or
 130  *         HTTP_PRECONDITION_FAILED) to indicate that the script's response does
 131  *         not meet the request's conditions
 132  * @fn int ap_scan_script_header_err_brigade(request_rec *r, apr_bucket_brigade *bb, char *buffer)
 133  */
 134 AP_DECLARE(int) ap_scan_script_header_err_brigade(request_rec *r,
 135                                                   apr_bucket_brigade *bb,
 136                                                   char *buffer);
 137
 138 /**
 139  * Read headers output from a script, ensuring that the output is valid.  If
 140  * the output is valid, then the headers are added to the headers out of the
 141  * current request. If the request method is GET or HEAD and the script's
 142  * response will not meet the request's HTTP conditions, a conditional status
 143  * code is returned.
 144  * @param r The current request
 145  * @param bb The brigade from which to read
 146  * @param buffer Empty when calling the function.  On output, if there was an
 147  *               error, the string that cause the error is stored here.
 148  * @param module_index The module index to be used for logging
 149  * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR or other 5xx status
 150  *         code on failure, or a conditional status code (HTTP_NOT_MODIFIED or
 151  *         HTTP_PRECONDITION_FAILED) to indicate that the script's response does
 152  *         not meet the request's conditions
 153  */
 154 AP_DECLARE(int) ap_scan_script_header_err_brigade_ex(request_rec *r,
 155                                                      apr_bucket_brigade *bb,
 156                                                      char *buffer,
 157                                                      int module_index);
 158
 159 /**
 160  * Read headers strings from a script, ensuring that the output is valid.  If
 161  * the output is valid, then the headers are added to the headers out of the
 162  * current request. If the request method is GET or HEAD and the script's
 163  * response will not meet the request's HTTP conditions, a conditional status
 164  * code is returned.
 165  * @param r The current request
 166  * @param buffer Empty when calling the function.  On output, if there was an
 167  *               error, the string that cause the error is stored here.
 168  * @param termch Pointer to the last character parsed.
 169  * @param termarg Pointer to an int to capture the last argument parsed.
 170  *
 171  * The varargs are string arguments to parse consecutively for headers,
 172  * with a NULL argument to terminate the list.
 173  *
 174  * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR or other 5xx status
 175  *         code on failure, or a conditional status code (HTTP_NOT_MODIFIED or
 176  *         HTTP_PRECONDITION_FAILED) to indicate that the script's response does
 177  *         not meet the request's conditions
 178  */
 179 AP_DECLARE_NONSTD(int) ap_scan_script_header_err_strs(request_rec *r,
 180                                                       char *buffer,
 181                                                       const char **termch,
 182                                                       int *termarg, ...)
 183                        AP_FN_ATTR_SENTINEL;
 184
 185 /**
 186  * Read headers strings from a script, ensuring that the output is valid.  If
 187  * the output is valid, then the headers are added to the headers out of the
 188  * current request. If the request method is GET or HEAD and the script's
 189  * response will not meet the request's HTTP conditions, a conditional status
 190  * code is returned.
 191  * @param r The current request
 192  * @param buffer Empty when calling the function.  On output, if there was an
 193  *               error, the string that cause the error is stored here.
 194  * @param module_index The module index to be used for logging
 195  * @param termch Pointer to the last character parsed.
 196  * @param termarg Pointer to an int to capture the last argument parsed.
 197  *
 198  * The varargs are string arguments to parse consecutively for headers,
 199  * with a NULL argument to terminate the list.
 200  *
 201  * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR or other 5xx status
 202  *         code on failure, or a conditional status code (HTTP_NOT_MODIFIED or
 203  *         HTTP_PRECONDITION_FAILED) to indicate that the script's response does
 204  *         not meet the request's conditions
 205  */
 206 AP_DECLARE_NONSTD(int) ap_scan_script_header_err_strs_ex(request_rec *r,
 207                                                          char *buffer,
 208                                                          int module_index,
 209                                                          const char **termch,
 210                                                          int *termarg, ...)
 211                        AP_FN_ATTR_SENTINEL;
 212
 213
 214 /**
 215  * Read headers output from a script, ensuring that the output is valid.  If
 216  * the output is valid, then the headers are added to the headers out of the
 217  * current request. If the request method is GET or HEAD and the script's
 218  * response will not meet the request's HTTP conditions, a conditional status
 219  * code is returned.
 220  * @param r The current request
 221  * @param buffer Empty when calling the function.  On output, if there was an
 222  *               error, the string that cause the error is stored here.
 223  * @param getsfunc Function to read the headers from.  This function should
 224                    act like gets()
 225  * @param getsfunc_data The place to read from
 226  * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR or other 5xx status
 227  *         code on failure, or a conditional status code (HTTP_NOT_MODIFIED or
 228  *         HTTP_PRECONDITION_FAILED) to indicate that the script's response does
 229  *         not meet the request's conditions
 230  */
 231 AP_DECLARE(int) ap_scan_script_header_err_core(request_rec *r, char *buffer,
 232                                                int (*getsfunc) (char *, int, void *),
 233                                                void *getsfunc_data);
 234
 235 /**
 236  * Read headers output from a script, ensuring that the output is valid.  If
 237  * the output is valid, then the headers are added to the headers out of the
 238  * current request. If the request method is GET or HEAD and the script's
 239  * response will not meet the request's HTTP conditions, a conditional status
 240  * code is returned.
 241  * @param r The current request
 242  * @param buffer Empty when calling the function.  On output, if there was an
 243  *               error, the string that cause the error is stored here.
 244  * @param getsfunc Function to read the headers from.  This function should
 245                    act like gets()
 246  * @param getsfunc_data The place to read from
 247  * @param module_index The module index to be used for logging
 248  * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR or other 5xx status
 249  *         code on failure, or a conditional status code (HTTP_NOT_MODIFIED or
 250  *         HTTP_PRECONDITION_FAILED) to indicate that the script's response does
 251  *         not meet the request's conditions
 252  */
 253 AP_DECLARE(int) ap_scan_script_header_err_core_ex(request_rec *r, char *buffer,
 254                                         int (*getsfunc) (char *, int, void *),
 255                                         void *getsfunc_data, int module_index);
 256
 257
 258 /**
 259  * Parse query args for the request and store in a new table allocated
 260  * from the request pool.
 261  * For args with no value, "1" will be used instead.
 262  * If no query args were specified, the table will be empty.
 263  * @param r The current request
 264  * @param table A new table on output.
 265  */
 266 AP_DECLARE(void) ap_args_to_table(request_rec *r, apr_table_t **table);
 267
 268 #ifdef __cplusplus
 269 }
 270 #endif
 271
 272 #endif  /* !APACHE_UTIL_SCRIPT_H */
 273 /** @} */