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. | 
