|
Apache::Connection - Perl API for Apache connection object |
abortedbase_serverbucket_allocclient_socketget_remote_hostidinput_filterskeepalivekeepaliveslocal_addrlocal_hostlocal_ipnotesoutput_filterspoolremote_addrremote_ipremote_host
Apache::Connection - Perl API for Apache connection object
use Apache::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();
Apache::RequestRec provides the Perl API for Apache connection
record object.
Apache::Connection provides the following functions and/or methods:
abortedCheck whether the connection is still open
$status = $c->aborted();
$c
( Apache::Connection object|docs::2.0::api::Apache::Connection )$status ( boolean )
base_serverPhysical server this connection came in on (main server or vhost):
$base_server = $c->base_server();
$c
( Apache::Connection object|docs::2.0::api::Apache::Connection )$base_server
( Apache::Server object|docs::2.0::api::Apache::ServerRec )
bucket_allocThe bucket allocator to use for all bucket/brigade creations
$ba = $c->bucket_alloc();
$c
( Apache::Connection object|docs::2.0::api::Apache::Connection )$ba
( APR::BucketAlloc object|docs::2.0::api::APR::BucketAlloc )This object is needed by APR::Bucket|docs::2.0::api::APR::Bucket
and APR::Brigade|docs::2.0::api::APR::Brigade methods/functions.
client_socketGet/set the client socket
$socket = $c->client_socket; $prev_socket = $c->client_socket($new_socket);
$c
( Apache::Connection object|docs::2.0::api::Apache::Connection )$new_socket
( APR::Socket object|docs::2.0::api::APR::Socket object )$socket
( APR::Socket object|docs::2.0::api::APR::Socket object )if the optional argument $new_socket was passed the previous socket
object is returned.
get_remote_hostLookup 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);
$c
( Apache::Connection object|docs::2.0::api::Apache::Connection )$type ( :remotehost
constant|docs::2.0::api::Apache::Const/C__remotehost_> )Apache::REMOTE_DOUBLE_REVHostnameLookups setting. The result is
the (double reverse checked) hostname, or undef if any of the lookups
fail.
Apache::REMOTE_HOSTundef if the hostname lookup fails. It
will force a DNS lookup according to the HostnameLookups setting.
Apache::REMOTE_NAMEHostnameLookups
setting.
Apache::REMOTE_NOLOOKUPApache::REMOTE_NAME except that a DNS lookup is never
forced.
Default value is Apache::REMOTE_NAME.
$dir_config
( Apache::ConfVector object|docs::2.0::api::Apache::ConfVector )HostnameLookups is set. To get one
for the current request use
$r->per_dir_config|docs::2.0::api::Apache::RequestRec/C_per_dir_config_.
By default, undef is passed, in which case it's the same as if
HostnameLookups was set to Off.
$remote_host ( string/undef )undef if the hostname is not known.
The result of get_remote_host call is cached in
$c->remote_host|/C_remote_host_. If the latter is set,
get_remote_host will return that value immediately, w/o doing any
checkups.
idID of this connection; unique at any point in time
$id = $c->id();
$c
( Apache::Connection object|docs::2.0::api::Apache::Connection )$id (integer)
input_filtersGet/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);
$c
( Apache::Connection object|docs::2.0::api::Apache::Connection )$new_input_filters$input_filters
( Apache::Filter object|docs::2.0::api::Apache::Filter )If $new_input_filters was passed, returns the previous value.
For an example see: Bucket Brigades-based Protocol Module
keepaliveThis 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);
$c
( Apache::Connection object|docs::2.0::api::Apache::Connection )$new_status ( :conn_keepalive
constant|docs::2.0::api::Apache::Const/C__conn_keepalive_> )$r->assbackwards|docs::2.0::api::Apache::RequestRec/C_assbackwards_)
-- take a look at the ap_set_keepalive() function in
httpd-2.0/modules/http/http_protocol.c.
$status ( :conn_keepalive
constant|docs::2.0::api::Apache::Const/C__conn_keepalive_> ):conn_keepalive
constants|docs::2.0::api::Apache::Const/C__conn_keepalive_>).
Unless you set this value yourself when implementing non-HTTP protocols, it's only relevant for HTTP requests.
For example:
use Apache::RequestRec (); use Apache::Connection ();
use Apache::Const -compile => qw(:conn_keepalive);
...
my $c = $r->connection;
if ($c->keepalive == Apache::CONN_KEEPALIVE) {
# do something
}
elsif ($c->keepalive == Apache::CONN_CLOSE) {
# do something else
}
elsif ($c->keepalive == Apache::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.
keepalivesHow many requests were already served over the current connection.
$served = $c->keepalives(); $served = $c->keepalives($new_served);
$c
( Apache::Connection object|docs::2.0::api::Apache::Connection )$new_served (integer)$r->assbackwards|docs::2.0::api::Apache::RequestRec/C_assbackwards_).
$served (integer)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()).
If you send your own set of HTTP headers with
$r->assbackwards|docs::2.0::api::Apache::RequestRec/C_assbackwards_,
which includes the Keep-Alive HTTP response header, you must make
sure to increment the keepalives counter.
local_addrGet this connection's local socket address
$local_sa = $c->local_addr();
$c
( Apache::Connection object|docs::2.0::api::Apache::Connection )$local_sa
( APR::SockAddr object|docs::2.0::api::APR::SockAddr )
local_hostused for ap_get_server_name when UseCanonicalName is set to DNS (ignores setting of HostnameLookups)
$local_host = $c->local_host();
$c
( Apache::Connection object|docs::2.0::api::Apache::Connection )$local_host (string)META: you probably shouldn't use this method, but (
get_server_name|docs::2.0::api::Apache::RequestUtil/C_get_server_name_
) if inside request and $r is available.
local_ipserver IP address
$local_ip = $c->local_ip();
$c
( Apache::Connection object|docs::2.0::api::Apache::Connection )$local_ip (string)
notesGet/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);
$c
( Apache::Connection object|docs::2.0::api::Apache::Connection )$new_notes
( APR::Table object|docs::2.0::api::APR::Table )$notes
( APR::Table object|docs::2.0::api::APR::Table )if the $new_notes argument was passed, returns the previous value.
Also see
$r->notes|docs::2.0::api::Apache::RequestRec/C_notes_
output_filtersGet 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);
$c
( Apache::Connection object|docs::2.0::api::Apache::Connection )$new_output_filters$output_filters
( Apache::Filter object|docs::2.0::api::Apache::Filter )If $new_output_filters was passed, returns the previous value.
For an example see: Bucket Brigades-based Protocol Module
poolPool associated with this connection
$p = $c->pool();
$c
( Apache::Connection object|docs::2.0::api::Apache::Connection )$p
( APR::Pool object|docs::2.0::api::APR::Pool )
remote_addrGet this connection's remote socket address
$remote_sa = $c->remote_addr();
$c
( Apache::Connection object|docs::2.0::api::Apache::Connection )$remote_sa
( APR::SockAddr object|docs::2.0::api::APR::SockAddr )
remote_ipClient's IP address
$remote_ip = $c->remote_ip();
$c
( Apache::Connection object|docs::2.0::api::Apache::Connection )$remote_ip (string)
remote_hostClient's DNS name:
$remote_host = $c->remote_host();
$c
( Apache::Connection object|docs::2.0::api::Apache::Connection )$remote_host ( string/undef )$c->get_remote_host|/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.
It's best to to call $c->get_remote_host|/C_get_remote_host_
instead of directly accessing this variable.
Apache::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_configConfig vector containing pointers to connections per-server config structures
$ret = $c->conn_config();
$c
( Apache::Connection object|docs::2.0::api::Apache::Connection )$ret
( Apache::ConfVector object|docs::2.0::api::Apache::ConfVector )
sbhMETA: Autogenerated - needs to be reviewed/completed
handle to scoreboard information for this connection
$sbh = $c->sbh();
$c
( Apache::Connection object|docs::2.0::api::Apache::Connection )$sbh (XXX)META: Not sure how this can be used from mod_perl at the
moment. Unless Apache::Scoreboard is extended to provide a hook to
read from this variable.
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.
|
Apache::Connection - Perl API for Apache connection object |