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

In this section...

Introduction Handler Subroutines Status Codes Installing Handlers Perl API Configuration Directives

Introduction

When Apache calls a handler, it passes information about the current transaction and the server configuration. It's the handler's responsibility to take whatever action is appropriate for this phase and to then return an integer status code to Apache indicating the success or failure of its operation.

Handler Subroutines

In the Perl API, the definition of a handler is short and sweet:

sub  {
  my $r = shift;
  # do something
  return ;
}

No matter which phase of the Apache life cycle the handler is responsible for, the subroutine structure is always the same. The handler is passed a single argument consisting of a reference to an Apache request object. The request object is an object-oriented version of a central C record structure called the request record, and it contains all the information that Apache has collected about the transaction. By convention, a typical handler will store this object in a lexically scoped variable named $r. The handler retrieves whatever information it needs from the request object, does some processing, and possibly modifies the object to suit its needs. The handler then returns a numeric status code as its function result, informing Apache of the outcome of its work. We discuss the list of status codes and their significance in the next section.

There is one special case, however. If the handler has a function prototype of ($$) indicating that the subroutine takes two scalar arguments, the Perl API treats the handler as an object-oriented method call. In this case, the handler will receive two arguments. The handler's class (package) name or an object reference will be the first argument, and the Apache request object reference will be the second. This allows handlers to take advantage of class inheritance, polymorphism, and other useful object-oriented features. Handlers that use this feature are called "method handlers" and have the following structure:

sub  ($$) {
  my $class = shift;
  my $r = shift;
  # do something
  return ;
}

We give an example of using a Perl API method handler in the next chapter.

Request handlers declared in the C API are very similar:

 static int  (request_rec* r) {
   /* do something */
   return ;
}

The handler is called with a single argument consisting of a pointer to a request_rec request record. The subroutine pulls out whatever information it needs from the request record, modifies it if necessary, and then returns a status code.

However, unlike the Perl API, in which all handlers have the same structure regardless of their phase, the C API handlers that are responsible for the phases of the server life cycle outside the request loop are heterogeneous. For example, a child_init() handler in C looks like this:

 static void child_init (server_rec *s, pool *p) {
   /* do something */
}

In this case, there is no request record because there is no request to process at this point. Instead there is a pointer to a server record structure (a server_rec) and a memory pool for handling memory allocation issues. We explain the differences fully in Chapter 8, Customizing the Apache Configuration Process.