apachaepamcohdepmeordl-p1e0r1l.-11~02U1:s.:e1mr~o2dC:o:pnmetorrdli-bp2ue.tr0el.d-22:P.:e0dr.ol2c:sD::od:coaucpmsie::n::taAapptiai:co:hnAep2a:c:hCeo2n:n:eCcotninoenc(t3i)on(3)

NAME
       Apache2::Connection - Perl API for Apache connection object

SSyynnooppssiiss
         use Apache2::Connection ();

         # is connection still open?
         $status = $c->aborted;

         # base server
         $baseserver = $c->baseserver();

         # needed for creating buckets/brigades
         $ba = $c->bucketalloc();

         # client's socket
         $socket = $c->clientsocket;

         # unique connection id
         $id = $c->id();

         # connection filters stack
         $inputfilters = $c->inputfilters();
         $outputfilters = $c->outputfilters();

         # 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
         $localsa  = $c->localaddr();
         $remotesa = $c->remoteaddr();

         # local and remote hostnames
         $localhost = $c->localhost();
         $remotehost = $c->getremotehost();
         $remotehost = $c->remotehost();

         # server and remote client's IP addresses
         $localip = $c->localip();
         $remoteip = $c->remoteip();

         # connection level Apache notes
         $notes = $c->notes();

         # this connection's pool
         $p = $c->pool();

DDeessccrriippttiioonn
       "Apache2::RequestRec" provides the Perl API for Apache connection
       record object.

AAPPII
       "Apache2::Connection" provides the following functions and/or methods:

       ""aabboorrtteedd""

       Check whether the connection is still open

         $status = $c->aborted();

       obj: $c ( "Apache2::Connection object" )
       ret: $status ( boolean )
           true if the connection has been aborted, false if still open

       since: 2.0.00

       ""bbaasseesseerrvveerr""

       Physical server this connection came in on (main server or vhost):

         $baseserver = $c->baseserver();

       obj: $c ( "Apache2::Connection object" )
       ret: $baseserver ( "Apache2::Server object" )
       since: 2.0.00

       ""bbuucckkeettaalllloocc""

       The bucket allocator to use for all bucket/brigade creations

         $ba = $c->bucketalloc();

       obj: $c ( "Apache2::Connection object" )
       ret: $ba ( "APR::BucketAlloc object" )
       since: 2.0.00

       This object is needed by "APR::Bucket" and "APR::Brigade"
       methods/functions.

       ""cclliieennttssoocckkeett""

       Get/set the client socket

         $socket      = $c->clientsocket;
         $prevsocket = $c->clientsocket($newsocket);

       obj: $c ( "Apache2::Connection object" )
       opt arg1: $newsocket ( "APR::Socket object" object )
           If passed a new socket will be set.

       ret: $socket ( "APR::Socket object" object )
           current client socket

           if the optional argument $newsocket was passed the previous socket
           object is returned.

       since: 2.0.00

       ""ggeettrreemmootteehhoosstt""

       Lookup the client's DNS hostname or IP address

         $remotehost = $c->remotehost();
         $remotehost = $c->remotehost($type);
         $remotehost = $c->remotehost($type, $dirconfig);

       obj: $c ( "Apache2::Connection object" )
           The current connection

       opt arg1: $type ( ":remotehost constant" )
           The type of lookup to perform:

           "Apache2::Const::REMOTEDOUBLEREV"
               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.

           "Apache2::Const::REMOTEHOST"
               returns the hostname, or "undef" if the hostname lookup fails.
               It will force a DNS lookup according to the "HostnameLookups"
               setting.

           "Apache2::Const::REMOTENAME"
               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::REMOTENOLOOKUP"
               is like "Apache2::Const::REMOTENAME" except that a DNS lookup
               is never forced.

           Default value is "Apache2::Const::REMOTENAME".

       opt arg2: $dirconfig ( "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->perdirconfig".

           By default, "undef" is passed, in which case it's the same as if
           "HostnameLookups" was set to "Off".

       ret: $remotehost ( string/undef )
           The remote hostname.  If the configuration directive
           HHoossttNNaammeeLLooookkuuppss 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.

       since: 2.0.00

       The result of "getremotehost" call is cached in "$c->remotehost". If
       the latter is set, "getremotehost" will return that value
       immediately, w/o doing any checkups.

       ""iidd""

       ID of this connection; unique at any point in time

         $id = $c->id();

       obj: $c ( "Apache2::Connection object" )
       ret: $id (integer)
       since: 2.0.00

       ""iinnppuuttffiilltteerrss""

       Get/set the first filter in a linked list of protocol level input
       filters:

         $inputfilters      = $c->inputfilters();
         $previnputfilters = $c->inputfilters($newinputfilters);

       obj: $c ( "Apache2::Connection object" )
       opt arg1: $newinputfilters
           Set a new value

       ret: $inputfilters ( "Apache2::Filter object" )
           The first filter in the connection input filters chain.

           If $newinputfilters was passed, returns the previous value.

       since: 2.0.00

       For an example see: Bucket Brigades-based Protocol Module

       ""kkeeeeppaalliivvee""

       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($newstatus);

       obj: $c ( "Apache2::Connection object" )
       opt arg1: $newstatus ( ":connkeepalive 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
           apsetkeepalive() function in
           httpd-2.0/modules/http/httpprotocol.c.

       ret: $status ( ":connkeepalive constant" )
           The method does nnoott return true or false, but one of the states
           which can be compared against (":connkeepalive constants").

       since: 2.0.00

       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(:connkeepalive);
         ...
         my $c = $r->connection;
         if ($c->keepalive == Apache2::Const::CONNKEEPALIVE) {
             # do something
         }
         elsif ($c->keepalive == Apache2::Const::CONNCLOSE) {
             # do something else
         }
         elsif ($c->keepalive == Apache2::Const::CONNUNKNOWN) {
             # 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.

       ""kkeeeeppaalliivveess""

       How many requests were already served over the current connection.

         $served = $c->keepalives();
         $served = $c->keepalives($newserved);

       obj: $c ( "Apache2::Connection object" )
       opt arg1: $newserved (integer)
           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").

       ret: $served (integer)
           How many requests were already served over the current connection.

           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.

       since: 2.0.00

       This method is only relevant for keepalive connections. The core
       connection output filter "aphttpheaderfilter" increments this value
       when the response headers are sent and it decides that the connection
       should not be closed (see "apsetkeepalive()").

       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.

       ""llooccaallaaddddrr""

       Get this connection's local socket address

         $localsa = $c->localaddr();

       obj: $c ( "Apache2::Connection object" )
       ret: $localsa ( "APR::SockAddr object" )
       since: 2.0.00

       ""llooccaallhhoosstt""

       used for apgetservername when UseCanonicalName is set to DNS
       (ignores setting of HostnameLookups)

         $localhost = $c->localhost();

       obj: $c ( "Apache2::Connection object" )
       ret: $localhost (string)
       since: 2.0.00

       META: you probably shouldn't use this method, but ( "getservername" )
       if inside request and $r is available.

       ""llooccaalliipp""

       server IP address

         $localip = $c->localip();

       obj: $c ( "Apache2::Connection object" )
       ret: $localip (string)
       since: 2.0.00

       ""nnootteess""

       Get/set text notes for the duration of this connection. These notes can
       be passed from one module to another (not only modperl, but modules in
       any other language):

         $notes      = $c->notes();
         $prevnotes = $c->notes($newnotes);

       obj: $c ( "Apache2::Connection object" )
       opt arg1: $newnotes ( "APR::Table object" )
       ret: $notes ( "APR::Table object" )
           the current notes table.

           if the $newnotes argument was passed, returns the previous value.

       since: 2.0.00

       Also see "$r->notes"

       ""oouuttppuuttffiilltteerrss""

       Get the first filter in a linked list of protocol level output filters:

         $outputfilters = $c->outputfilters();
         $prevoutputfilters = $r->outputfilters($newoutputfilters);

       obj: $c ( "Apache2::Connection object" )
       opt arg1: $newoutputfilters
           Set a new value

       ret: $outputfilters ( "Apache2::Filter object" )
           The first filter in the connection output filters chain.

           If $newoutputfilters was passed, returns the previous value.

       since: 2.0.00

       For an example see: Bucket Brigades-based Protocol Module

       ""ppooooll""

       Pool associated with this connection

         $p = $c->pool();

       obj: $c ( "Apache2::Connection object" )
       ret: $p ( "APR::Pool object" )
       since: 2.0.00

       ""rreemmootteeaaddddrr""

       Get this connection's remote socket address

         $remotesa = $c->remoteaddr();

       obj: $c ( "Apache2::Connection object" )
       ret: $remotesa ( "APR::SockAddr object" )
       since: 2.0.00

       ""rreemmootteeiipp""

       Client's IP address

         $remoteip      = $c->remoteip();
         $prevremoteip = $c->remoteip($newremoteip);

       obj: $c ( "Apache2::Connection object" )
       opt arg1: $newremoteip ( string )
           If passed a new value will be set

       ret: $remoteip ( string )
           current remote ip address

           if the optional argument $newremoteip was passed the previous
           value is returned.

       since: 2.0.00

       ""rreemmootteehhoosstt""

       Client's DNS name:

         $remotehost = $c->remotehost();

       obj: $c ( "Apache2::Connection object" )
       ret: $remotehost ( string/undef )
           If "$c->getremotehost" 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.

       since: 2.0.00

       It's best to to call "$c->getremotehost" instead of directly
       accessing this variable.

UUnnssuuppppoorrtteedd AAPPII
       "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 modperl development mailing list so we can help each
       other take the steps necessary to shift the method to an officially
       supported API.

       ""ccoonnnnccoonnffiigg""

       Config vector containing pointers to connections per-server config
       structures

         $ret = $c->connconfig();

       obj: $c ( "Apache2::Connection object" )
       ret: $ret ( "Apache2::ConfVector object" )
       since: 2.0.00

       ""ssbbhh""

       META: Autogenerated - needs to be reviewed/completed

       handle to scoreboard information for this connection

         $sbh = $c->sbh();

       obj: $c ( "Apache2::Connection object" )
       ret: $sbh (XXX)
       since: 2.0.00

       META: Not sure how this can be used from modperl at the moment. Unless
       "Apache2::Scoreboard" is extended to provide a hook to read from this
       variable.

SSeeee AAllssoo
       modperl 2.0 documentation.

CCooppyyrriigghhtt
       modperl 2.0 and its core modules are copyrighted under The Apache
       Software License, Version 2.0.

AAuutthhoorrss
       The modperl development team and numerous contributors.



perlavp5a.c8h.e8modperl-101.1~2::modp2e0r0l5-21.00-.220::docs::api::Apache2::Connection(3)