home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam    

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.


 


   Show Contents   Previous Page   Next Page

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

Code
Constant (Nickname)
Description

2XX Codes--Success

200
HTTP_OK
(DOCUMENT_FOLLOWS)
The URI was found. Its contents follow.
201
HTTP_CREATED
The URI was created in response to a PUT.
202
HTTP_ACCEPTED
The request was accepted for processing at a later date.
203
HTTP_NON_AUTHORITATIVE
This is nonauthoritative mirrored information.
204
HTTP_NO_CONTENT
The request was successful, but there's no content to display.
206
HTTP_PARTIAL_CONTENT
(PARTIAL_CONTENT)
A portion of the document follows.

3XX Codes--Multiple Choices Available

300
HTTP_MULTIPLE_CHOICES
(MULTIPLE_CHOICES)
There are multiple document choices. (Used in content negotiation.)
301
HTTP_MOVED_PERMANENTLY
(MOVED)
The document has permanently moved to a new URI.
302
HTTP_MOVED_TEMPORARILY
(REDIRECT)
The document has temporarily moved to a new URI.
304
HTTP_NOT_MODIFIED
(USE_LOCAL_COPY)
The document has not been modified since it was cached.

4XX Codes--Client-Side Errors

400
HTTP_BAD_REQUEST
(BAD_REQUEST)
The request contains a syntax error.
401
HTTP_UNAUTHORIZED
(AUTH_REQUIRED)
The client did not provide correct authorization information.
402
HTTP_PAYMENT_REQUIRED
Payment is required. (Used in charging schemes.)
403
HTTP_FORBIDDEN
(FORBIDDEN)
The client is not allowed to access the document.
404
HTTP_NOT_FOUND
(NOT_FOUND)
The requested document does not exist.
405
HTTP_METHOD_NOT_ALLOWED
(METHOD_NOT_ALLOWED)
The request method (e.g., PUT) is not allowed here.
406
HTTP_NOT_ACCEPTABLE
The request is not acceptable.
407
HTTP_PROXY_AUTHENTICATION_REQUIRED
Proxy server must provide authentication.
408
HTTP_REQUEST_TIME_OUT
The client waited too long to complete the request.
410
HTTP_GONE
The requested document has been permanently removed.
412
HTTP_PRECONDITION_FAILED
(PRECONDITION_FAILED)
A conditional retrieval of the document has failed.
413
HTTP_REQUEST_ENTITY_TOO_LARGE
The client tried to PUT or POST data that was too long.
414
HTTP_REQUEST_URI_TOO_LARGE
The client tried to fetch a URI that was too long.
415
HTTP_UNSUPPORTED_MEDIA_TYPE
The client tried to PUT or POST data using an unsupported MIME type.

5XX Codes--Server-Side Errors

500
HTTP_INTERNAL_SERVER_ERROR
(SERVER_ERROR)
The server encountered an unexpected error condition.
501
HTTP_NOT_IMPLEMENTED
(NOT_IMPLEMENTED)
An HTTP feature is unimplemented.
502
HTTP_BAD_GATEWAY
(BAD_GATEWAY)
An error occurred in a remote server during a proxy request.
503
HTTP_SERVICE_UNAVAILABLE
The server is temporarily down.
504
HTTP_GATEWAY_TIME_OUT
A remote server timed out during a proxy request.
505
HTTP_VERSION_NOT_SUPPORTED
The server doesn't support this version of HTTP.
506
HTTP_VARIANT_ALSO_VARIES
(VARIANT_ALSO_VARIES)
A negotiated document has several alternative representations.

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.

   Show Contents   Previous Page   Next Page
Copyright © 1999 by O'Reilly & Associates, Inc.










??????????????@Mail.ru