WebReference.com - Chapter 4 from The mod_perl Developer's Cookbook, from Sams Publishing (1/6)

[next]

mod_perl Developer's Cookbook

Chapter 4: Communicating with the Apache Server

Introduction

In addition to the Apache request record, there are also two other important data structures of which you should be awareÂthe server record and the connection record. The Apache server record contains information about the server itself, such as the values set by the ErrorLog and ServerAlias directives. The Apache connection record contains information about the current connection, such as the IP address of the initiating client and the authentication method for the request. As with the request record, the server and connection records are both defined in src/include/httpd.h in the Apache sources.

Access to each of these records is granted through two separate classes, appropriately named Apache::Server and Apache::Connection. Through these two classes, the Apache::Log class, and a few methods provided by the base Apache class, accessing and sometimes modifying properties logically connected to the server and its operation are possible. Although many of the following methods are not used frequently, they are all good to understand and suitable for scribbling on your mental chalkboard for later use.

4.1. Accessing the `Apache::Server` Object

You want to access various properties of the Apache server, such as the ServerName or TimeOut directives.

Technique

Create an Apache::Server object and use its methods.

package Cookbook::ViewServer;
use Apache::Constants qw(OK);
use Apache::Log;
use strict;
sub handler {
 # Get the Apache request object...
 my $r = shift;
 # ... and the Apache::Server object for this request.
 my $s = $r->server;
 $r->send_http_header('text/plain');
 # Iterate through all the configured servers.
 for (my $s = Apache->server; $s; $s = $s->next) {
  print "User directive:    ", $s->uid,       "\n";
  print "Group directive:    ", $s->gid,       "\n";
  print "Port directive:    ", $s->port,      "\n";
  print "TimeOut directive:   ", $s->timeout,     "\n";
  print "ErrorLog directive:  ", $s->error_fname,   "\n";
  print "LogLevel directive:  ", $s->loglevel,    "\n";
  print "ServerName directive: ", $s->server_hostname, "\n";
  print "ServerAdmin directive: ", $s->server_admin,  "\n";
  print "ServerAlias directives:\n" if $s->is_virtual;
  print "\t$_\n" foreach @{$s->names};
  print "-" x 30,                    "\n";
 }
 return OK;
}
1;

Comments

The previous chapter discussed the Apache request record and the various pieces of per-request data it holds. In addition to those fields already discussed, the request record holds a pointer to information about the Apache server responsible for servicing the current request. The Apache::Server class provides the interface to many of the base server configuration directives from the Apache server record. An Apache::Server object can be created in two ways, either by digging it out from the current request:

my $s = $r->server;

or by retrieving it directly through the Apache class:

my $s = Apache->server;

The difference between the two methods is that $r->server() returns the Apache::Server object associated with the current request. Apache->server(), on the other hand, returns the main Apache::Server object in Apache's internal list of configured servers. The convention is to place the Apache::Server object in the $s variable, which is how it will be presented throughout this book.

In most cases, you will want to retrieve the Apache::Server object directly from the request object, because that is the server directly involved in the current request. However, if you are interested in inspecting or altering any of the properties of the Apache server outside of a request, such as during module initialization, in <Perl> sections, or in startup.pl script, you can use Apache->server().

A partial list of Apache::Server methods is given in Table 4.1.

Table 4.1 Some `Apache::Server` Methods

Method	Example Value	Details
`error_fname()`	`logs/error_log`	Returns the value of the filename specified by the `ErrorLog` directive.
`gid()`	`99`	The numeric value of the group specified by the `Group` directive.
`is_virtual()`	TRUE	Returns true if the server is a virtual server.
`loglevel()`	`3`	Provides access to the numeric value Apache uses to represent the `LogLevel` setting. Requires `use()`ing the `Apache::Log` class.
`names()`	array reference	Returns an array reference containing the names of any configured `ServerAlias` directives.
`next()`	Apache::Server `object`	Returns the next server in Apache's internal list of configured servers.
`port()`	`80`	Returns the value given by the `Port` directive.
`server_admin()`	`[email protected]`	Returns the value of the `ServerAdmin` directive.
`server_hostname()`	`helm.example.com`	Returns the value of the `ServerName` directive.
`timeout()`	`300`	Provides access to the `TimeOut` directive.
`uid()`	`99`	Returns the numeric value of the user specified by the `User` directive.

The very important thing to remember is that even though the Apache::Server object is available at request time through the Apache request object, the scope of its attributes outlasts the current request. In fact, any changes you make to values in the server record are maintained for the life of the child, and will affect any requests to that same child process. Thus, it pays to be careful in your manipulation of server attributes and to know that changes you make will not be localized to the current request.

Although the Apache::Server class offers a direct hook into the raw server configuration, the base Apache class has a few methods that dig out some of the same information but are more applicable to most programming needs. For instance, the get_server_name() and get_server_port() methods from the Apache class are both sensitive to the UseCanonicalName directive, making them preferable over direct access to the corresponding fields in the server record at request time.

[next]

URL: https://webreference.com/programming/perl/cookbook/chap4/