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 9 - Perl API Reference Guide / Other Core Perl API Classes
The Apache::Constants Class

All of the HTTP status codes are defined in the httpd.h file, along with server-specific status codes such as OK, DECLINED, and DONE. The Apache::Constants class provides access to these codes as constant subroutines. As there are many of these constants, they are not all exported by default. By default, only those listed in the :common export tag are exported. A variety of export tags are defined, allowing you to bring in various sets of constants to suit your needs. You are also free to bring in individual constants, just as you can with any other Perl module.

Here are the status codes listed by export tag group:

:common

This tag imports the most commonly used constants:

OK
FORBIDDEN
DECLINED
AUTH_REQUIRED
DONE
SERVER_ERROR
NOT_FOUND
 

:response

This tag imports the :common response codes, plus these response codes:

DOCUMENT_FOLLOWS
BAD_GATEWAY
MOVED
RESPONSE_CODES
REDIRECT
NOT_IMPLEMENTED
USE_LOCAL_COPY
CONTINUE
BAD_REQUEST
NOT_AUTHORITATIVE

CONTINUE and NOT_AUTHORITATIVE are aliases for DECLINED.

:methods

These are the method numbers, commonly used with the Apache method_number() method:

METHODS
M_PROPFIND
M_GET
M_PROPPATCH
M_PUT
M_MKCOL
M_POST
M_COPY
M_DELETE
M_MOVE
M_CONNECT
M_LOCK
M_OPTIONS
M_UNLOCK
M_TRACE
M_INVALID
M_PATCH
 

Each of the M_ constants corresponds to an integer value, where M_GET..M_UNLOCK is 0..14. The METHODS constant is the number of M_ constants, 15 at the time of this writing. This is designed to accommodate support for other request methods.

for (my $i = 0; $i < METHODS; $i++) {
  ...
}

:options

These constants are most commonly used with the Apache allow_options() method:

OPT_NONE
OPT_UNSET
OPT_INDEXES
OPT_INCNOEXEC
OPT_INCLUDES
OPT_SYM_OWNER
OPT_SYM_LINKS
OPT_MULTI
OPT_EXECCGI
OPT_ALL

:satisfy

These constants are most commonly used with the Apache satisfy() method:

SATISFY_ALL
SATISFY_ANY
SATISFY_NOSPEC

:remotehost

These constants are most commonly used with the Apache get_remote_host method:

REMOTE_HOST
REMOTE_NAME
REMOTE_NOLOOKUP
REMOTE_DOUBLE_REV

:http

This is a set of common HTTP response codes:

HTTP_OK
HTTP_BAD_REQUEST
HTTP_MOVED_TEMPORARILY
HTTP_INTERNAL_SERVER_ERROR
HTTP_MOVED_PERMANENTLY
HTTP_NOT_ACCEPTABLE
HTTP_METHOD_NOT_ALLOWED
HTTP_NO_CONTENT
HTTP_NOT_MODIFIED
HTTP_PRECONDITION_FAILED
HTTP_UNAUTHORIZED
HTTP_SERVICE_UNAVAILABLE
HTTP_FORBIDDEN
HTTP_VARIANT_ALSO_VARIES
HTTP_NOT_FOUND
 

Note that this list is not definitive. See the Apache source code for the most up-to-date listing.

:server

These are constants related to the version of the Apache server software:

MODULE_MAGIC_NUMBER
SERVER_VERSION
SERVER_BUILT

:config

These are constants most commonly used with configuration directive handlers:

DECLINE_CMD

:types

These are constants which define internal request types:

DIR_MAGIC_TYPE

:override

These constants are used to control and test the context of configuration directives:

OR_NONE
OR_INDEXES
OR_LIMIT
OR_UNSET
OR_OPTIONS
OR_ALL
OR_FILEINFO
ACCESS_CONF
OR_AUTHCFG
RSRC_CONF

:args_how

These are the constants which define configuration directive prototypes:

RAW_ARGS
TAKE123
TAKE1
ITERATE
TAKE2
ITERATE2
TAKE12
FLAG
TAKE3
NO_ARGS
TAKE23
 

As you may notice, this list is shorter than the list defined in Apache's include/httpd.h header file. The missing constants are available as subroutines via Apache::Constants, they are just not exportable by default. The less frequently used constants were left out of this list to keep memory consumption at a reasonable level.

There are two options if you need to access a constant that is not exportable by default. One is simply to use the fully qualified subroutine name, for example:

return Apache::Constants::HTTP_MULTIPLE_CHOICES();

Or use the export method in a server startup file to add exportable names. The name will now become available to the use operator.

#startup script
Apache::Constants->export(qw( HTTP_MULTIPLE_CHOICES ));
#runtime module
use Apache::Constants qw(:common HTTP_MULTIPLE_CHOICES);
...
return HTTP_MULTIPLE_CHOICES;

While the HTTP constants generally use a return code from handler subroutines, it is also possible to use the built-in die() function to jump out of a handler with a status code that will be propagated back to Apache:

unless (-r _) {
   die FORBIDDEN;
}

Footnotes

5 At the time of this writing, URI::URL was scheduled to be replaced by URI.pm, which will be distributed separately from the libwww-perl package.

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










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