• NAME
• SYNOPSIS
• DESCRIPTION
• THE REQUEST OBJECT
• CLIENT REQUEST PARAMETERS
• SERVER CONFIGURATION INFORMATION
• SETTING UP THE RESPONSE
• SERVER CORE FUNCTIONS
• CGI SUPPORT
• ERROR LOGGING
• UTILITY FUNCTIONS
• SEE ALSO
• AUTHORS

NAME

SYNOPSIS

   use Apache ();

DESCRIPTION

THE REQUEST OBJECT

Apache->request([$r])

The Apache->request method will return a reference to the request object.

Perl*Handler's can obtain a reference to the request object when it is passed to them via @_. However, scripts that run under Registry, for example, need a way to access the request object. Registry will make a request object availible to these scripts by passing it's object reference to Apache-request>. If handlers use modules such as Apache::CGI that need to access Apache-request>, they too should do this (e.g. Apache::Status).

$r->main

If the current request is a sub-request, this method returns a blessed reference to the main request structure.

$r->is_main

Returns true if the current request object is for the main request.

CLIENT REQUEST PARAMETERS

$r->method( [$meth] )

The $r->method method will return the request method. It will be a string such as ``GET'', ``HEAD'' or ``POST''. Passing an argument will set the method, mainly used for internal redirects.

$r->method_number( [$num] )

The $r->method_number method will return the request method number. Each number corresponds to a string representation such as ``GET'', ``HEAD'' or ``POST''. Passing an argument will set the method_number, mainly used for internal redirects and testing authorization restriction masks.

$r->the_request

The request line send by the client, handy for logging, etc.

$r->proxyreq

Returns true if the request is proxy http. Mainly used during the filename translation stage of the request, which may be handled by a PerlTransHandler.

$r->header_only

Returns true if the client is asking for headers only, e.g. if the request method was HEAD.

$r->protocol

The $r->protocol method will return a string identifying the protocol that the client speaks. Typical values will be ``HTTP/1.0'' or ``HTTP/1.1''.

$r->uri( [$uri] )

The $r->uri method will return the requested URI, optionally changing it with the first argument.

$r->filename( [$filename] )

The $r->filename method will return the result of the URI --> filename translation, optionally changing it with the first argument if you happen to be doing the translation.

$r->path_info( [$path_info] )

The $r->path_info method will return what's left in the path after the URI --> filename translation, optionally changing it with the first argument if you happen to be doing the translation.

$r->args

The $r->args method will return the contents of the URI's query string. When called in a scalar context, the entire string is returned. When called in a list context, a list of parsed key => value pairs are returned, i.e. it can be used like this:

  $query = $r->args;
  %in    = $r->args;

$r->headers_in

The $r->headers_in method will return a %hash of client request headers. This can be used to initialize a perl hash, or one could use the $r->header_in() method (described below) to retrieve a specific header value directly.

$r->header_in( $header_name, [$value] )

Return the value of a client header. Can be used like this:

  $ct = $r->header_in("Content-type");

  $r->header_in($key, $val); #set the value of header '$key'

$r->content

The $r->content method will return the entity body read from the client, but only if the request content type is application/x-www-form-urlencoded. When called in a scalar context, the entire string is returned. When called in a list context, a list of parsed key => value pairs are returned. *NOTE*: you can only ask for this once, as the entire body is read from the client.

$r->read_client_block($buf, $bytes_to_read)

Read from the entity body sent by the client. Example of use:

  $r->read_client_block($buf, $r->header_in('Content-length'));

$r->read($buf, $bytes_to_read)

This method uses read_client_block to read data from the client, looping until it gets all of $bytes_to_read or a timeout happens.

In addition, this method sets a timeout before reading with $r-hard_timeout>

$r->get_remote_host

Lookup the client's DNS hostname. Might return undef if the hostname is not known.

$c = $r->connection

The $r->connection method will return a reference to the request connection object (blessed into the Apache::Connection package). This is really a conn_rec* in disguise. The following methods can be used on the connection object:

$c->remote_host

$c->remote_ip

$c->remote_logname

$c->user; #Returns the remote username if authenticated.

$c->auth_type; #Returns the authentication scheme used, if any.

$c->aborted; #returns true if the client stopped talking to us

$c->close; #Calling this method will close down the connection to the client

SERVER CONFIGURATION INFORMATION

$r->dir_config( $key )

Returns the value of a per-directory variable specified by the PerlSetVar directive.

 #<Location /foo/bar>
 #SetPerlVar  Key  Value
 #</Location>

 my $val = $r->dir_config('Key');

$r->requires

Returns an array reference of hash references, containing information related to the require directive. This is normally used for access control, see AuthzAge for an example.

$r->allow_options

The $r->allow_options method can be used for checking if it's ok to run a perl script. The Apache::Options module provide the constants to check against.

 if(!($r->allow_options & OPT_EXECCGI)) {
     $r->log_reason("Options ExecCGI is off in this directory", 
		    $filename);
 }

$s = $r->server

Return a reference to the server info object (blessed into the Apache::Server package). This is really a server_rec* in disguise. The following methods can be used on the server object:

$s->server_admin

Returns the mail address of the person responsible for this server.

$s->server_hostname

Returns the hostname used by this server.

$s->port

Returns the port that this servers listens too.

$s->is_virtal

Returns true if this is a virtual server.

$s->names

Returns the wildcarded names for HostAlias servers.

SETTING UP THE RESPONSE

$r->send_http_header

Send the response line and all headers to the client. (This method will actually call $r->basic_http_header first).

This method will create headers from the $r->content_xxx() and $r->no_cache() attributes (described below) and then append the headers defined by $r->header_out (or $r->err_header_out if status indicates an error).

$r->get_basic_auth_pw

If the current request is protected by Basic authentication, this method will return 0, otherwise -1. The second return value will be the decoded password sent by the client.

    ($ret, $sent_pw) = $r->get_basic_auth_pw;

$r->note_basic_auth_failure

Prior to requiring Basic authentication from the client, this method will set the outgoing HTTP headers asking the client to authenticate for the realm defined by the configuration directive AuthName.

$r->handler( [$meth] )

Set the handler for a request. Normally set by the configuration directive AddHandler. $r->handler( ``perl-script'' );

$r->content_type( [$newval] )

Get or set the content type being sent to the client. Content types are strings like ``text/plain'', ``text/html'' or ``image/gif''. This corresponds to the ``Content-Type'' header in the HTTP protocol. Example of usage is:

   $previous_type = $r->content_type;
   $r->content_type("text/plain");

$r->content_encoding( [$newval] )

Get or set the content encoding. Content encodings are string like ``gzip'' or ``compress''. This correspond to the ``Content-Encoding'' header in the HTTP protocol.

$r->content_language( [$newval] )

Get or set the content language. The content language corresponds to the ``Content-Language'' HTTP header and is a string like ``en'' or ``no''.

$r->status( $integer )

Get or set the reply status for the client request. The Apache::Constants module provide mnemonic names for the status codes.

$r->status_line( $string )

Get or set the response status line. The status line is a string like ``HTTP/1.0 200 OK'' and it will take precedence over the value specified using the $r->status() described above.

$r->headers_out

The $r->headers_out method will return a %hash of server response headers. This can be used to initialize a perl hash, or one could use the $r->header_out() method (described below) to retrieve or set a specific header value directly.

$r->header_out( $header, $value )

Change the value of a response header, or create a new one. You should not define any ``Content-XXX'' headers by calling this method, because these headers use their own specific methods. Example of use:

   $r->header_out("WWW-Authenticate" => "Basic");

   $val = $r->header_out($key);

$r->err_headers_out

The $r->err_headers_out method will return a %hash of server response headers. This can be used to initialize a perl hash, or one could use the $r->err_header_out() method (described below) to retrieve or set a specific header value directly.

The difference between headers_out and err_headers_out is that the latter are printed even on error, and persist across internal redirects (so the headers printed for ErrorDocument handlers will have them).

$r->err_header_out( $header, [$value] )

Change the value of an error response header, or create a new one. These headers are used if the status indicates an error.

   $r->err_header_out("Warning" => "Bad luck");

   $val = $r->err_header_out($key);

$r->no_cache( $boolean )

This is a flag that indicates that the data being returned is volatile and the client should be told not to cache it.

$r->write_client( @list_of_data )

Send data to the client. Unless you know what you are doing, you should only call this method after you have called $r->send_http_header.

$r->print()

This method sends data to the client with $r-write_client>, but first sets a timeout before sending with $r-hard_timeout>.

$r->send_fd( $filehandle )

Send the contents of a file to the client. Can for instance be used like this:

  open(FILE, $r->filename) || return 404;
  $r->send_fd(FILE);
  close(FILE);

$r->internal_redirect_handler( $newplace )

Redirect to a location in the server's namespace without telling the client. For instance:

  $r->internal_redirect_handler("/home/sweet/home.html");

SERVER CORE FUNCTIONS

$r->soft_timeout($message)

$r->hard_timeout($message)

$r->kill_timeout

$r->reset_timeout

(Documentation borrowed from http_main.h)

There are two functions which modules can call to trigger a timeout (with the per-virtual-server timeout duration); these are hard_timeout and soft_timeout.

The difference between the two is what happens when the timeout expires (or earlier than that, if the client connection aborts) --- a soft_timeout just puts the connection to the client in an ``aborted'' state, which will cause http_protocol.c to stop trying to talk to the client, but otherwise allows the code to continue normally. hard_timeout, by contrast, logs the request, and then aborts it completely --- longjmping out to the accept loop in http_main. Any resources tied into the request's resource pool will be cleaned up; everything that isn't will leak.

soft_timeout is recommended as a general rule, because it gives your code a chance to clean up. However, hard_timeout may be the most convenient way of dealing with timeouts waiting for some external resource other than the client, if you can live with the restrictions.

When a hard timeout is in scope, critical sections can be guarded with block_alarms and unblock_alarms --- these are declared in alloc.c because they are most often used in conjunction with routines to allocate something or other, to make sure that the cleanup does get registered before any alarm is allowed to happen which might require it to be cleaned up; they * are, however, implemented in http_main.c.

kill_timeout will disarm either variety of timeout.

reset_timeout resets the timeout in progress.

CGI SUPPORT

$r->cgi_env

Return a %hash that can be used to set up a standard CGI environment. Typical usage would be:

  %ENV = $r->cgi_env

NOTE: The $ENV{GATEWAY_INTERFACE} is set to 'CGI-Perl/1.1' so you can say:

  if($ENV{GATEWAY_INTERFACE} =~ /^CGI-Perl/) {
      #do mod_perl stuff
  }
  else {
     #do normal CGI stuff
  }

When given a key => value pair, this will set an environment variable.

 $r->cgi_env(REMOTE_GROUP => "camels");

$r->cgi_var($key);

Calls $r->cgi_env($key) in a scalar context to prevent the mistake of calling in a list context.

    my $doc_root = $r->cgi_env('DOCUMENT_ROOT');

$r->send_cgi_header()

Take action on certain headers including Status:, Location: and Content-type: just as mod_cgi does, then calls $r->send_http_header(). Example of use:

  $r->send_cgi_header("
  Location: /foo/bar
  Content-type: text/html 
  
  ");

ERROR LOGGING

$r->log_reason($message, $file)

The request failed, why?? Write a message to the server's errorlog.

   $r->log_reason("Because I felt like it", $r->filename);

$r->log_error($message)

Uh, oh. Write a message to the server's errorlog.

  $r->log_error("Some text that goes in the error_log");

UTILITY FUNCTIONS

Apache::unescape_url($string)

Handy function for unescapes.

Apache::perl_hook($hook)

Test to see if a callback hook is enabled

 for (qw(Access Authen Authz Fixup HeaderParser Log Trans Type)) {
    print "$_ hook enabled\n" if Apache::perl_hook($_);
 }  

SEE ALSO

AUTHORS