Annotation of win32/apache22/include/http_request.h, revision 1.1
1.1 ! moko 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 http_request.h
! 19: * @brief Apache Request library
! 20: *
! 21: * request.c is the code which handles the main line of request
! 22: * processing, once a request has been read in (finding the right per-
! 23: * directory configuration, building it if necessary, and calling all
! 24: * the module dispatch functions in the right order).
! 25: *
! 26: * The pieces here which are public to the modules, allow them to learn
! 27: * how the server would handle some other file or URI, or perhaps even
! 28: * direct the server to serve that other file instead of the one the
! 29: * client requested directly.
! 30: *
! 31: * There are two ways to do that. The first is the sub_request mechanism,
! 32: * which handles looking up files and URIs as adjuncts to some other
! 33: * request (e.g., directory entries for multiviews and directory listings);
! 34: * the lookup functions stop short of actually running the request, but
! 35: * (e.g., for includes), a module may call for the request to be run
! 36: * by calling run_sub_req. The space allocated to create sub_reqs can be
! 37: * reclaimed by calling destroy_sub_req --- be sure to copy anything you care
! 38: * about which was allocated in its apr_pool_t elsewhere before doing this.
! 39: */
! 40:
! 41: #ifndef APACHE_HTTP_REQUEST_H
! 42: #define APACHE_HTTP_REQUEST_H
! 43:
! 44: #include "apr_hooks.h"
! 45: #include "util_filter.h"
! 46:
! 47: #ifdef __cplusplus
! 48: extern "C" {
! 49: #endif
! 50:
! 51: #define AP_SUBREQ_NO_ARGS 0
! 52: #define AP_SUBREQ_MERGE_ARGS 1
! 53:
! 54: /**
! 55: * An internal handler used by the ap_process_request, all subrequest mechanisms
! 56: * and the redirect mechanism.
! 57: * @param r The request, subrequest or internal redirect to pre-process
! 58: * @return The return code for the request
! 59: */
! 60: AP_DECLARE(int) ap_process_request_internal(request_rec *r);
! 61:
! 62: /**
! 63: * Create a subrequest from the given URI. This subrequest can be
! 64: * inspected to find information about the requested URI
! 65: * @param new_uri The URI to lookup
! 66: * @param r The current request
! 67: * @param next_filter The first filter the sub_request should use. If this is
! 68: * NULL, it defaults to the first filter for the main request
! 69: * @return The new request record
! 70: */
! 71: AP_DECLARE(request_rec *) ap_sub_req_lookup_uri(const char *new_uri,
! 72: const request_rec *r,
! 73: ap_filter_t *next_filter);
! 74:
! 75: /**
! 76: * Create a subrequest for the given file. This subrequest can be
! 77: * inspected to find information about the requested file
! 78: * @param new_file The file to lookup
! 79: * @param r The current request
! 80: * @param next_filter The first filter the sub_request should use. If this is
! 81: * NULL, it defaults to the first filter for the main request
! 82: * @return The new request record
! 83: */
! 84: AP_DECLARE(request_rec *) ap_sub_req_lookup_file(const char *new_file,
! 85: const request_rec *r,
! 86: ap_filter_t *next_filter);
! 87: /**
! 88: * Create a subrequest for the given apr_dir_read result. This subrequest
! 89: * can be inspected to find information about the requested file
! 90: * @param finfo The apr_dir_read result to lookup
! 91: * @param r The current request
! 92: * @param subtype What type of subrequest to perform, one of;
! 93: * <PRE>
! 94: * AP_SUBREQ_NO_ARGS ignore r->args and r->path_info
! 95: * AP_SUBREQ_MERGE_ARGS merge r->args and r->path_info
! 96: * </PRE>
! 97: * @param next_filter The first filter the sub_request should use. If this is
! 98: * NULL, it defaults to the first filter for the main request
! 99: * @return The new request record
! 100: * @note The apr_dir_read flags value APR_FINFO_MIN|APR_FINFO_NAME flag is the
! 101: * minimum recommended query if the results will be passed to apr_dir_read.
! 102: * The file info passed must include the name, and must have the same relative
! 103: * directory as the current request.
! 104: */
! 105: AP_DECLARE(request_rec *) ap_sub_req_lookup_dirent(const apr_finfo_t *finfo,
! 106: const request_rec *r,
! 107: int subtype,
! 108: ap_filter_t *next_filter);
! 109: /**
! 110: * Create a subrequest for the given URI using a specific method. This
! 111: * subrequest can be inspected to find information about the requested URI
! 112: * @param method The method to use in the new subrequest
! 113: * @param new_uri The URI to lookup
! 114: * @param r The current request
! 115: * @param next_filter The first filter the sub_request should use. If this is
! 116: * NULL, it defaults to the first filter for the main request
! 117: * @return The new request record
! 118: */
! 119: AP_DECLARE(request_rec *) ap_sub_req_method_uri(const char *method,
! 120: const char *new_uri,
! 121: const request_rec *r,
! 122: ap_filter_t *next_filter);
! 123: /**
! 124: * An output filter to strip EOS buckets from sub-requests. This always
! 125: * has to be inserted at the end of a sub-requests filter stack.
! 126: * @param f The current filter
! 127: * @param bb The brigade to filter
! 128: * @return status code
! 129: */
! 130: AP_CORE_DECLARE_NONSTD(apr_status_t) ap_sub_req_output_filter(ap_filter_t *f,
! 131: apr_bucket_brigade *bb);
! 132:
! 133: /**
! 134: * Run the handler for the subrequest
! 135: * @param r The subrequest to run
! 136: * @return The return code for the subrequest
! 137: */
! 138: AP_DECLARE(int) ap_run_sub_req(request_rec *r);
! 139:
! 140: /**
! 141: * Free the memory associated with a subrequest
! 142: * @param r The subrequest to finish
! 143: */
! 144: AP_DECLARE(void) ap_destroy_sub_req(request_rec *r);
! 145:
! 146: /*
! 147: * Then there's the case that you want some other request to be served
! 148: * as the top-level request INSTEAD of what the client requested directly.
! 149: * If so, call this from a handler, and then immediately return OK.
! 150: */
! 151:
! 152: /**
! 153: * Redirect the current request to some other uri
! 154: * @param new_uri The URI to replace the current request with
! 155: * @param r The current request
! 156: */
! 157: AP_DECLARE(void) ap_internal_redirect(const char *new_uri, request_rec *r);
! 158:
! 159: /**
! 160: * This function is designed for things like actions or CGI scripts, when
! 161: * using AddHandler, and you want to preserve the content type across
! 162: * an internal redirect.
! 163: * @param new_uri The URI to replace the current request with.
! 164: * @param r The current request
! 165: */
! 166: AP_DECLARE(void) ap_internal_redirect_handler(const char *new_uri, request_rec *r);
! 167:
! 168: /**
! 169: * Redirect the current request to a sub_req, merging the pools
! 170: * @param sub_req A subrequest created from this request
! 171: * @param r The current request
! 172: * @note the sub_req's pool will be merged into r's pool, be very careful
! 173: * not to destroy this subrequest, it will be destroyed with the main request!
! 174: */
! 175: AP_DECLARE(void) ap_internal_fast_redirect(request_rec *sub_req, request_rec *r);
! 176:
! 177: /**
! 178: * Can be used within any handler to determine if any authentication
! 179: * is required for the current request
! 180: * @param r The current request
! 181: * @return 1 if authentication is required, 0 otherwise
! 182: */
! 183: AP_DECLARE(int) ap_some_auth_required(request_rec *r);
! 184:
! 185: /**
! 186: * Determine if the current request is the main request or a subrequest
! 187: * @param r The current request
! 188: * @return 1 if this is the main request, 0 otherwise
! 189: */
! 190: AP_DECLARE(int) ap_is_initial_req(request_rec *r);
! 191:
! 192: /**
! 193: * Function to set the r->mtime field to the specified value if it's later
! 194: * than what's already there.
! 195: * @param r The current request
! 196: * @param dependency_mtime Time to set the mtime to
! 197: */
! 198: AP_DECLARE(void) ap_update_mtime(request_rec *r, apr_time_t dependency_mtime);
! 199:
! 200: /**
! 201: * Add one or more methods to the list permitted to access the resource.
! 202: * Usually executed by the content handler before the response header is
! 203: * sent, but sometimes invoked at an earlier phase if a module knows it
! 204: * can set the list authoritatively. Note that the methods are ADDED
! 205: * to any already permitted unless the reset flag is non-zero. The
! 206: * list is used to generate the Allow response header field when it
! 207: * is needed.
! 208: * @param r The pointer to the request identifying the resource.
! 209: * @param reset Boolean flag indicating whether this list should
! 210: * completely replace any current settings.
! 211: * @param ... A NULL-terminated list of strings, each identifying a
! 212: * method name to add.
! 213: * @return None.
! 214: */
! 215: AP_DECLARE(void) ap_allow_methods(request_rec *r, int reset, ...);
! 216:
! 217: /**
! 218: * Add one or more methods to the list permitted to access the resource.
! 219: * Usually executed by the content handler before the response header is
! 220: * sent, but sometimes invoked at an earlier phase if a module knows it
! 221: * can set the list authoritatively. Note that the methods are ADDED
! 222: * to any already permitted unless the reset flag is non-zero. The
! 223: * list is used to generate the Allow response header field when it
! 224: * is needed.
! 225: * @param r The pointer to the request identifying the resource.
! 226: * @param reset Boolean flag indicating whether this list should
! 227: * completely replace any current settings.
! 228: * @param ... A list of method identifiers, from the "M_" series
! 229: * defined in httpd.h, terminated with a value of -1
! 230: * (e.g., "M_GET, M_POST, M_OPTIONS, -1")
! 231: * @return None.
! 232: */
! 233: AP_DECLARE(void) ap_allow_standard_methods(request_rec *r, int reset, ...);
! 234:
! 235: #define MERGE_ALLOW 0
! 236: #define REPLACE_ALLOW 1
! 237:
! 238: #ifdef CORE_PRIVATE
! 239: /**
! 240: * Function called by main.c to handle first-level request
! 241: * @param r The current request
! 242: */
! 243: void ap_process_request(request_rec *);
! 244:
! 245: /**
! 246: * Kill the current request
! 247: * @param type Why the request is dieing
! 248: * @param r The current request
! 249: */
! 250: AP_DECLARE(void) ap_die(int type, request_rec *r);
! 251: #endif
! 252:
! 253: /* Hooks */
! 254:
! 255: /**
! 256: * Gives modules a chance to create their request_config entry when the
! 257: * request is created.
! 258: * @param r The current request
! 259: * @ingroup hooks
! 260: */
! 261: AP_DECLARE_HOOK(int,create_request,(request_rec *r))
! 262:
! 263: /**
! 264: * This hook allow modules an opportunity to translate the URI into an
! 265: * actual filename. If no modules do anything special, the server's default
! 266: * rules will be followed.
! 267: * @param r The current request
! 268: * @return OK, DECLINED, or HTTP_...
! 269: * @ingroup hooks
! 270: */
! 271: AP_DECLARE_HOOK(int,translate_name,(request_rec *r))
! 272:
! 273: /**
! 274: * This hook allow modules to set the per_dir_config based on their own
! 275: * context (such as "<Proxy>" sections) and responds to contextless requests
! 276: * such as TRACE that need no security or filesystem mapping.
! 277: * based on the filesystem.
! 278: * @param r The current request
! 279: * @return DONE (or HTTP_) if this contextless request was just fulfilled
! 280: * (such as TRACE), OK if this is not a file, and DECLINED if this is a file.
! 281: * The core map_to_storage (HOOK_RUN_REALLY_LAST) will directory_walk
! 282: * and file_walk the r->filename.
! 283: *
! 284: * @ingroup hooks
! 285: */
! 286: AP_DECLARE_HOOK(int,map_to_storage,(request_rec *r))
! 287:
! 288: /**
! 289: * This hook is used to analyze the request headers, authenticate the user,
! 290: * and set the user information in the request record (r->user and
! 291: * r->ap_auth_type). This hook is only run when Apache determines that
! 292: * authentication/authorization is required for this resource (as determined
! 293: * by the 'Require' directive). It runs after the access_checker hook, and
! 294: * before the auth_checker hook.
! 295: *
! 296: * @param r The current request
! 297: * @return OK, DECLINED, or HTTP_...
! 298: * @ingroup hooks
! 299: */
! 300: AP_DECLARE_HOOK(int,check_user_id,(request_rec *r))
! 301:
! 302: /**
! 303: * Allows modules to perform module-specific fixing of header fields. This
! 304: * is invoked just before any content-handler
! 305: * @param r The current request
! 306: * @return OK, DECLINED, or HTTP_...
! 307: * @ingroup hooks
! 308: */
! 309: AP_DECLARE_HOOK(int,fixups,(request_rec *r))
! 310:
! 311: /**
! 312: * This routine is called to determine and/or set the various document type
! 313: * information bits, like Content-type (via r->content_type), language, et
! 314: * cetera.
! 315: * @param r the current request
! 316: * @return OK, DECLINED, or HTTP_...
! 317: * @ingroup hooks
! 318: */
! 319: AP_DECLARE_HOOK(int,type_checker,(request_rec *r))
! 320:
! 321: /**
! 322: * This hook is used to apply additional access control to this resource.
! 323: * It runs *before* a user is authenticated, so this hook is really to
! 324: * apply additional restrictions independent of a user. It also runs
! 325: * independent of 'Require' directive usage.
! 326: *
! 327: * @param r the current request
! 328: * @return OK, DECLINED, or HTTP_...
! 329: * @ingroup hooks
! 330: */
! 331: AP_DECLARE_HOOK(int,access_checker,(request_rec *r))
! 332:
! 333: /**
! 334: * This hook is used to check to see if the resource being requested
! 335: * is available for the authenticated user (r->user and r->ap_auth_type).
! 336: * It runs after the access_checker and check_user_id hooks. Note that
! 337: * it will *only* be called if Apache determines that access control has
! 338: * been applied to this resource (through a 'Require' directive).
! 339: *
! 340: * @param r the current request
! 341: * @return OK, DECLINED, or HTTP_...
! 342: * @ingroup hooks
! 343: */
! 344: AP_DECLARE_HOOK(int,auth_checker,(request_rec *r))
! 345:
! 346: /**
! 347: * This hook allows modules to insert filters for the current request
! 348: * @param r the current request
! 349: * @ingroup hooks
! 350: */
! 351: AP_DECLARE_HOOK(void,insert_filter,(request_rec *r))
! 352:
! 353: AP_DECLARE(int) ap_location_walk(request_rec *r);
! 354: AP_DECLARE(int) ap_directory_walk(request_rec *r);
! 355: AP_DECLARE(int) ap_file_walk(request_rec *r);
! 356:
! 357: #ifdef __cplusplus
! 358: }
! 359: #endif
! 360:
! 361: #endif /* !APACHE_HTTP_REQUEST_H */
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to http_request.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / win32 / apache22 / include