Apache2::Connection - Perl API for Apache connection object
use Apache2::Connection (); use Apache2::RequestRec (); my $c = $r->connection; my $c = $r->connection; # is connection still open? $status = $c->aborted; # base server $base_server = $c->base_server(); # needed for creating buckets/brigades $ba = $c->bucket_alloc(); # client's socket $socket = $c->client_socket; # unique connection id $id = $c->id(); # connection filters stack $input_filters = $c->input_filters(); $output_filters = $c->output_filters(); # keep the connection alive? $status = $c->keepalive(); # how many requests served over the current connection $served = $c->keepalives(); # this connection's local and remote socket addresses $local_sa = $c->local_addr(); $remote_sa = $c->remote_addr(); # local and remote hostnames $local_host = $c->local_host(); $remote_host = $c->get_remote_host(); $remote_host = $c->remote_host(); # server and remote client's IP addresses $local_ip = $c->local_ip(); $remote_ip = $c->remote_ip(); # connection level Apache notes $notes = $c->notes(); # this connection's pool $p = $c->pool();
Apache2::RequestRec provides the Perl API for Apache connection record object.
Apache2::RequestRec
Apache2::Connection provides the following functions and/or methods:
Apache2::Connection
aborted
Check whether the connection is still open
$status = $c->aborted();
$c
Apache2::Connection object
$status
true if the connection has been aborted, false if still open
base_server
Physical server this connection came in on (main server or vhost):
$base_server = $c->base_server();
$base_server
Apache2::Server object
bucket_alloc
The bucket allocator to use for all bucket/brigade creations
$ba = $c->bucket_alloc();
$ba
APR::BucketAlloc object
This object is needed by APR::Bucket and APR::Brigade methods/functions.
APR::Bucket
APR::Brigade
client_socket
Get/set the client socket
$socket = $c->client_socket; $prev_socket = $c->client_socket($new_socket);
$new_socket
APR::Socket object
If passed a new socket will be set.
$socket
current client socket
if the optional argument $new_socket was passed the previous socket object is returned.
get_remote_host
Lookup the client's DNS hostname or IP address
$remote_host = $c->remote_host(); $remote_host = $c->remote_host($type); $remote_host = $c->remote_host($type, $dir_config);
The current connection
$type
:remotehost constant
The type of lookup to perform:
Apache2::Const::REMOTE_DOUBLE_REV
will always force a DNS lookup, and also force a double reverse lookup, regardless of the HostnameLookups setting. The result is the (double reverse checked) hostname, or undef if any of the lookups fail.
HostnameLookups
Apache2::Const::REMOTE_HOST
returns the hostname, or undef if the hostname lookup fails. It will force a DNS lookup according to the HostnameLookups setting.
undef
Apache2::Const::REMOTE_NAME
returns the hostname, or the dotted quad if the hostname lookup fails. It will force a DNS lookup according to the HostnameLookups setting.
Apache2::Const::REMOTE_NOLOOKUP
is like Apache2::Const::REMOTE_NAME except that a DNS lookup is never forced.
Default value is Apache2::Const::REMOTE_NAME.
$dir_config
Apache2::ConfVector object
The directory config vector from the request. It's needed to find the container in which the directive HostnameLookups is set. To get one for the current request use $r->per_dir_config.
$r->per_dir_config
By default, undef is passed, in which case it's the same as if HostnameLookups was set to Off.
Off
$remote_host
The remote hostname. If the configuration directive HostNameLookups is set to off, this returns the dotted decimal representation of the client's IP address instead. Might return undef if the hostname is not known.
The result of get_remote_host call is cached in $c->remote_host. If the latter is set, get_remote_host will return that value immediately, w/o doing any checkups.
$c->remote_host
id
ID of this connection; unique at any point in time
$id = $c->id();
$id
input_filters
Get/set the first filter in a linked list of protocol level input filters:
$input_filters = $c->input_filters(); $prev_input_filters = $c->input_filters($new_input_filters);
$new_input_filters
Set a new value
$input_filters
Apache2::Filter object
The first filter in the connection input filters chain.
If $new_input_filters was passed, returns the previous value.
For an example see: Bucket Brigades-based Protocol Module
keepalive
This method answers the question: Should the the connection be kept alive for another HTTP request after the current request is completed?
$status = $c->keepalive(); $status = $c->keepalive($new_status);
$new_status
:conn_keepalive constant
Normally you should not mess with setting this option when handling the HTTP protocol. If you do (for example when sending your own headers set with $r->assbackwards) -- take a look at the ap_set_keepalive() function in httpd-2.0/modules/http/http_protocol.c.
$r->assbackwards
The method does not return true or false, but one of the states which can be compared against (:conn_keepalive constants).
:conn_keepalive constants
Unless you set this value yourself when implementing non-HTTP protocols, it's only relevant for HTTP requests.
For example:
use Apache2::RequestRec (); use Apache2::Connection (); use Apache2::Const -compile => qw(:conn_keepalive); ... my $c = $r->connection; if ($c->keepalive == Apache2::Const::CONN_KEEPALIVE) { # do something } elsif ($c->keepalive == Apache2::Const::CONN_CLOSE) { # do something else } elsif ($c->keepalive == Apache2::Const::CONN_UNKNOWN) { # do yet something else } else { # die "unknown state"; }
Notice that new states could be added later by Apache, so your code should make no assumptions and do things only if the desired state matches.
keepalives
How many requests were already served over the current connection.
$served = $c->keepalives(); $served = $c->keepalives($new_served);
$new_served
Set the number of served requests over the current connection. Normally you won't do that when handling HTTP requests. (But see below a note regarding $r->assbackwards).
$served
In most handlers, but HTTP output filter handlers, that value doesn't count the current request. For the latter it'll count the current request.
This method is only relevant for keepalive connections. The core connection output filter ap_http_header_filter increments this value when the response headers are sent and it decides that the connection should not be closed (see ap_set_keepalive()).
ap_http_header_filter
ap_set_keepalive()
If you send your own set of HTTP headers with $r->assbackwards, which includes the Keep-Alive HTTP response header, you must make sure to increment the keepalives counter.
Keep-Alive
local_addr
Get this connection's local socket address
$local_sa = $c->local_addr();
$local_sa
APR::SockAddr object
local_host
used for ap_get_server_name when UseCanonicalName is set to DNS (ignores setting of HostnameLookups)
$local_host = $c->local_host();
$local_host
META: you probably shouldn't use this method, but ( get_server_name ) if inside request and $r is available.
get_server_name
$r
local_ip
server IP address
$local_ip = $c->local_ip();
$local_ip
notes
Get/set text notes for the duration of this connection. These notes can be passed from one module to another (not only mod_perl, but modules in any other language):
$notes = $c->notes(); $prev_notes = $c->notes($new_notes);
$new_notes
APR::Table object
$notes
the current notes table.
if the $new_notes argument was passed, returns the previous value.
Also see $r->notes
$r->notes
output_filters
Get the first filter in a linked list of protocol level output filters:
$output_filters = $c->output_filters(); $prev_output_filters = $r->output_filters($new_output_filters);
$new_output_filters
$output_filters
The first filter in the connection output filters chain.
If $new_output_filters was passed, returns the previous value.
pool
Pool associated with this connection
$p = $c->pool();
$p
APR::Pool object
remote_addr
Get this connection's remote socket address
$remote_sa = $c->remote_addr();
$remote_sa
remote_ip
Client's IP address
$remote_ip = $c->remote_ip(); $prev_remote_ip = $c->remote_ip($new_remote_ip);
$new_remote_ip
If passed a new value will be set
$remote_ip
current remote ip address
if the optional argument $new_remote_ip was passed the previous value is returned.
remote_host
Client's DNS name:
$remote_host = $c->remote_host();
If $c->get_remote_host was run it returns the cached value, which is a client DNS name or "" if it wasn't found. If the check wasn't run -- undef is returned.
$c->get_remote_host
""
It's best to to call $c->get_remote_host instead of directly accessing this variable.
Apache2::Connection also provides auto-generated Perl interface for a few other methods which aren't tested at the moment and therefore their API is a subject to change. These methods will be finalized later as a need arises. If you want to rely on any of the following methods please contact the the mod_perl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported API.
conn_config
Config vector containing pointers to connections per-server config structures
$ret = $c->conn_config();
$ret
sbh
META: Autogenerated - needs to be reviewed/completed
handle to scoreboard information for this connection
$sbh = $c->sbh();
$sbh
META: Not sure how this can be used from mod_perl at the moment. Unless Apache2::Scoreboard is extended to provide a hook to read from this variable.
Apache2::Scoreboard
mod_perl 2.0 documentation.
mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.
The mod_perl development team and numerous contributors.
To install mod_perl2, copy and paste the appropriate command in to your terminal.
cpanm
cpanm mod_perl2
CPAN shell
perl -MCPAN -e shell install mod_perl2
For more information on module installation, please visit the detailed CPAN module installation guide.