15.8 The Perl API

Team-Fly    

 
Webmaster in a Nutshell, 3rd Edition
By Robert Eckstein, Stephen Spainhour
Table of Contents
Chapter 15.  Web Server Programming with mod_perl

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.


Team-Fly    
Top


Webmaster in a Nutshell
Webmaster in a Nutshell, Third Edition
ISBN: 0596003579
EAN: 2147483647
Year: 2002
Pages: 412

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net