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
Perl API Classes and Data Structures

In this section...

Introduction The Apache Request Object The Apache::Server Object The Apache::Connection Object Other Core Classes Noncore Classes

Introduction

We'll look now at what a handler subroutine sees when it is called. All interaction between the handler and the Apache server is done through the request record. In the Perl API, the request record is encapsulated within a request object, which for historical reasons is blessed into the Apache:: namespace. The Apache request object contains most of the information about the current transaction. It also contains references to other objects that provide further information about the server and the current transaction. The request object's server() method returns an Apache::Server object, which contains server configuration information. The connection() method returns an Apache::Connection object, which contains low-level information about the TCP/IP connection between the browser and the client.

In the C API, information about the request is passed to the handler as a pointer to a request_rec. Included among its various fields are pointers to a server_rec and a conn_rec structure, which correspond to the Perl API's Apache::Server and Apache::Connection objects. We have much more to say about using the request_rec in Chapters 10 and 11 when we discuss the C-language API in more detail.

The Apache Request Object

The Apache request object (the request_rec in C) is the primary conduit for the transfer of information between modules and the server. Handlers can use the request object to perform several types of operations:

Get and set information about the requested document

The URI of the requested document, its translated file name, its MIME type, and other useful information are available through a set of request object methods. For example, a method named uri() returns the requested document's URI, and content_type() retrieves the document's MIME type. These methods can also be used to change the values, for example, to set the MIME type of a document generated on the fly.

Get incoming HTTP headers

All the request headers are available through a method called header_in(). From this information you can recover the make and model of the browser, the list of MIME types that the browser can display, any HTTP cookies the server has set, and information about any content the browser wishes to send, such as the contents of a fill-out form.

Get and set outgoing HTTP headers

The outgoing HTTP headers, which do such things as set HTTP cookies, control browser caching, and provide information about the requested document, can be examined or set via a method called header_out(). Certain very common outgoing headers have dedicated methods for setting their values. For example, the outgoing Content-Type header is usually set using the content_type() method rather than header_out(). Once the outgoing header fields are fully set up, the handler can send them to the client with send_ http_header().

Read incoming document data

When the browser sends document information to the server, such as the contents of POSTed forms or uploaded files, the handler can use the request object's read() method to read in and manage the submitted information.

Create outgoing document data

Handlers that are responsible for content generation will use the request object's print() method to send document data to the browser. There are also methods for sending whole files in a single step.

Get common per-transaction information

Commonly needed information, such as the remote browser's hostname and the port at which the server established the connection, is available from the request object through methods with names like get_remote_host() and get_server_port(). More esoteric information is available through the Apache::Connection and Apache::Server objects returned by the connection() and server() methods, respectively.

Log warnings and errors

The request object provides methods for writing formatted error messages and warnings to the server error log. The simplest and most widely used method is log_error(). There is also a fully fledged Apache::Log class which gives you access to Apache's more advanced logging API.

Control transaction processing

By calling the request object's custom_response(), handler(), or internal_redirect() methods, a handler can control how the transaction is to be processed by setting what modules will handle the content generation phase of the request in the case of success or failure. A handler can also kick off a sub-request using the lookup_uri() or lookup_filename() methods.

Get module configuration information

The PerlSetVar configuration file directive allows you to pass runtime configuration information to Perl API modules using a simple key/value system. Perl API modules fetch this information with the dir_config() method. This eliminates the need to pass runtime information to Perl API modules by making source code modifications. In addition, mod_perl supports a more complex configuration API that allows modules to define and use custom configuration directives.

The bulk of this book is devoted to all the many things you can do with the request object.

The Apache::Server Object

The Apache::Server class (a server_rec in the C API) contains information about the server's configuration. From this object, handlers can recover such things as the email address of the server administrator, the list of virtual hosts that this server supports, and the port number(s) that this server listens to.

The Apache::Server object is also where per-server module configuration information is stored and is an integral part of the custom configuration directive API described in Chapter 8.

The Apache::Connection Object

Handlers can use this class to retrieve all sorts of low-level information about the current connection. Among the information stored here are the TCP/IP socket endpoints of the server/browser connection, the remote and local IP addresses, and a flag that indicates when a connection was broken prematurely.

In addition, the Apache::Connection object provides information about user authentication. You can recover the type of authentication in use with the auth_type() method, and the authenticated user's name with the user() method. These features are described in more detail in Chapter 6.

Other Core Classes

The Perl API also defines a number of core classes that provide interfaces to other areas of the Apache C API. We'll describe them at length in later chapters when we need to use them. For now, we'll just list them so that you know they're there.

Apache::URI

Methods for generating and parsing URIs

Apache::Log

Methods to generate nicely formatted log messages

Apache::File

Methods to send the contents of static files in an HTTP/1.1-compliant fashion

Apache::Util

Methods for manipulating HTTP dates and times, and for working with HTML documents

Apache::ModuleConfig and Apache::CmdParms

Utilities for generating and processing custom configuration directives

Noncore Classes

mod_perl comes with a set of standalone modules that are useful in their own right. The most important of these is Apache::Registry, which the next chapter covers in great detail. We list them briefly here just so that you know they exist. See Appendix A, Standard Noncore Modules, for a full reference guide to Apache::Registry and its kin.

Apache::Registry

A persistent CGI-like environment for legacy scripts and for writing high-performance modules without using the Apache API.

Apache::PerlRun

An object-oriented API for running Perl scripts inside of the Apache server. It uses this API within its own handler which provides another CGI emulation environment for running legacy scripts that do not run properly under Apache::Registry.

Apache::RegistryLoader

Speeds up Apache::Registry even further by preloading certain CGI scripts.

Apache::Resource

Controls resource allocation to avoid poorly written scripts from hogging the server.

Apache::PerlSections

Helper methods for configuring Apache dynamically using Perl embedded in its configuration files.

Apache::StatINC

Reloads changed modules from disk automatically when they change, rather than the next time the server is restarted.

Apache::Include

Simple wrappers around the subrequest API and a handler for running within mod_ include.

Apache::Status

A Perl runtime browser often helpful when tracking down problems or satisfying curiosities.

The next chapter begins a tutorial that takes you through the API one step at a time, beginning with the all-important response phase. For the definitive reference style listing of classes, methods, functions, and data types, see Chapter 9 for the Perl API and Chapters 10 and 11 for the C API.