Some of the comments were out of order or incomplete in
mod_exmple.c. It was also missing ap_hook_create_request()
This brings it up to date a bit.
Sorry if this is kinda trivial, I'm probably going to generate a lot
more silly fixes like this. Let me know if there's an optimal
way/time for stuff like this.
-bmd
--- mod_example.c.old Fri Jun 14 15:54:56 2002
+++ mod_example.c Fri Jun 14 17:15:21 2002
@@ -657,31 +657,6 @@
/* see the individual handler comments below for details. */
/* */
/*--------------------------------------------------------------------------*/
-/*
- * This function is called during server initialisation. Any information
- * that needs to be recorded must be in static cells, since there's no
- * configuration record.
- *
- * There is no return value.
- */
-
-/*
- * This function is called when an heavy-weight process (such as a child) is
- * being run down or destroyed. As with the child initialisation function,
- * any information that needs to be recorded must be in static cells, since
- * there's no configuration record.
- *
- * There is no return value.
- */
-
-/*
- * This function is called during server initialisation when an heavy-weight
- * process (such as a child) is being initialised. As with the
- * module initialisation function, any information that needs to be recorded
- * must be in static cells, since there's no configuration record.
- *
- * There is no return value.
- */
/*
* This function gets called to create a per-directory configuration
@@ -844,8 +819,14 @@
}
/*
- * This routine is called before the server processes the configuration
- * files. There is no return value.
+ * This routine was registered by ap_hook_pre_config()
+ *
+ * It is called before the server processes the configuration files
+ * during server initialisation. Any information that needs to be
+ * recorded must be in static cells, since there's no configuration
+ * record.
+ *
+ * The return value must be OK or apache will not start up.
*/
static int x_pre_config(apr_pool_t *pconf, apr_pool_t *plog,
apr_pool_t *ptemp)
@@ -859,12 +840,11 @@
}
/*
- * This routine is called to perform any module-specific fixing of header
- * fields, et cetera. It is invoked just before any content-handler.
+ * This routine is registered by ap_hook_post_config()
+ * It is called just after the server processes the configuration
+ * files. It is mostly analogous to old apache _init routines.
*
- * The return value is OK, DECLINED, or HTTP_mumble. If we return OK, the
- * server will still call any remaining modules with an handler for this
- * phase.
+ * The return value must be OK or apache will not start up.
*/
static int x_post_config(apr_pool_t *pconf, apr_pool_t *plog,
apr_pool_t *ptemp, server_rec *s)
@@ -877,12 +857,13 @@
}
/*
- * This routine is called to perform any module-specific fixing of header
- * fields, et cetera. It is invoked just before any content-handler.
+ * This function is registered by ap_hook_open_logs()
+ * It is responsible for opening any logfiles. It is assumed that if
+ * you are going to fail the open_logs phase, then you will print out
+ * your own message that explains what has gone wrong. The server
+ * doesn't need to do that for you.
*
- * The return value is OK, DECLINED, or HTTP_mumble. If we return OK, the
- * server will still call any remaining modules with an handler for this
- * phase.
+ * This function must return OK or apache will not start up.
*/
static int x_open_logs(apr_pool_t *pconf, apr_pool_t *plog,
apr_pool_t *ptemp, server_rec *s)
@@ -895,7 +876,16 @@
}
/*
- * All our process-death routine does is add its trace to the log.
+ * This is the cleanup routine registered by
+ * apr_pool_cleanup_register() which executes when when an
+ * heavy-weight process (such as a child) is being run down or
+ * destroyed. As with the child initialisation function, any
+ * information that needs to be recorded must be in static cells,
+ * since there's no configuration record. Note that it is not
+ * registered in x_register_hooks but inside of x_child_init.
+ *
+ * This function should return APR_SUCCESS on success. On error,
+ * see the apr docs for appropriate errorcodes, or use APR_EGENERAL
*/
static apr_status_t x_child_exit(void *data)
{
@@ -914,7 +904,13 @@
}
/*
- * All our process initialiser does is add its trace to the log.
+ * This function is registered by ap_hook_child_init()
+ * It is called during server initialisation when an heavy-weight
+ * process (such as a child) is being initialised. As with the module
+ * initialisation function, any information that needs to be recorded
+ * must be in static cells, since there's no configuration record.
+ *
+ * Note that it registers a cleanup function
*/
static void x_child_init(apr_pool_t *p, server_rec *s)
{
@@ -937,12 +933,42 @@
}
/*
- * This routine is called to perform any module-specific fixing of header
- * fields, et cetera. It is invoked just before any content-handler.
- *
- * The return value is OK, DECLINED, or HTTP_mumble. If we return OK, the
- * server will still call any remaining modules with an handler for this
- * phase.
+ * This method is registered by ap_hook_create_request()
+ * This hook allows modules to modify a request while it is being
+ * created. This hook is called for all request_rec's, main request,
+ * sub request, and internal redirect. When this hook is called, the
+ * the r->main, r->prev, r->next pointers have been set, so modules
+ * can determine what kind of request this is.
+ *
+ * This can be used for adding filters that should ONLY be run in a
+ * subrequest, or ONLY run in a main request.
+ *
+ * You should return OK in this function on success.
+ *
+ * XXX - nobody checks the return value of this function so who knows
+ * what the correct behavior is
+ */
+static int x_create_request(request_rec *r)
+{
+ if (!r->main && !r->prev) {
+ /** we're in the primary request **/
+ }
+ else {
+ /** this is a subrequest **/
+ }
+
+ return OK;
+}
+
+
+/*
+ * This function is registered by ap_hook_http_method()
+ * It is called to retrieve the HTTP method from a request. You
+ * probably don't want to register this method in your module.
+ *
+ * The return value is a string representing the the url scheme
+ * as defined in rfc 1738. (IE, the string preceding the colon
+ * in a url, such as 'http', 'ftp', 'https', 'rtsp', etc...)
*/
#if 0
static const char *x_http_method(const request_rec *r)
@@ -953,17 +979,17 @@
/*
* Log the call and exit.
*/
- trace_add(r->server, NULL, cfg, "x_post_config()");
+ trace_add(r->server, NULL, cfg, "x_http_method()");
return "foo";
}
/*
- * This routine is called to perform any module-specific fixing of header
- * fields, et cetera. It is invoked just before any content-handler.
+ * This function is registered by ap_hook_default_port()
+ * It is called to retrieve the default port for the server, such as
+ * port 80 in the current example. You probably don't want to
+ * register this function in your module.
*
- * The return value is OK, DECLINED, or HTTP_mumble. If we return OK, the
- * server will still call any remaining modules with an handler for this
- * phase.
+ * The return value is an apr_port_t int representing the port number.
*/
static apr_port_t x_default_port(const request_rec *r)
{
@@ -973,18 +999,20 @@
/*
* Log the call and exit.
*/
- trace_add(r->server, NULL, cfg, "x_post_config()");
+ trace_add(r->server, NULL, cfg, "x_default_port()");
return 80;
}
#endif /*0*/
/*
- * This routine is called to perform any module-specific fixing of header
- * fields, et cetera. It is invoked just before any content-handler.
+ * This routine is registered by ap_hook_insert_filter()
*
- * The return value is OK, DECLINED, or HTTP_mumble. If we return OK, the
- * server will still call any remaining modules with an handler for this
- * phase.
+ * This function should insert a filter into the filter chain. See
+ * the apache documentation on filters for more information
+ * (docs/manual/developer/filters.html)
+ *
+ * XXX - why use this instead of ap_register_*_filter() inside the
+ * register hooks function??
*/
static void x_insert_filter(request_rec *r)
{
@@ -994,19 +1022,30 @@
/*
* Log the call and exit.
*/
- trace_add(r->server, NULL, cfg, "x_post_config()");
+ trace_add(r->server, NULL, cfg, "x_insert_filter()");
}
/*
- * XXX fix my comment!!!!!! this sounds like the comment for a fixup
- * handler
- *
- * This routine is called to perform any module-specific fixing of header
- * fields, et cetera. It is invoked just before any content-handler.
- *
- * The return value is OK, DECLINED, or HTTP_mumble. If we return OK, the
- * server will still call any remaining modules with an handler for this
- * phase.
+ * This routine is registered by ap_hook_quick_handler()
+ * The quick_handler is run before any other requests hooks are called
+ * (location_walk, directory_walk, access checking, et. al.) This
+ * hook was added to enable serving files out of a URI keyed content
+ * cache ( e.g., Mike Abbott's Quick Shortcut Cache, described here:
+ * http://oss.sgi.com/projects/apache/mod_qsc.html )
+ *
+ * It may have other uses as well, such as routing requests directly to
+ * content handlers that have the ability to grok HTTP and do their
+ * own access checking, etc (e.g. servlet engines).
+ *
+ * Use this hook with extreme care and only if you know what you are
+ * doing.
+ *
+ * The return value is OK, DECLINED, or HTTP_mumble. If we return OK,
+ * the server will stop calling the handlers in this phase. Also, the
+ * full location_walk, access check, real handler will be skipped
+ * over. If all handlers in this phase return DECLINED, the normal
+ * request hook sequence is called. Note that the HTTP_mumble return
+ * status may not do what you expect in subrequests.
*/
static int x_quick_handler(request_rec *r, int lookup_uri)
{
@@ -1016,7 +1055,7 @@
/*
* Log the call and exit.
*/
- trace_add(r->server, NULL, cfg, "x_post_config()");
+ trace_add(r->server, NULL, cfg, "x_quick_handler()");
return DECLINED;
}
@@ -1040,7 +1079,7 @@
/*
* Log the call and exit.
*/
- trace_add(r->server, NULL, cfg, "x_post_config()");
+ trace_add(r->server, NULL, cfg, "x_pre_connection()");
#endif
return OK;
}
@@ -1284,6 +1323,7 @@
ap_hook_access_checker(x_access_checker, NULL, NULL, APR_HOOK_MIDDLE);
ap_hook_auth_checker(x_auth_checker, NULL, NULL, APR_HOOK_MIDDLE);
ap_hook_insert_filter(x_insert_filter, NULL, NULL, APR_HOOK_MIDDLE);
+ ap_hook_create_request( x_create_request, NULL, NULL, APR_HOOK_MIDDLE);
}
/*--------------------------------------------------------------------------*/
