start page | rating of books | rating of authors | reviews | copyrights

Book HomeWebmaster in a Nutshell, 3rd EditionSearch this book

15.8. The Perl API

The Apache API is a set of routines that C programmers can use to write Apache modules. One of the most powerful features of mod_perl is its Perl API, which gives Perl programmers access to the Apache API. For information on how to program Apache modules in Perl, see Writing Apache Modules in Perl and C by Lincoln Stein and Doug MacEachern (O'Reilly).

The following methods are defined for the Perl API to Apache.

aborted

$c->aborted 

Returns true if the client aborted the transaction.

allow_options

$r->allow_options 

Checks the options allowed for this request.

allowed

$r->allowed($bitmask)

Gets or sets the "allowed methods" bitmask.

args

$r->args( [$query_string] )

Returns the query string portion of the URI either as a string (scalar context) or as a list of key/value pairs (list context).

as_string

$r->as_string

Returns a string representation of the request object.

auth_name

$r->auth_name

Returns a reference to the value of the AuthName directive.

auth_type

$c->auth_type

Returns the authentication scheme.

auth_type

$r->auth_type

Returns a reference to the value of the AuthType directive.

bytes_sent

$r->bytes_sent

Returns the number of bytes sent to the client.

connection

$c = $r->connection

Returns a reference to the request connection object.

content

$r->content

If the request content type is application/x-www-form-urlencoded, returns the entity body either as a string (scalar context) or as a list of key/value pairs (list context).

content_encoding

$r->content_encoding( [$value] )

Returns the content encoding of the entity.

content_languages

$r->content_languages( [$ref] )

Returns the content language(s) of the entity as an array reference.

content_type

$r->content_type( [$value] )

Returns the content type of the entity.

current_callback

$r->current_callback

Returns the name of the current handler.

custom_response

$r->custom_response($code, $uri)

Creates a custom response for the specified response code.

dir_config

$r->dir_config( $key )

Returns the value associated with $key as specified by the PerlSetVar directive.

dir_config

$s->dir_config( $key )

Same as Apache::dir_config.

document_root

$r->document_root ( [$docroot] )

Returns a reference to the value of the DocumentRoot directive.

err_header_out

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

Retrieves a specific response header when an error is encountered.

err_headers_out

$r->err_headers_out

Returns a hash of server response headers when an error is encountered.

filename

$r->filename( [$filename] )

Returns the filename that the URI resolves to.

fileno

$c->fileno( [$n] )

Returns either the client output file descriptor, or the input file descriptor if an argument of 0 is given.

get

$r->dir_config->get( $key )

Returns the value associated with $key as specified by the PerlAddVar directive.

get_basic_auth_pw

$r->get_basic_auth_pw

Reports whether the request uses Basic authentication, or returns a value such as AUTH_REQUIRED that needs to be conveyed back to the client.

get_handlers

$r->get_handlers( $phase )

Returns a reference to a list of handlers enabled for the specified request phase.

get_remote_host

$r->get_remote_host

Returns the client's DNS hostname.

get_remote_logname

$r->get_remote_logname

Returns the client's login name.

get_server_port

$r->get_server_port

Returns server's port number.

gid

$s->gid

Returns the group ID under the server uses.

handler

$r->handler( [$meth] )

Specifies the handler for the request.

hard_timeout

$r->hard_timeout($string)

Performs a hard timeout with the specified message.

header_only

$r->header_only

Returns true if the request method is HEAD.

header_out

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

Retrieves a specific response header.

headers_in

$r->headers_in

Returns a hash of client request headers.

headers_out

$r->headers_out

Returns a hash of server response headers.

hostname

$r->hostname

Returns the server hostname.

internal_redirect

$r->internal_redirect( $location )

Redirects transparently to a different location on the server.

internal_redirect_handler

$r->internal_redirect_handler( $location )

Redirects transparently to a different location on the server, preserving the handler.

is_initial_req

$r->is_initial_req

Returns true if the current request is the first request.

is_main

$r->is_main

Returns true if the main request is current.

is_virtual

$s->is_virtual

Returns true for virtual servers.

kill_timeout

$r->kill_timeout

Performs a kill timeout.

last

$r->last

Returns a reference to the last request structure.

local_addr

$c->local_addr

Returns the port and address on the local host.

location

$r->location

Returns the location that the current Perl handler is being called from.

log_error

$r->log_error($message)

Logs a message to the error log.

log_error

$s->log_error

Same as Apache::log_error.

log_reason

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

Logs a message to the specified error log.

loglevel

$s->loglevel

Returns the current LogLevel.

lookup_file

$r->lookup_file($filename)

Looks up the specified file.

lookup_uri

$r->lookup_uri($uri)

Looks up the specified URI.

main

$r->main

Returns a reference to the main request, or undef if the current request is the main request.

method

$r->method( [$meth] )

Returns the request method.

method_number

$r->method_number( [$num] )

Returns the request method number as defined by the M_GET and M_POST,... constants available from the Apache::Constants module.

names

$s->names

Returns aliases for the server.

next

$r->next

Returns a reference to the next request or undef if there is none.

no_cache

$r->no_cache( $boolean )

Specifies whether the returned data should be cached.

note_basic_auth_failure

$r->note_basic_auth_failure

Sets the HTTP headers requesting authentication for the realm.

notes

$r->notes( $key, [$value] )

Returns (or sets) a value from the Apache notes table. See also pnotes.

path_info

$r->path_info( [$path_info] )

Returns the path_info portion of the URI.

perl_hook

Apache::perl_hook($hook)

Reports whether the specified callback hook is in effect.

pnotes

$r->pnotes( $key, [$value] )

Returns (or sets) a value from the Apache notes table, taking any scalar as $value. The value is cleaned up after every request.

port

$s->port

Returns the server's port number.

post_connection

$r->post_connection($code_ref)

Registers a cleanup function.

prev

$r->prev

Returns a reference to the previous request or undef if there is none.

print

$r->print( @list )

Sends the specified data to the client.

protocol

$r->protocol

Returns the HTTP protocol that the client uses.

proxyreq

$r->proxyreq

Returns true if the request is a proxy request.

push_handlers

$r->push_handlers( $phase, \&handler )

Specifies a new handler to be called for the specified request phase.

read

$r->read($buf, $num_bytes, [$offset])

Reads data from the client starting at the optional $offset until it reaches $num_bytes or reaches a timeout.

register_cleanup

$r->register_cleanup($code_ref)

Registers a cleanup function.

remote_addr

$c->remote_addr

Returns the port and address on the remote host.

remote_host

$c->remote_host

Returns the client's hostname.

remote_ip

$c->remote_ip

Returns the client's IP address.

remote_logname

$c->remote_logname

Returns the remote user's login name.

request

Apache->request([$r])

Returns a reference to the request object.

request_time

$r->request_time

Returns the timestamp of the request.

requires

$r->requires

Returns an array reference with information relating to the require directive.

reset_timeout

$r->reset_timeout

Resets the current timeout.

run

$subr->run

Executes the subroutine.

send_cgi_header

$r->send_cgi_header()

Specifies CGI headers and calls send_http_header().

send_fd

$r->send_fd( $filehandle )

Sends the specified file to the client.

send_http_header

$r->send_http_header( [$content_type] )

Sends the http header to the client.

server

$s = $r->server

Return a reference to the server info object. Can also be used without a request object (i.e,, Apache->server) for startup files.

server_admin

$s->server_admin

Returns the webmaster's email address.

server_hostname

$s->server_hostname

Returns the server's hostname.

server_root_relative

$r->server_root_relative( [$path] )

Returns the value of the ServerRoot directory, or concatenates $path to that value. Can also be used without a request object (i.e., Apache->server_root_relative) for startup files.

set_handlers

$r->set_handlers( $phase, [\&handler, ... ] )

Specifies the handlers to be called for the specified request phase.

soft_timeout

$r->soft_timeout($string)

Performs a soft timeout with the specified message.

status

$r->status( $integer )

Returns the 3-digit response status code for the request.

status_line

$r->status_line( $string )

Returns the response status string for the request.

subprocess_env

$r->subprocess_env( $key, [$value] )

Returns (or sets) a value from the Apache subprocess_env table.

the_request

$r->the_request

Returns the request line sent by the client.

uid

$s->uid

Returns the user ID the server uses.

unescape_url

Apache::unescape_url($string)

Removes escapes for the specified URL.

unescape_url_info

Apache::unescape_url_info($string)

Removes escapes from the specified form data.

uri

$r->uri( [$uri] )

Returns the requested URI.

user

$c->user( [$user] )

Returns the authenticated user name.

warn

$r->warn($message)

Logs a message to the error log. Only works if the LogLevel is "warn" or higher under Apache 1.3 and later.

warn

$s->warn

Same as Apache::warn.



Library Navigation Links

Copyright © 2003 O'Reilly & Associates. All rights reserved.