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

   1 /* ====================================================================
   2  * The Apache Software License, Version 1.1
   3  *
   4  * Copyright (c) 2000-2001 The Apache Software Foundation.  All rights
   5  * reserved.
   6  *
   7  * Redistribution and use in source and binary forms, with or without
   8  * modification, are permitted provided that the following conditions
   9  * are met:
  10  *
  11  * 1. Redistributions of source code must retain the above copyright
  12  *    notice, this list of conditions and the following disclaimer.
  13  *
  14  * 2. Redistributions in binary form must reproduce the above copyright
  15  *    notice, this list of conditions and the following disclaimer in
  16  *    the documentation and/or other materials provided with the
  17  *    distribution.
  18  *
  19  * 3. The end-user documentation included with the redistribution,
  20  *    if any, must include the following acknowledgment:
  21  *       "This product includes software developed by the
  22  *        Apache Software Foundation (http://www.apache.org/)."
  23  *    Alternately, this acknowledgment may appear in the software itself,
  24  *    if and wherever such third-party acknowledgments normally appear.
  25  *
  26  * 4. The names "Apache" and "Apache Software Foundation" must
  27  *    not be used to endorse or promote products derived from this
  28  *    software without prior written permission. For written
  29  *    permission, please contact apache@apache.org.
  30  *
  31  * 5. Products derived from this software may not be called "Apache",
  32  *    nor may "Apache" appear in their name, without prior written
  33  *    permission of the Apache Software Foundation.
  34  *
  35  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46  * SUCH DAMAGE.
  47  * ====================================================================
  48  *
  49  * This software consists of voluntary contributions made by many
  50  * individuals on behalf of the Apache Software Foundation.  For more
  51  * information on the Apache Software Foundation, please see
  52  * <http://www.apache.org/>.
  53  *
  54  * Portions of this software are based upon public domain software
  55  * originally written at the National Center for Supercomputing Applications,
  56  * University of Illinois, Urbana-Champaign.
  57  */
  58
  59 #ifndef APACHE_HTTP_REQUEST_H
  60 #define APACHE_HTTP_REQUEST_H
  61
  62 #include "apr_hooks.h"
  63 #include "util_filter.h"
  64
  65 #ifdef __cplusplus
  66 extern "C" {
  67 #endif
  68
  69 /**
  70  * @file http_request.h
  71  * @brief Apache Request library
  72  */
  73
  74 /* http_request.c is the code which handles the main line of request
  75  * processing, once a request has been read in (finding the right per-
  76  * directory configuration, building it if necessary, and calling all
  77  * the module dispatch functions in the right order).
  78  *
  79  * The pieces here which are public to the modules, allow them to learn
  80  * how the server would handle some other file or URI, or perhaps even
  81  * direct the server to serve that other file instead of the one the
  82  * client requested directly.
  83  *
  84  * There are two ways to do that.  The first is the sub_request mechanism,
  85  * which handles looking up files and URIs as adjuncts to some other
  86  * request (e.g., directory entries for multiviews and directory listings);
  87  * the lookup functions stop short of actually running the request, but
  88  * (e.g., for includes), a module may call for the request to be run
  89  * by calling run_sub_req.  The space allocated to create sub_reqs can be
  90  * reclaimed by calling destroy_sub_req --- be sure to copy anything you care
  91  * about which was allocated in its apr_pool_t elsewhere before doing this.
  92  */
  93
  94 /**
  95  * Create a sub request from the given URI.  This sub request can be
  96  * inspected to find information about the requested URI
  97  * @param new_file The URI to lookup
  98  * @param r The current request
  99  * @param next_filter The first filter the sub_request should use.  If this is
 100  *                    NULL, it defaults to the first filter for the main request
 101  * @return The new request record
 102  * @deffunc request_rec * ap_sub_req_lookup_uri(const char *new_file, const request_rec *r)
 103  */
 104 AP_DECLARE(request_rec *) ap_sub_req_lookup_uri(const char *new_file,
 105                                                 const request_rec *r,
 106                                                 ap_filter_t *next_filter);
 107
 108 /**
 109  * Create a sub request for the given file.  This sub request can be
 110  * inspected to find information about the requested file
 111  * @param new_file The URI to lookup
 112  * @param r The current request
 113  * @param next_filter The first filter the sub_request should use.  If this is
 114  *                    NULL, it defaults to the first filter for the main request
 115  * @return The new request record
 116  * @deffunc request_rec * ap_sub_req_lookup_file(const char *new_file, const request_rec *r)
 117  */
 118 AP_DECLARE(request_rec *) ap_sub_req_lookup_file(const char *new_file,
 119                                               const request_rec *r,
 120                                               ap_filter_t *next_filter);
 121 /**
 122  * Create a sub request for the given URI using a specific method.  This
 123  * sub request can be inspected to find information about the requested URI
 124  * @param method The method to use in the new sub request
 125  * @param new_file The URI to lookup
 126  * @param r The current request
 127  * @param next_filter The first filter the sub_request should use.  If this is
 128  *                    NULL, it defaults to the first filter for the main request
 129  * @return The new request record
 130  * @deffunc request_rec * ap_sub_req_method_uri(const char *method, const char *new_file, const request_rec *r)
 131  */
 132 AP_DECLARE(request_rec *) ap_sub_req_method_uri(const char *method,
 133                                                 const char *new_file,
 134                                                 const request_rec *r,
 135                                                 ap_filter_t *next_filter);
 136 /**
 137  * An output filter to strip EOS buckets from sub-requests.  This always
 138  * has to be inserted at the end of a sub-requests filter stack.
 139  * @param f The current filter
 140  * @param bb The brigade to filter
 141  * @deffunc apr_status_t ap_sub_req_output_filter(ap_filter_t *f, apr_bucket_brigade *bb)
 142  */
 143 AP_CORE_DECLARE_NONSTD(apr_status_t) ap_sub_req_output_filter(ap_filter_t *f,
 144                                                         apr_bucket_brigade *bb);
 145
 146 /**
 147  * Run the handler for the sub request
 148  * @param r The sub request to run
 149  * @return The return code for the sub request
 150  * @deffunc int ap_run_sub_req(request_rec *r)
 151  */
 152 AP_DECLARE(int) ap_run_sub_req(request_rec *r);
 153
 154 /**
 155  * Free the memory associated with a sub request
 156  * @param r The sub request to finish
 157  * @deffunc void ap_destroy_sub_req(request_rec *r)
 158  */
 159 AP_DECLARE(void) ap_destroy_sub_req(request_rec *r);
 160
 161 /*
 162  * Then there's the case that you want some other request to be served
 163  * as the top-level request INSTEAD of what the client requested directly.
 164  * If so, call this from a handler, and then immediately return OK.
 165  */
 166
 167 /**
 168  * Redirect the current request to some other uri
 169  * @param new_uri The URI to replace the current request with
 170  * @param r The current request
 171  * @deffunc void ap_internal_redirect(const char *new_uri, request_rec *r)
 172  */
 173 AP_DECLARE(void) ap_internal_redirect(const char *new_uri, request_rec *r);
 174
 175 /**
 176  * This function is designed for things like actions or CGI scripts, when
 177  * using AddHandler, and you want to preserve the content type across
 178  * an internal redirect.
 179  * @param new_uri The URI to replace the current request with.
 180  * @param r The current request
 181  * @deffunc void ap_internal_redirect_handler(const char *new_uri, request_rec *r)
 182  */
 183 AP_DECLARE(void) ap_internal_redirect_handler(const char *new_uri, request_rec *r);
 184
 185 /**
 186  * Can be used within any handler to determine if any authentication
 187  * is required for the current request
 188  * @param r The current request
 189  * @return 1 if authentication is required, 0 otherwise
 190  * @deffunc int ap_some_auth_required(request_rec *r)
 191  */
 192 AP_DECLARE(int) ap_some_auth_required(request_rec *r);
 193
 194 /**
 195  * Determine if the current request is the main request or a sub requests
 196  * @param r The current request
 197  * @retrn 1 if this is a main request, 0 otherwise
 198  * @deffunc int ap_is_initial_req(request_rec *r)
 199  */
 200 AP_DECLARE(int) ap_is_initial_req(request_rec *r);
 201
 202 /**
 203  * Function to set the r->mtime field to the specified value if it's later
 204  * than what's already there.
 205  * @param r The current request
 206  * @param dependency_time Time to set the mtime to
 207  * @deffunc void ap_update_mtime(request_rec *r, apr_time_t dependency_mtime)
 208  */
 209 AP_DECLARE(void) ap_update_mtime(request_rec *r, apr_time_t dependency_mtime);
 210
 211 /**
 212  * Add one or more methods to the list permitted to access the resource.
 213  * Usually executed by the content handler before the response header is
 214  * sent, but sometimes invoked at an earlier phase if a module knows it
 215  * can set the list authoritatively.  Note that the methods are ADDED
 216  * to any already permitted unless the reset flag is non-zero.  The
 217  * list is used to generate the Allow response header field when it
 218  * is needed.
 219  * @param   r     The pointer to the request identifying the resource.
 220  * @param   reset Boolean flag indicating whether this list should
 221  *                completely replace any current settings.
 222  * @param   ...   A NULL-terminated list of strings, each identifying a
 223  *                method name to add.
 224  * @return  None.
 225  * @deffunc void ap_allow_methods(request_rec *r, int reset, ...)
 226  */
 227 AP_DECLARE(void) ap_allow_methods(request_rec *r, int reset, ...);
 228
 229 #define MERGE_ALLOW 0
 230 #define REPLACE_ALLOW 1
 231
 232 #ifdef CORE_PRIVATE
 233 /* Function called by main.c to handle first-level request */
 234 void ap_process_request(request_rec *);
 235 /**
 236  * Kill the current request
 237  * @param type Why the request is dieing
 238  * @param r The current request
 239  * @deffunc void ap_die(int type, request_rec *r)
 240  */
 241 AP_DECLARE(void) ap_die(int type, request_rec *r);
 242 #endif
 243
 244 /* Hooks */
 245
 246 /* XXX: doxygen grouping doesn't appear to work, but it should. Checking with
 247  * doxygen (Ben).
 248  */
 249
 250 /**
 251  * This hook allow modules an opportunity to translate the URI into an
 252  * actual filename.  If no modules do anything special, the server's default
 253  * rules will be followed.
 254  * @param r The current request
 255  * @return OK, DECLINED, or HTTP_...
 256  * @ingroup hooks
 257  */
 258 AP_DECLARE_HOOK(int,translate_name,(request_rec *r))
 259
 260 /**
 261  * This hook allows modules to check the authentication information sent with
 262  * the request.
 263  * @param r The current request
 264  * @return OK, DECLINED, or HTTP_...
 265  * @ingroup hooks
 266  */
 267 AP_DECLARE_HOOK(int,check_user_id,(request_rec *r))
 268
 269 /**
 270  * Allows modules to perform module-specific fixing of header fields.  This
 271  * is invoked just before any content-handler
 272  * @param r The current request
 273  * @return OK, DECLINED, or HTTP_...
 274  * @ingroup hooks
 275  */
 276 AP_DECLARE_HOOK(int,fixups,(request_rec *r))
 277
 278 /**
 279  * This routine is called to determine and/or set the various document type
 280  * information bits, like Content-type (via r->content_type), language, et
 281  * cetera.
 282  * @param r the current request
 283  * @return OK, DECLINED, or HTTP_...
 284  * @ingroup hooks
 285  */
 286 AP_DECLARE_HOOK(int,type_checker,(request_rec *r))
 287
 288 /**
 289  * This routine is called to check for any module-specific restrictions placed
 290  * upon the requested resource.
 291  * @param r the current request
 292  * @return OK, DECLINED, or HTTP_...
 293  * @ingroup hooks
 294  */
 295 AP_DECLARE_HOOK(int,access_checker,(request_rec *r))
 296
 297 /**
 298  * This routine is called to check to see if the resource being requested
 299  * requires authorisation.
 300  * @param r the current request
 301  * @return OK, DECLINED, or HTTP_...
 302  * @ingroup hooks
 303  */
 304 AP_DECLARE_HOOK(int,auth_checker,(request_rec *r))
 305
 306 /**
 307  * This hook allows modules to insert filters for the current request
 308  * @param r the current request
 309  * @ingroup hooks
 310  */
 311 AP_DECLARE_HOOK(void,insert_filter,(request_rec *r))
 312
 313 AP_DECLARE(int) directory_walk(request_rec *r);
 314 AP_DECLARE(int) location_walk(request_rec *r);
 315 AP_DECLARE(int) file_walk(request_rec *r);
 316
 317 #ifdef __cplusplus
 318 }
 319 #endif
 320
 321 #endif  /* !APACHE_HTTP_REQUEST_H */