NAME

Apache - Perl interface to the Apache server API

SYNOPSIS

   require Apache;

   #using API
   $req = Apache->request;

   $host = $req->get_remote_host;
   $user = $req->connection->user;

   $req->content_type("text/html");
   $req->send_http_header;  # actually start a reply

   $req->write_client (
        "Hey you from $host! <br>\n",
        "I bet your name is $user. <br>\n",
        "Yippe! <hr>\n",
   );

   ###################
   #or setup a CGI environment  
   $r = Apache->request;
   %ENV = $r->cgi_env;
   
   #Apache's i/o is not stream oriented
   #so you cannot print() to your script's STDOUT
   #and you cannont read() from STDIN (yet)
   $r->print (
          "Content-type: text/html\n\n",
          "Hey you from $ENV{REMOTE_HOST}! <br>\n",
          "I bet your name is $ENV{REMOTE_USER}. <br>\n",
          "Yippe! <hr>\n",
   );

DESCRIPTION

This module provides a Perl interface the Apache API. It's here mainly for mod_perl, but may be used for other Apache modules that wish to embed a Perl interpreter.

METHODS

request()

Create a request object. This is really a request_rec * in disguise.

 $req = Apache->request;

get_remote_host()

Lookup the client's hostname, return it if found.

 $remote_host = $req->get_remote_host();

content_type()

Get or set the content type being sent to the client.

   $type = $req->content_type;
   $req->content_type("text/plain");

content_encoding()

Get or set the content encoding.

   $enc = $req->content_encoding;
   $req->content_encoding("gzip");

content_language()

Get or set the content language.

   $lang = $req->content_language;
   $req->content_language("en");

status()

Get or set the reply status for the client request.

   $code = $req->status; 
   $req->status(200);    

status_line()

Get or set the response status line.

   $resp = $req->status_line;
   $req->status_line("HTTP/1.0 200 OK");

header_out()

Change the value of a response header, or create a new one.

   $req->header_out("WWW-Authenticate", "Basic");

err_header_out()

Change the value of an error response header, or create a new one.

   $req->err_headers_out("WWW-Authenticate", "Basic");

no_cache()

Boolean, on or off.

   $req->no_cache(1);

basic_http_header()

Send the response line along with 'Server' and 'Date' headers.

send_http_header()

Send the response line and all headers to the client. (Calls basic_http_header)

   $req->send_http_header;

internal_redirect_handler()

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

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

read_client_block()

Read entity body sent by the client.

   %headers_in = $req->headers_in;
   $req->read_client_block($buf, $headers_in{'Content-length'});

read()

Friendly alias for read_client_block()

   $req->read($buf, $headers_in{'Content-length'});

write_client()

Send a list of data to the client.

   $req->write_client(@list_of_data);

print()

Friendly alias for write_client()

   $req->print(@list_of_data);

send_fd()

Send the contents of a file to the client.

   $req->send_fd(FILE_HANDLE);

log_reason()

The request failed, why??

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

log_error()

Uh, oh.

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

cgi_env()

Setup a standard CGI environment.

  %ENV = $req->cgi_env();

NOTE: '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
  }
                

send_cgi_header()

Take action on certain headers including 'Status', 'Location' and 'Content-type' just as mod_cgi does, then calls send_http_header().

    $req->send_cgi_header(<<EOF);
 Location: /foo/bar
 Content-type: text/html 

 EOF

headers_in()

Return a %hash of client request headers.

  %headers_in = $req->headers_in();

header_in()

Return the value of a client header.

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

args()

Return the contents of the 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.

  $query_string = $req->args;

  #split on '&' and '='
  %in = $req->args;

content()

Return the entity body as read from the client. 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.

 $content = $req->content;

  #split on '&' and '='
  %in = $req->content;

unescape_url()

Handy function for unescapes.

  Apache::unescape_url($string);

allow_options(), is_perlaliased()

Methods for checking if it's ok to run a perl script.

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

more request info

   $method = $req->method;         #GET, POST, etc.
   $protocol = $req->protocol;     #HTTP/1.x
   $uri = $req->uri;               #requested uri
   $script_file = $req->filename;  #the uri->filename translation
   $path_info = $req->path_info;   #path_info

connection()

Return an object reference to the request connection. This is really a conn_rec * in disguise.

 $conn = $req->connection; 
 $remote_host = $conn->remote_host;
 $remote_ip = $conn->remote_ip;
 $remote_logname = $conn->remote_logname;
 
 #The remote username if authenticated.
 $remote_user = $conn->user;

 #The authentication scheme used, if any.
 $auth_type = $conn->auth_type;

 #close connection to the client
 $conn->close;
 

server()

Return an object reference to the server info. This is really a server_rec * in disguise.

 $srv = $req->server; 
 $server_admin = $srv->server_admin;
 $hostname = $srv->server_hostname;
 $port = $srv->port;

SEE ALSO

 perl(1), Apache::Registry(3), Apache::CGI(3), Apache::Debug(3), Apache::Options(3)

AUTHORS

Gisle Aas <aas@oslonett.no> and Doug MacEachern <dougm@osf.org>