http_request.h revision f0c7e2f3f183d7c289eb176434d68a922b66a008
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd/* ====================================================================
ab2c1c1c83ec91415565da5a71fbc15d9685caa6fielding * The Apache Software License, Version 1.1
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd * Copyright (c) 2000 The Apache Software Foundation. All rights
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd * reserved.
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd * Redistribution and use in source and binary forms, with or without
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * modification, are permitted provided that the following conditions
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd * are met:
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd * 1. Redistributions of source code must retain the above copyright
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd * notice, this list of conditions and the following disclaimer.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * 2. Redistributions in binary form must reproduce the above copyright
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * notice, this list of conditions and the following disclaimer in
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * the documentation and/or other materials provided with the
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * distribution.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * 3. The end-user documentation included with the redistribution,
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * if any, must include the following acknowledgment:
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * "This product includes software developed by the
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * Apache Software Foundation (http://www.apache.org/)."
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * Alternately, this acknowledgment may appear in the software itself,
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * if and wherever such third-party acknowledgments normally appear.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * 4. The names "Apache" and "Apache Software Foundation" must
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * not be used to endorse or promote products derived from this
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * software without prior written permission. For written
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * permission, please contact apache@apache.org.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * 5. Products derived from this software may not be called "Apache",
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * nor may "Apache" appear in their name, without prior written
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * permission of the Apache Software Foundation.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * SUCH DAMAGE.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * ====================================================================
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * This software consists of voluntary contributions made by many
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * individuals on behalf of the Apache Software Foundation. For more
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * information on the Apache Software Foundation, please see
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * Portions of this software are based upon public domain software
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * originally written at the National Center for Supercomputing Applications,
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * University of Illinois, Urbana-Champaign.
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingextern "C" {
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @package Apache Request library
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding/* http_request.c is the code which handles the main line of request
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * processing, once a request has been read in (finding the right per-
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * directory configuration, building it if necessary, and calling all
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * the module dispatch functions in the right order).
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * The pieces here which are public to the modules, allow them to learn
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * how the server would handle some other file or URI, or perhaps even
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * direct the server to serve that other file instead of the one the
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * client requested directly.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * There are two ways to do that. The first is the sub_request mechanism,
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * which handles looking up files and URIs as adjuncts to some other
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * request (e.g., directory entries for multiviews and directory listings);
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * the lookup functions stop short of actually running the request, but
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * (e.g., for includes), a module may call for the request to be run
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * by calling run_sub_req. The space allocated to create sub_reqs can be
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * reclaimed by calling destroy_sub_req --- be sure to copy anything you care
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * about which was allocated in its apr_pool_t elsewhere before doing this.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * Create a sub request from the given URI. This sub request can be
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * inspected to find information about the requested URI
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param new_file The URI to lookup
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param r The current request
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @return The new request record
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @deffunc request_rec * ap_sub_req_lookup_uri(const char *new_file, const request_rec *r)
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingAP_DECLARE(request_rec *) ap_sub_req_lookup_uri(const char *new_file,
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * Create a sub request for the given file. This sub request can be
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * inspected to find information about the requested file
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param new_file The URI to lookup
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param r The current request
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @return The new request record
024cd9589e52cf11ce765dfddb5b5f0c6e421a48gstein * @deffunc request_rec * ap_sub_req_lookup_file(const char *new_file, const request_rec *r)
024cd9589e52cf11ce765dfddb5b5f0c6e421a48gsteinAP_DECLARE(request_rec *) ap_sub_req_lookup_file(const char *new_file,
024cd9589e52cf11ce765dfddb5b5f0c6e421a48gstein * Create a sub request for the given URI using a specific method. This
024cd9589e52cf11ce765dfddb5b5f0c6e421a48gstein * sub request can be inspected to find information about the requested URI
024cd9589e52cf11ce765dfddb5b5f0c6e421a48gstein * @param method The method to use in the new sub request
024cd9589e52cf11ce765dfddb5b5f0c6e421a48gstein * @param new_file The URI to lookup
024cd9589e52cf11ce765dfddb5b5f0c6e421a48gstein * @param r The current request
9625528fcf4fa27288f3be080a1979c8ef60d7dfrbb * @return The new request record
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @deffunc request_rec * ap_sub_req_method_uri(const char *method, const char *new_file, const request_rec *r)
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingAP_DECLARE(request_rec *) ap_sub_req_method_uri(const char *method,
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding const char *new_file,
ff250fa78a491f4dcf3e673f122f2d9942a7411awrowe * An output filter to strip EOS buckets from sub-requests. This always
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * has to be inserted at the end of a sub-requests filter stack.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param f The current filter
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param bb The brigade to filter
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @deffuc apr_status_t ap_sub_req_output_filter(ap_filter_t *f, ap_bucket_brigade *bb)
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingAP_CORE_DECLARE_NONSTD(apr_status_t) ap_sub_req_output_filter(ap_filter_t *f,
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * Run the handler for the sub request
ba09062ce0c7e0d6904a53aaf99896f5924b3989trawick * @param r The sub request to run
ba09062ce0c7e0d6904a53aaf99896f5924b3989trawick * @return The return code for the sub request
ba09062ce0c7e0d6904a53aaf99896f5924b3989trawick * @deffunc int ap_run_sub_req(request_rec *r)
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * Free the memory associated with a sub request
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm * @param r The sub request to finish
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @deffunc void ap_destroy_sub_req(request_rec *r)
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingAP_DECLARE(void) ap_destroy_sub_req(request_rec *r);
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * Then there's the case that you want some other request to be served
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * as the top-level request INSTEAD of what the client requested directly.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * If so, call this from a handler, and then immediately return OK.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * Redirect the current request to some other uri
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param new_uri The URI to replace the current request with
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm * @param r The current request
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @deffunc void ap_internal_redirect(const char *new_uri, request_rec *r)
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingAP_DECLARE(void) ap_internal_redirect(const char *new_uri, request_rec *r);
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * This function is designed for things like actions or CGI scripts, when
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * using AddHandler, and you want to preserve the content type across
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * an internal redirect.
ba09062ce0c7e0d6904a53aaf99896f5924b3989trawick * @param new_uri The URI to replace the current request with.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param r The current request
ba09062ce0c7e0d6904a53aaf99896f5924b3989trawick * @deffunc void ap_internal_redirect_handler(const char *new_uri, request_rec *r)
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingAP_DECLARE(void) ap_internal_redirect_handler(const char *new_uri, request_rec *r);
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * Can be used within any handler to determine if any authentication
ba09062ce0c7e0d6904a53aaf99896f5924b3989trawick * is required for the current request
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param r The current request
ba09062ce0c7e0d6904a53aaf99896f5924b3989trawick * @return 1 if authentication is required, 0 otherwise
ba09062ce0c7e0d6904a53aaf99896f5924b3989trawick * @deffunc int ap_some_auth_required(request_rec *r)
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingAP_DECLARE(int) ap_some_auth_required(request_rec *r);
ba09062ce0c7e0d6904a53aaf99896f5924b3989trawick * Determine if the current request is the main request or a sub requests
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param r The current request
ba09062ce0c7e0d6904a53aaf99896f5924b3989trawick * @retrn 1 if this is a main request, 0 otherwise
ba09062ce0c7e0d6904a53aaf99896f5924b3989trawick * @deffunc int ap_is_initial_req(request_rec *r)
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * Function to set the r->mtime field to the specified value if it's later
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * than what's already there.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param r The current request
ba09062ce0c7e0d6904a53aaf99896f5924b3989trawick * @param dependency_time Time to set the mtime to
ba09062ce0c7e0d6904a53aaf99896f5924b3989trawick * @deffunc void ap_update_mtime(request_rec *r, apr_time_t dependency_mtime)
ba09062ce0c7e0d6904a53aaf99896f5924b3989trawickAP_DECLARE(void) ap_update_mtime(request_rec *r, apr_time_t dependency_mtime);
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * Add one or more methods to the list permitted to access the resource.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * Usually executed by the content handler before the response header is
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * sent, but sometimes invoked at an earlier phase if a module knows it
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * can set the list authoritatively. Note that the methods are ADDED
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * to any already permitted unless the reset flag is non-zero. The
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * list is used to generate the Allow response header field when it
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm * is needed.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param r The pointer to the request identifying the resource.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param reset Boolean flag indicating whether this list should
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * completely replace any current settings.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param ... A NULL-terminated list of strings, each identifying a
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm * method name to add.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @return None.
066877f1a045103acfdd376d48cdd473c33f409bdougm * @deffunc void ap_allow_methods(request_rec *r, int reset, ...)
0f081398cf0eef8cc7c66a535d450110a92dc8aefieldingAP_DECLARE(void) ap_allow_methods(request_rec *r, int reset, ...);
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding/* Function called by main.c to handle first-level request */
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * Kill the current request
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param type Why the request is dieing
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param r The current request
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @deffunc void ap_die(int type, request_rec *r)
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding /* Hooks */
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * This hook allow modules an opportunity to translate the URI into an
000b67449410515eac43e76ef6667915bfd4d2abgstein * actual filename. If no modules do anything special, the server's default
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * rules will be followed.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param r The current request
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @return OK, DECLINED, or HTTP_...
10a4cdd68ef1ca0e54af296fe1d08ac00150c90bwrowe * @deffunc int ap_run_translate_name(request_rec *r)
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * This hook allows modules to check the authentication information sent with
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * the request.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param r The current request
10a4cdd68ef1ca0e54af296fe1d08ac00150c90bwrowe * @return OK, DECLINED, or HTTP_...
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @deffunc int ap_run_check_user_id(request_rec *r)
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * Allows modules to perform module-specific fixing of header fields. This
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * is invoked just before any content-handler
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param r The current request
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm * @return OK, DECLINED, or HTTP_...
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @deffunc int ap_run_fixups(request_rec *r)
066877f1a045103acfdd376d48cdd473c33f409bdougm * This routine is called to determine and/or set the various document type
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * information bits, like Content-type (via r->content_type), language, et
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param r the current request
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @return OK, DECLINED, or HTTP_...
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @deffunc int ap_run_type_checker(request_rec *r)
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * This routine is called to check for any module-specific restrictions placed
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm * upon the requested resource.
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm * @param r the current request
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @return OK, DECLINED, or HTTP_...
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @deffunc int ap_run_access_checker(request_rec *r)
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * This routine is called to check to see if the resource being requested
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * requires authorisation.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param r the current request
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @return OK, DECLINED, or HTTP_...
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @deffunc int ap_run_auth_checker(request_rec *r)
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * This hook allows modules to insert filters for the current request
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param r the current request
d9f2c22804bcbc9ad07d4ec18fbb8aa7c042dcd0bjh * @deffunc void ap_run_insert_filter(request_rec *r)
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding#endif /* !APACHE_HTTP_REQUEST_H */