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 3 - The Apache Module Architecture and API / The Handler API
Status Codes

Every handler must return a status code. There are many possible codes, each of which is associated with a symbolic constant. The constants are defined by the Apache::Constants module if you are using Perl and the httpd.h include file if you are using the C language.

Table 3-1 shows the HTTP status codes, their symbolic constants, and a brief explanation. All constants have a full name that begins with the prefix "HTTP_" as in HTTP_FORBIDDEN. The common ones also have shorter "nicknames" as well, for example, FORBIDDEN.

Table 3-1. Common HTTP Status Codes

Apache::Constants does not export all of the formal HTTP_* names, since only a small handful are used by most modules. However, the constant functions are available for all of these names, should you need them. Chapter 9 gives a complete listing of all the HTTP_* names that are exportable by default. If your module tries to use one of the HTTP_* names and gets an "Undefined subroutine" error, see Chapter 9 for details on accessing it. The nicknames for the common status codes are all exportable by Apache::Constants.

The Perl examples throughout this book use the nicknames when available, even though their formal equivalents can be imported using the Apache::Constants :http tag. We do this partly because of historical reasons and because the :common tag imports a small number of functions--only those we need for the majority of modules. As always with Perl, there's more than one way to do it; the choice is yours.

In addition to the HTTP status codes, Apache defines some return codes of its own which handlers use to send status information to the server.

OK

This constant indicates that the handler was successful. For most phases Apache will now pass the request on to any other module that has registered its interest in handling the phase. However, for the URI translation, authentication, type-mapping, and response phases, the phase terminates as soon as a handler returns OK. The server behaves this way because it usually makes sense for a single module to handle these phases. However, you can override this behavior using the Perl API's "stacked handlers" mechanism, which we discuss in the next chapter.

The internal Apache OK constant should not be confused with HTTP constant HTTP_ OK (known by Apache::Constants as DOCUMENT_FOLLOWS).

DECLINED

The handler has decided it doesn't want to handle the request. Apache will act as if the subroutine were never called and either handle the phase internally or pass the request on to another module that has expressed its interest. Even if all registered modules return DECLINED for a particular phase, it will still be handled by the Apache core, which has default handlers for each phase (even if they do nothing).

It is possible for a module to lie when it declines a transaction. It may actually have done some work but wishes to let another module take the ultimate responsibility for the phase. For example, an authentication handler might manage caching of credential lookups from a database, but not actually make the authentication decision itself.

DONE

When DONE is returned, Apache immediately jumps out of the request loop, logs the transaction, and closes the client connection. This is one way to halt the transaction without generating an error status.

SERVER_ERROR, UNAUTHORIZED, REDIRECT, BAD_REQUEST, NOT_FOUND ...

The handler can return any of the HTTP status codes described in Table 3-1. Apache will create the appropriate HTTP header and send it to the browser. This is the way that handlers can signal that the requested document cannot be found, redirect the browser to another URI, or implement novel authorization schemes. The SERVER_ERROR code is commonly used to signal a fatal error, and it results in the display of the ugly but familiar "internal server error" page.

Apache's response to the status codes can be intercepted and customized with the ErrorDocument directive or the custom_response() API call. We give examples of using this feature to advantage in Chapter 4, Content Handlers, and Chapter 9.