Writing Apache Modules with Perl and C By:   Lincoln Stein and Doug MacEachern Published:   O'Reilly & Associates, Inc.  - March 1999 Copyright © 1999 by O'Reilly & Associates, Inc.

Chapter 10 - C API Reference Guide, Part I / Server Core Routines
Custom Response Handlers

As described in Chapters 3 and 4 and Chapter 6, Authentication and Authorization, Apache provides an API for creating custom error handlers. Modules can arrange for Apache to take special action when a handler returns a particular status code. Possible actions include displaying a static string, invoking a local URI, or redirecting to a remote URI. This is the mechanism that underlies the ErrorDocument directive.

As of Version 1.3.2, the Apache C-language API allows you to install a custom response handler from within a handler by calling the ap_custom_response() function, which is defined in the http_core.h header file. Here is the function's prototype:

void ap_custom_response (request_rec *r, int status, char *string);

r is, as usual, the current request record. status contains the status code that you wish to intercept, selected from among the symbolic constants defined in httpd.h. The last argument, string, can be a simple text message for Apache to display when the indicated error occurs, a remote URI, in which case Apache generates an external redirect, or a local URI, for which Apache generates a transparent internal redirect.

Apache distinguishes between these three possibilities by looking at the first few characters of the string. If it begins with a double quote mark, it is assumed to be a simple message string (the quote is stripped from the message before displaying it). Otherwise, if the string looks like a full URL (determined by calling ap_is_url()), Apache takes it to be an external URL. Finally, if the string begins with a forward slash, Apache assumes the string to be a local URI. If the string doesn't satisfy any of these criteria, then it is again treated as a simple text message.

Here is an example of using ap_custom_response() to set a text message to be displayed when authentication fails:

ap_custom_response(r, HTTP_UNAUTHORIZED, "sorry, I don't know you.");

And here is an example that will generate an internal redirect to the Perl script server_error_handler.pl when any sort of internal server error occurs:

ap_custom_response(r, HTTP_INTERNAL_SERVER_ERROR,
                   "/perl/server_error_handler.pl");

The next example will redirect the client to another site if an HTTP_METHOD_NOT_ALLOWED error is raised:

ap_custom_response(r, HTTP_METHOD_NOT_ALLOWED,
                   "http://www.w3.org/pub/WWW/Protocols/rfc2068/rfc2068");

If you wish to use custom response handlers to pass information from the original request onward to the new request, there are a number of techniques that you can use to preserve headers, cookies, and other information. See "The ErrorDocument System" in Chapter 4 and "Cookie-Based Access Control" in Chapter 6 for a discussion of these techniques and their practical application. The main point to recall is that outgoing HTTP headers stored in the request record's headers_out field are not sent to the browser on an error, nor are they preserved across internal redirects. The contents of the err_headers_out table, however, have both characteristics.