1<table border=1 cellpadding=0 cellspacing=0> 2<tr> 3 <th bgcolor=salmon>Request Information</th> 4 <th bgcolor=salmon>Connection Information</th> 5</tr> 6<td valign=top rowspan=3> 7 $r-><a href="#method">method</a>( [$meth] ) = <% $r->method() %><BR> 8 $r-><a href="#method_number">method_number</a>( [$num] ) = <% $r->method_number() %><BR> 9 $r-><a href="#bytes_sent">bytes_sent</a> = <% $r->bytes_sent %><BR> 10 $r-><a href="#the_request">the_request</a> = <% $r->the_request %><BR> 11 $r-><a href="#proxyreq">proxyreq</a> = <% $r->proxyreq %><BR> 12 $r-><a href="#header_only">header_only</a> = <% $r->header_only %><BR> 13 $r-><a href="#protocol">protocol</a> = <% $r->protocol %><BR> 14 $r-><a href="#uri">uri</a>( [$uri] ) = <% $r->uri() %><BR> 15 $r-><a href="#filename">filename</a>( [$filename] ) = <% $r->filename() %><BR> 16 $r-><a href="#path_info">path_info</a>( [$path_info] ) = <% $r->path_info() %><BR> 17 $r-><a href="#args">args</a> = <% $r->args %><BR> 18 $r-><a href="#header_in">header_in</a>( $header_name, [$value] ) = <% $r->header_in("Content-type") %><BR> 19 $r-><a href="#get_remote_host">get_remote_host</a> = <% $r->get_remote_host %><BR> 20 $r-><a href="#requires">requires</a> = <% $r->requires %><BR> 21 $r-><a href="#auth_type">auth_type</a> = <% $r->auth_type %><BR> 22 $r-><a href="#auth_name">auth_name</a> = <% $r->auth_name %><BR> 23 $r-><a href="#document_root">document_root</a> = <% $r->document_root %><BR> 24 $r-><a href="#allow_options">allow_options</a> = <% $r->allow_options %> 25</td> 26<td valign=top> 27% my $c = $r->connection; 28 $c-><a href="#remote_host">remote_host</a> = <%$c->remote_host%><BR> 29 $c-><a href="#remote_ip">remote_ip</a> = <%$c->remote_ip %><BR> 30 $c-><a href="#local_addr">local_addr</a> = <%$c->local_addr %><BR> 31 $c-><a href="#remote_addr">remote_addr</a> = <%$c->remote_addr %><BR> 32 $c-><a href="#remote_logname">remote_logname</a> = <%$c->remote_logname%><BR> 33 $c-><a href="#user">user</a> = <%$c->user %><BR> 34 $c-><a href="#auth_type">auth_type</a> = <%$c->auth_type %><BR> 35 $c-><a href="#aborted">aborted</a> = <%$c->aborted %> 36</td> 37</tr><tr> 38 <th bgcolor=salmon>Server Configuration</th> 39</tr><tr> 40<td valign=top> 41% my $s = $r->server; 42 $s-><a href="#server_admin">server_admin</a> = <% $s->server_admin %><BR> 43 $s-><a href="#server_hostname">server_hostname</a> = <%$s->server_hostname%><BR> 44 $s-><a href="#port">port</a> = <%$s->port%><BR> 45 $s-><a href="#is_virtual">is_virtual</a> = <%$s->is_virtual%><BR> 46 $s-><a href="#names">names</a> = <%$s->names%> 47</td> 48</tr></table> 49 50<P> 51<a name="method"> 52$r->method( [$meth] ) 53<blockquote> 54The $r->method method will return the request method. It will be a 55string such as ``GET'', ``HEAD'' or ``POST''. Passing an argument will 56set the method, mainly used for internal redirects. 57</blockquote> 58 59<a name="method_number"> 60$r->method_number( [$num] ) 61<blockquote> 62The $r->method_number method will return the request method 63number. The method numbers are defined by the M_GET, 64M_POST,... constants available from the Apache::Constants 65module. Passing an argument will set the method_number, mainly used 66for internal redirects and testing authorization restriction masks. 67</blockquote> 68 69<a name="bytes_sent"> 70$r->bytes_sent 71<blockquote> 72The number of bytes sent to the client, handy for logging, etc. 73</blockquote> 74 75<a name="the_request"> 76$r->the_request 77<blockquote> 78The request line send by the client, handy for logging, etc. 79</blockquote> 80 81<a name="proxyreq"> 82$r->proxyreq 83<blockquote> 84Returns true if the request is proxy http. Mainly used during the 85filename translation stage of the request, which may be handled by a 86PerlTransHandler. 87</blockquote> 88 89<a name="header_only"> 90$r->header_only 91<blockquote> 92Returns true if the client is asking for headers only, e.g. if the 93request method was HEAD. 94</blockquote> 95 96<a name="protocol"> 97$r->protocol 98<blockquote> 99The $r->protocol method will return a string identifying the protocol 100that the client speaks. Typical values will be ``HTTP/1.0'' or 101``HTTP/1.1''. 102</blockquote> 103 104<a name="uri"> 105$r->uri( [$uri] ) 106<blockquote> 107The $r->uri method will return the requested URI, optionally changing 108it with the first argument. 109</blockquote> 110 111<a name="filename"> 112$r->filename( [$filename] ) 113<blockquote> 114The $r->filename method will return the result of the URI --> filename 115translation, optionally changing it with the first argument if you 116happen to be doing the translation. 117</blockquote> 118 119<a name="path_info"> 120$r->path_info( [$path_info] ) 121<blockquote> 122The $r->path_info method will return what is left in the path after 123the URI --> filename translation, optionally changing it with the 124first argument if you happen to be doing the translation. 125</blockquote> 126 127<a name="args"> 128$r->args 129<blockquote> 130The $r->args method will return the contents of the URI query 131string. When called in a scalar context, the entire string is 132returned. When called in a list context, a list of parsed key => value 133pairs are returned, i.e. it can be used like this: 134</blockquote> 135 136<pre> 137 $query = $r->args; 138 %in = $r->args; 139</pre> 140<%doc> 141<a name="headers_in"> 142$r->headers_in 143The $r->headers_in method will return a %hash of client request headers. This can be used to initialize 144a perl hash, or one could use the $r->header_in() method (described below) to retrieve a specific 145header value directly. 146</%doc> 147 148<a name="header_in"> 149$r->header_in( $header_name, [$value] ) 150<blockquote> 151Return the value of a client header. Can be used like this: 152</blockquote> 153 154<pre> 155 $ct = $r->header_in("Content-type"); 156 $r->header_in($key, $val); #set the value of header '$key' 157</pre> 158 159<a name="content"> 160$r->content 161<blockquote> 162The $r->content method will return the entity body read from the 163client, but only if the request content type is 164application/x-www-form-urlencoded. When called in a scalar context, 165the entire string is returned. When called in a list context, a list 166of parsed key => value pairs are returned. *NOTE*: you can only ask 167for this once, as the entire body is read from the client. 168</blockquote> 169 170<a name="read_client_block"> 171$r->read_client_block($buf, $bytes_to_read) 172Read from the entity body sent by the client. Example of use: 173 174 $r->read_client_block($buf, $r->header_in('Content-length')); 175 176<a name="get_remote_host"> 177$r->get_remote_host= <% $r->get_remote_host %> 178<blockquote> 179Lookup the client's DNS hostname. If the configuration directive 180HostNameLookups is set to off, this returns the dotted decimal 181representation of the client's IP address instead. Might return undef 182if the hostname is not known. 183</blockquote> 184 185<a name="get_remote_logname"> 186$r->get_remote_logname = NOT IMPLEMENTED BY MOD_PERL 187<blockquote> 188Lookup the remote user's system name. Might return undef if the remote 189system is not running an RFC 1413 server or if the configuration 190directive IdentityCheck is not turned on. 191</blockquote> 192 193More information about the client can be obtained from the 194Apache::Connection object, as described below. 195<P> 196$c = $r->connection 197<blockquote> 198The $r->connection method will return a reference to the request 199connection object (blessed into the Apache::Connection package). This 200is really a conn_rec* in disguise. The following methods can be used 201on the connection object: 202</blockquote> 203 204<a name="remote_host"> 205$c->remote_host 206<blockquote> 207If the configuration directive HostNameLookups is set to on: then the 208first time $r->get_remote_host is called the server does a DNS lookup 209to get the remote client's host name. The result is cached in 210$c->remote_host then returned. If the server was unable to resolve the 211remote client's host name this will be set to ``''. Subsequent calls 212to $r->get_remote_host return this cached value. 213<P> 214If the configuration directive HostNameLookups is set to off: calls to 215$r->get_remote_host return a string that contains the dotted decimal 216representation of the remote client's IP address. However this string 217is not cached, and $c->remote_host is undefined. So, it's best to to 218call $r->get_remote_host instead of directly accessing this variable. 219</blockquote> 220 221<a name="remote_ip"> 222$c->remote_ip 223<blockquote> 224The dotted decimal representation of the remote client's IP 225address. This is set by then server when the connection record is 226created so is always defined. 227</blockquote> 228 229<a name="local_addr"> 230$c->local_addr 231<blockquote> 232A packed SOCKADDR_IN in the same format as returned by Socket, 233containing the port and address on the local host that the remote 234client is connected to. This is set by the server when the connection 235record is created so it is always defined. 236</blockquote> 237 238<a name="remote_addr"> 239$c->remote_addr 240<blockquote> 241A packed SOCKADDR_IN in the same format as returned by Socket, 242containing the port and address on the remote host that the server is 243connected to. This is set by the server when the connection record is 244created so it is always defined. 245<P> 246Among other things, this can be used, together with $c->local_addr, to 247perform RFC1413 ident lookups on the remote client even when the 248configuration directive IdentityCheck is turned off. 249<P> 250 251Can be used like: 252<pre> 253 use Net::Ident qw (lookupFromInAddr); 254 ... 255 my $remoteuser = lookupFromInAddr ($c->local_addr, 256 $c->remote_addr, 2); 257</pre> 258 259Note that the lookupFromInAddr interface does not currently exist in 260the Net::Ident module, but the author is planning on adding it soon. 261</blockquote> 262 263<a name="remote_logname"> 264$c->remote_logname 265<blockquote> 266If the configuration directive IdentityCheck is set to on: then the 267first time $r->get_remote_logname is called the server does an RFC 2681413 (ident) lookup to get the remote users system name. Generally for 269UNI* systems this is their login. The result is cached in 270$c->remote_logname then returned. Subsequent calls to 271$r->get_remote_host return the cached value. 272<P> 273If the configuration directive IdentityCheck is set to off: then 274$r->get_remote_logname does nothing and $c->remote_logname is always 275undefined. 276</blockquote> 277 278<a name="user"> 279$c->user 280<blockquote> 281If an authentication check was successful, the authentication handler 282caches the user name here. 283</blockquote> 284 285<a name="auth_type"> 286$c->auth_type 287<blockquote> 288Returns the authentication scheme that successfully authenticate 289$c->user, if any. 290</blockquote> 291 292<a name="aborted"> 293$c->aborted 294<blockquote> 295Returns true if the client stopped talking to us. 296</blockquote> 297 298<h2>SERVER CONFIGURATION INFORMATION </h2> 299 300The following methods are used to obtain information from server 301configuration and access control files. 302 303<a name="dir_config"> 304$r->dir_config( $key ) 305<blockquote> 306Returns the value of a per-directory variable specified by the 307PerlSetVar directive. 308</blockquote> 309<PRE> 310 # <Location /foo/bar> 311 # SetPerlVar Key Value 312 # </Location> 313 314 my $val = $r->dir_config('Key'); 315 316</PRE> 317 318<a name="requires"> 319$r->requires 320<blockquote> 321Returns an array reference of hash references, containing information 322related to the require directive. This is normally used for access 323control, see Apache for an example. 324</blockquote> 325 326<a name="auth_type"> 327$r->auth_type 328<blockquote> 329Returns a reference to the current value of the per directory 330configuration directive AuthType. Normally this would be set to Basic 331to use the basic authentication scheme defined in RFC 1945, Hypertext 332Transfer Protocol -- HTTP/1.0. However, you could set to something 333else and implement your own authentication scheme. 334</blockquote> 335 336<a name="auth_name"> 337$r->auth_name 338<blockquote> 339Returns a reference to the current value of the per directory 340configuration directive AuthName. The AuthName directive creates 341protection realm within the server document space. To quote RFC 1945 342``These realms allow the protected resources on a server to be 343partitioned into a set of protection spaces, each with its own 344authentication scheme and/or authorization database.'' The client uses 345the root URL of the server to determine which authentication 346credentials to send with each HTTP request. These credentials are 347tagged with the name of the authentication realm that created 348them. Then during the authentication stage the server uses the current 349authentication realm, from $r->auth_name, to determine which set of 350credentials to authenticate. 351</blockquote> 352 353<a name="document_root"> 354$r->document_root 355<blockquote> 356Returns a reference to the current value of the per server 357configuration directive DocumentRoot. To quote the Apache server 358documentation, ``Unless matched by a directive like Alias, the server 359appends the path from the requested URL to the document root to make 360the path to the document.'' This same value is passed to CGI scripts 361in the DOCUMENT_ROOT environment variable. 362</blockquote> 363 364<a name="allow_options"> 365$r->allow_options 366<blockquote> 367The $r->allow_options method can be used for checking if it is OK to 368run a perl script. The Apache::Options module provides the constants 369to check against. 370</blockquote> 371 372<pre> 373 if(!($r->allow_options & OPT_EXECCGI)) { 374 $r->log_reason("Options ExecCGI is off in this directory", 375 $filename); 376 } 377</pre> 378 379$s = $r->server 380<blockquote> 381Return a reference to the server info object (blessed into the 382Apache::Server package). This is really a server_rec* in disguise. The 383following methods can be used on the server object: 384</blockquote> 385 386$s = Apache->server 387<blockquote> 388Same as above, but only available during server startup for use in 389<Perl> sections, PerlScript or PerlModule. 390<blockquote> 391 392<a name="server_admin"> 393$s->server_admin 394<blockquote> 395Returns the mail address of the person responsible for this server. 396</blockquote> 397 398<a name="server_hostname"> 399$s->server_hostname 400<blockquote> 401Returns the hostname used by this server. 402</blockquote> 403 404<a name="port"> 405$s->port 406<blockquote> 407Returns the port that this servers listens too. 408</blockquote> 409 410<a name="is_virtual"> 411$s->is_virtual 412<blockquote> 413Returns true if this is a virtual server. 414</blockquote> 415 416<a name="names"> 417$s->names 418<blockquote> 419Returns the wild-carded names for HostAlias servers. 420</blockquote> 421 422<a name="warn"> 423$s->warn 424<blockquote> 425Alias for Apache::warn. 426</blockquote> 427 428<a name="log_error"> 429$s->log_error 430<blockquote> 431Alias for Apache::log_error. 432</blockquote> 433 434 435 436 437 438 439 440