home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  

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.


   Show Contents   Previous Page   Next Page

Chapter 10 - C API Reference Guide, Part I / Major Data Structures
The conn_rec Structure

The connection record structure, conn_rec, contains information that is specific to each client/server connection but not necessarily to each request (remember that recent versions of the HTTP protocol allow browsers to make multiple requests within the same TCP/IP session by issuing a Keepalive header). Within handlers, the current conn_rec is available inside the request record's connection field. The same server child will process all requests that are piggybacked on the same connection.

Most of the fields in the connection record are used internally by the server. Its most common use in modules is to retrieve the user's login name during authentication and to recover the client's IP address. The definition of conn_rec is given in Example 10-3. As before, we skip over those fields that module writers shouldn't worry about.

ap_pool *pool

This is a resource pool that module writers can use to allocate resources that should persist for the lifetime of the connection. This is rarely necessary, and it is usually better to use the pool located in the request record for this purpose.

server_rec *server
server_rec *base_server

These fields contain pointers to the server records for the current and base servers. If the current connection is being served by the main server, then these two pointers will be the same. Otherwise, server will point to the record for the current virtual host. The current host's server record is more conveniently obtained from the request record's server field.

BUFF *client

The client field contains a BUFF*, which is Apache's equivalent of the familiar standard I/O FILE*. This field is used internally to read and write data to the client and may be implemented as a plain TCP socket, an SSL channel, or some other protocol such as DCE RPC. You will never use this field directly but go through Apache's I/O routines instead. These are described in detail later in this section.

struct sockaddr_in local_addr
struct sockaddr_inremote_addr

These fields contain the endpoints of the active TCP/IP socket. You might use this information to request identd identification from the remote host.

char *remote_ip

The remote_ip field contains the dotted Internet address of the client.

char *remote_host

This field may contain the DNS name of the client. The various caveats described in Chapter 9, Perl API Reference Guide, for the remote_host() method of the Apache::Connection class also apply here. It is almost always a better idea to use the high-level API call ap_ get_remote_host() than to access this field directly.

char *remote_logname

This field may contain the login name of the remote user, provided that IdentityCheck is turned on and that the identd daemon is running on the user's machine (and a host of other considerations, such as the presence of firewalls between the client and host). All the caveats listed in Chapter 9 under the remote_logname() method of the Apache::Connection class apply here as well. You are strongly encouraged to take advantage of the high-level call ap_get_remote_logname() rather than accessing this field directly.

char *user

If an authentication method is in use for the current connection, the user field holds the login name provided by the user. The password cannot be recovered from this connection record, however. To get this information, you must call the high-level routine ap_ get_basic_auth_pw().

char *ap_auth_type

If authentication is in use for the current connection, this field will hold the name of the authentication method. At the time of this writing, the possibilities were Basic and Digest.

if(strcasecmp(c->ap_auth_type, "Basic")) {
     ap_log_error(APLOG_MARK, APLOG_NOERRNO|APLOG_WARN, r->server,
                "phew, I feel better now");

unsigned aborted

The aborted field is set to a true value if a timeout set by ap_soft_timeout() occurs while reading or writing to the client (see "The Timeout API" later in this chapter). This can happen, for example, when the remote user presses the browser stop button before the document is fully transmitted.

if(r->connection->aborted) {
    ap_log_error(APLOG_MARK, APLOG_NOERRNO|APLOG_WARN, r->server,
                "uh,oh, the client has gone away!");

signed int double_reverse

This field contains a flag indicating whether a double-reverse hostname lookup has been performed. 0 indicates that a double-reverse lookup has not been done (yet), and 1 indicates that the lookup was performed and was successful. If the field is set to -1, it means that the lookup was tried but failed. Double-reverse lookups are only performed if the configuration variable HostnameLookups is On or if an allow directive is configured to limit hostnames rather than IP addresses. See also the description of ap_get_remote_host().

Example 10-3. The conn_rec Definition

struct conn_rec {
    ap_pool *pool;
   server_rec *server;
   server_rec *base_server;   /* Physical vhost this conn come in on */
   void *vhost_lookup_data;   /* used by http_vhost.c */
    /* Information about the connection itself */
    int child_num;             /* The number of the child handling conn_rec */
   BUFF *client;              /* Connection to the guy */
    /* Who is the client? */
    struct sockaddr_in local_addr;     /* local address */
   struct sockaddr_in remote_addr;    /* remote address */
   char *remote_ip;           /* Client's IP address */
   char *remote_host;         /* Client's DNS name, if known.
                               * NULL if DNS hasn't been checked,
                               * "" if it has and no address was found.
                               * N.B. Only access this though
                               * get_remote_host() */
   char *remote_logname;      /* Only ever set if doing rfc1413 lookups.
                               * N.B. Only access this through
                               * get_remote_logname() */
   char *user;                /* If an authentication check was made,
                               * this gets set to the user name.  We assume
                               * that there's only one user per connection(!) 
*/ char *ap_auth_type; /* Ditto. */
    unsigned aborted:1;        /* Are we still talking? */
   signed int keepalive:2;    /* Are we using HTTP Keep-Alive?
                               * -1 fatal error, 0 undecided, 1 yes */
   unsigned keptalive:1;      /* Did we use HTTP Keep-Alive? */
   signed int double_reverse:2;/* have we done double-reverse DNS?
                               * -1 yes/failure, 0 not yet, 1 yes/success */
   int keepalives;            /* How many times have we used it? */ };
   Show Contents   Previous Page   Next Page
Copyright 1999 by O'Reilly & Associates, Inc.