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 10 - C API Reference Guide, Part I
Processing Requests

In this section...

Introduction Getting Information About the Transaction Getting Information About the Server Sending Data to the Client Sending Files to the Client Reading the Request Body The BUFF API The Timeout API Status Code Constants

Introduction

Now that we've covered Apache's major data types and the API for manipulating them, we turn to the functions you'll use routinely within your handlers to process the incoming request and produce a response.

Getting Information About the Transaction

You can get most of the information about the incoming request by reading it from the request record, server record, or connection record. The exception to this rule are a handful of routines that require active participation on the part of Apache to recover information about the remote host and user.

These calls are declared in the header file http_core.h unless specified otherwise:

const char *ap_get_remote_host(conn_rec *conn, void *dir_config, int type)

This routine returns the DNS name or dotted IP address of the remote host. The first argument is a pointer to the connection record, usually recovered from the request record. The second argument points to the per-directory configuration record, which can also be retrieved from the request record. ap_get_remote_host() uses the directory configuration pointer to examine the value of the HostnameLookups directive. If you pass NULL for this argument, ap_get_remote_host() will assume a value of Off for HostnameLookups , returning the dotted IP address of the remote host.

The third argument passed to ap_get_remote_host() is an integer constant indicating the type of lookup you wish to perform. There are four possibilities:

REMOTE_HOST

If this argument is specified, Apache will try to look up the DNS name of the remote host. This lookup may fail if the Apache configuration directive HostNameLookups is set to Off or the hostname cannot be determined by a DNS lookup, in which case the function will return null.

REMOTE_NAME

When called with this argument, the function will return the DNS name of the remote host if possible, or the dotted decimal representation of the client's IP address otherwise. The function will also return the IP address if HostNameLookups is set to Off. This is the most frequently used lookup type and the default in the Perl API.

REMOTE_NOLOOKUP

When this argument is specified, ap_get_remote_host() will not perform a new DNS lookup. If a successful lookup was done earlier in the request, the hostname cached in the connection record will be returned. Otherwise, the function returns the dotted decimal representation of the client's IP address.

REMOTE_DOUBLE_REV

This argument will trigger a double-reverse DNS lookup. Apache will first call DNS to return the hostname that maps to the IP number of the remote host. It will then make another call to map the returned hostname back to a set of IP addresses. If any of the new IP addresses that are returned match the original one, then the function returns the hostname. Otherwise, it returns NULL. The reason for this baroque procedure is that standard DNS lookups are susceptible to DNS spoofing in which a remote machine temporarily assumes the apparent identity of a trusted host. Double-reverse DNS lookups make spoofing much harder, and are recommended if you are using the hostname to distinguish between trusted clients and untrusted ones. For this very reason, REMOTE_DOUBLE_REV is always used for access checking when hostnames are used, rather than IP addresses. Unfortunately, double-reverse DNS lookups are also more expensive.

Unlike the other lookup types, REMOTE_DOUBLE_REV overrides the value of HostNameLookups and forces the lookup to occur if the result is not already cached.

Here is a typical example of using ap_get_remote_host() to return either the DNS name of the remote host or its dotted IP address:

char *remote_host = ap_get_remote_host(r->connection,
                                       r->per_dir_config, REMOTE_NAME);

const char *ap_get_remote_logname (request_rec *r)

This function returns the login name of the remote user or null if that information could not be determined. This generally works only if the remote user is logged into a Unix or VMS host and that machine is running the identd daemon (which implements a protocol known as RFC 1413). Its single argument is the current request record, from which it derives both the connection record and the per-directory configuration information (unlike ap_get_remote_host(), which requires you to split out that information yourself).

The success of the call also depends on the status of the IdentityCheck configuration directive. Since identity checks can adversely impact Apache's performance, this directive is off by default and the routine will return null.

const char *remote_logname = ap_get_remote_logname(r);

const char *ap_get_server_name(const request_rec *r)

The ap_get_server_name() function will return the server's name as a character string. The name returned is the server's "public" name suitable for incorporation into self-referencing URLs. If the request was directed to a virtual host, it will be this host's name that is returned. Otherwise, the function result will be the main host's name, as given by the ServerName directive. If there is no ServerName directive, then the value returned will be the same as that returned by the system's hostname command.

unsigned int ap_get_server_port(const request_rec *r)

This function returns the port number that the request was directed to, taking into account the default port and the virtual host. The port number returned by this function can be incorporated into self-referencing URLs.

int ap_method_number_of(const char *method)

(Declared in the header file http_protocol.h.) This function returns the integer method number corresponding to the given method string.

int methnum = ap_method_number_of(method);
if (methnum == M_INVALID) {
   return "Unknown method!";
}

Getting Information About the Server

Several API routines provide you with information about the server's current configuration. This information tends to remain the same from request to request. For historical reasons, these routines are distributed among http_config.h, http_core.h, and httpd.h.

char *ap_server_root_relative (pool *p, char *fname)

(Declared in the header file http_config.h.) Given a resource pool p and a relative file path fname, this routine prepends the path configured by ServerRoot to the file path and returns it as a new string. If an absolute file path is passed in, that value is returned, untouched. You can use ap_server_root_relative() to resolve relative pathnames to absolute paths beneath the server root directory or pass it an empty string to return the server root itself.

/* simply returns ServerRoot */
char *ServerRoot = ap_server_root_relative(r->pool, "");

/* returns $ServerRoot/logs/my.log */
char *log = ap_server_root_relative(r->pool, "logs/my.log");

/* returns /tmp/file.tmp */
char *tmpfile = ap_server_root_relative(r->pool, "/tmp/file.tmp");

const char *ap_default_type (request_rec *r)

(Declared in the header file http_core.h.) This function returns the value of the DefaultType directive or text/plain if not configured.

const char *type = ap_default_type(r);

const char *ap_get_server_version ()

(Declared in the header file httpd.h.) This function returns the server version string. This is the same string that appears in the outgoing HTTP Server header.

const char *server_version = ap_get_server_version();

const char * ap_get_server_built (void)

(Declared in the header file httpd.h.) This function returns a date stamp indicating when the main server image was compiled.

void ap_add_version_component (const char *component)

(Declared in the header file httpd.h.) When a module is considered a major component of the server, this function can be used to add the module name and version number to the server version string. It should be called from within a module init handler.

ap_add_version_component("mod_perl/2.20");

This will append a space followed by the string mod_perl/2.20 to the end of the server version string that Apache returns to clients.