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 9 - Perl API Reference Guide
Other Core Perl API Classes

In this section...

Introduction The Apache TIEHANDLE Interface The Apache::SubRequest Class The Apache::Server Class The Apache::Connection Class The Apache::Table Class The Apache::URI Class The Apache::Util Class The mod_perl Class The Apache::Constants Class

Introduction

The vast bulk of the functionality of the Perl API is contained in the Apache object. However, a number of auxiliary classes, including Apache::Table, Apache::Connection, and Apache::Server, provide additional methods for accessing and manipulating the state of the server. This section discusses these classes.

The Apache TIEHANDLE Interface

In the CGI environment, the standard input and standard output file descriptors are redirected so that data read and written is passed through Apache for processing. In the Apache module API, handlers ordinarily use the Apache read() and print() methods to communicate with the client. However, as a convenience, mod_perl ties the STDIN and STDOUT filehandles to the Apache class prior to invoking Perl API modules. This allows handlers to read from standard input and write to standard output exactly as if they were in the CGI environment.

The Apache class supports the full TIEHANDLE interface, as described in perltie(1). STDIN and STDOUT are already tied to Apache by the time your handler is called. If you wish to tie your own input or output filehandle, you may do so by calling tie() with the request object as the function's third parameter:

tie *BROWSER, 'Apache', $r;
print BROWSER 'Come out, come out, wherever you are!';

Of course, it is better not to hardcode the Apache class name, as $r might be blessed into a subclass:

tie *BROWSER, ref $r, $r;

The Apache::SubRequest Class

The Apache methods lookup_uri() and lookup_file() return a request record object blessed into the Apache::SubRequest class. The Apache::SubRequest class is a subclass of Apache and inherits most of its methods from there. Here are two examples of fetching subrequest objects:

my $subr = $r->lookup_file($filename);
my $subr = $r->lookup_uri($uri);

The Apache::SubRequest class adds a single new method, run().

run()

When a subrequest is created, the URI translation, access checks, and MIME checking phases are run, but unlike a real request, the content handler for the response phase is not actually run. If you would like to invoke the content handler, the run() method will do it:

my $status = $subr->run;

When you invoke the subrequest's response handler in this way, it will do everything a response handler is supposed to, including sending the HTTP headers and the document body. run() returns the content handler's status code as its function result. If you are invoking the subrequest run() method from within your own content handler, you must not send the HTTP header and document body yourself, as this would be appended to the bottom of the information that has already been sent. Most handlers that invoke run() will immediately return its status code, pretending to Apache that they handled the request themselves:

my $status = $subr->run;
return $status;

The Apache::Server Class

The Apache::Server class provides the Perl interface to the C API server_rec data structure, which contains lots of low-level information about the server configuration. Within a handler, the current Apache::Server object can be obtained by calling the Apache request object's server() method. At Perl startup time (such as within a startup script or a module loaded with PerlModule), you can fetch the server object by invoking Apache->server directly. By convention, we use the variable $s for server objects.

#at request time
sub handler {
  my $r = shift;
  my $s = $r->server;
  ....
}

#at server startup time, e.g., PerlModule or PerlRequire
my $s = Apache->server;

This section discusses the various methods that are available to you via the server object. They correspond closely to the fields of the server_rec structure, which we revisit in Chapter 10.

is_virtual()

This method returns true if the current request is being applied to a virtual server. This is a read-only method.

my $is_virtual = $s->is_virtual;

log()

The log() method retrieves an object blessed into the Apache::Log class. You can then use this object to access the full-featured logging API. See "The Apache::Log class" for details.

use Apache::Log ();
my $log = $s->log;

The Apache::Server::log() method is identical in most respects to the Apache::log() method discussed earlier. The difference is that messages logged with Apache::log() will include the IP address of the browser and add the messages to the notes table under a key named error-notes. See the description of notes() under "Server Core Functions."

port()

This method returns the port on which this (virtual) server is listening. If no port is explicitly listed in the server configuration file (that is, the server is listening on the default port 80), this method will return 0. Use the higher-level Apache::get_server_port() method if you wish to avoid this pitfall.

my $port = $r->server->port || 80;

This method is read-only.

server_admin()

This method returns the email address of the person responsible for this server as configured by the ServerAdmin directive.

my $admin = $s->server_admin;

This method is read-only.

server_hostname()

This method returns the (virtual) hostname used by this server, as set by the ServerName directive.

my $hostname = $s->server_hostname;

This method is read-only.

names()

If this server is configured to use virtual hosts, the names() method will return the names by which the current virtual host is recognized as specified by the ServerAlias directives (including wildcarded names). The function result is an array reference containing the hostnames. If no alias names are present or the server is not using virtual hosts, this will return a reference to an empty list.

my $s = $r->server;
my $names = $s->names;
print "Names = @$names\n";

next()

Apache maintains a linked list of all configured virtual servers, which can be accessed with the next() method.

for(my $s = Apache->server; $s; $s = $s->next) {
   printf "Contact %s regarding problems with the %s site\n",
           $s->server_admin, $s->server_hostname;
}

log_error()

This method is the same as the Apache::log_error() method, except that it's available through the Apache::Server object. This allows you to use it in Perl startup files and other places where the request object isn't available.

my $s = Apache->server;
$s->log_error("Can't open config file $!");

warn()

This method is the same as the Apache::warn() method, but it's available through the Apache::Server object. This allows you to use it in Perl startup files and other places where the request object isn't available.

my $s = Apache->server;
$s->warn("Can't preload script $file $!");