Show Contents Previous Page Next Page
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
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
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:
The next example will redirect the client to another site
HTTP_METHOD_NOT_ALLOWED error is raised:
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 Show Contents Previous Page Next Page
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.
Copyright © 1999 by O'Reilly & Associates, Inc.