15.8. The Perl APIThe 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.
$c->aborted Returns true if the client aborted the transaction.
$r->allow_options Checks the options allowed for this request.
$r->allowed($bitmask) Gets or sets the "allowed methods" bitmask.
$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).
$r->as_string Returns a string representation of the request object.
$r->auth_name Returns a reference to the value of the AuthName directive.
$c->auth_type Returns the authentication scheme.
$r->auth_type Returns a reference to the value of the AuthType directive.
$r->bytes_sent Returns the number of bytes sent to the client.
$c = $r->connection Returns a reference to the request connection object.
$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).
$r->content_encoding( [$value] ) Returns the content encoding of the entity.
$r->content_languages( [$ref] ) Returns the content language(s) of the entity as an array reference.
$r->content_type( [$value] ) Returns the content type of the entity.
$r->current_callback Returns the name of the current handler.
$r->custom_response($code, $uri) Creates a custom response for the specified response code.
$r->dir_config( $key ) Returns the value associated with $key as specified by the PerlSetVar directive.
$s->dir_config( $key ) Same as Apache::dir_config.
$r->document_root ( [$docroot] ) Returns a reference to the value of the DocumentRoot directive.
$r->err_header_out( $header, [$value] ) Retrieves a specific response header when an error is encountered.
$r->err_headers_out Returns a hash of server response headers when an error is encountered.
$r->filename( [$filename] ) Returns the filename that the URI resolves to.
$c->fileno( [$n] ) Returns either the client output file descriptor, or the input file descriptor if an argument of 0 is given.
$r->dir_config->get( $key ) Returns the value associated with $key as specified by the PerlAddVar directive.
$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.
$r->get_handlers( $phase ) Returns a reference to a list of handlers enabled for the specified request phase.
$r->get_remote_host Returns the client's DNS hostname.
$r->get_remote_logname Returns the client's login name.
$r->get_server_port Returns server's port number.
$s->gid Returns the group ID under the server uses.
$r->handler( [$meth] ) Specifies the handler for the request.
$r->hard_timeout($string) Performs a hard timeout with the specified message.
$r->header_only Returns true if the request method is HEAD.
$r->header_out( $header, $value ) Retrieves a specific response header.
$r->headers_in Returns a hash of client request headers.
$r->headers_out Returns a hash of server response headers.
$r->hostname Returns the server hostname.
$r->internal_redirect( $location ) Redirects transparently to a different location on the server.
$r->internal_redirect_handler( $location ) Redirects transparently to a different location on the server, preserving the handler.
$r->is_initial_req Returns true if the current request is the first request.
$r->is_main Returns true if the main request is current.
$s->is_virtual Returns true for virtual servers.
$r->kill_timeout Performs a kill timeout.
$r->last Returns a reference to the last request structure.
$c->local_addr Returns the port and address on the local host.
$r->location Returns the location that the current Perl handler is being called from.
$r->log_error($message) Logs a message to the error log.
$s->log_error Same as Apache::log_error.
$r->log_reason($message, $logfile) Logs a message to the specified error log.
$s->loglevel Returns the current LogLevel.
$r->lookup_file($filename) Looks up the specified file.
$r->lookup_uri($uri) Looks up the specified URI.
$r->main Returns a reference to the main request, or undef if the current request is the main request.
$r->method( [$meth] ) Returns the request method.
$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.
$s->names Returns aliases for the server.
$r->next Returns a reference to the next request or undef if there is none.
$r->no_cache( $boolean ) Specifies whether the returned data should be cached.
$r->note_basic_auth_failure Sets the HTTP headers requesting authentication for the realm.
$r->notes( $key, [$value] ) Returns (or sets) a value from the Apache notes table. See also pnotes.
$r->path_info( [$path_info] ) Returns the path_info portion of the URI.
Apache::perl_hook($hook) Reports whether the specified callback hook is in effect.
$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.
$s->port Returns the server's port number.
$r->post_connection($code_ref) Registers a cleanup function.
$r->prev Returns a reference to the previous request or undef if there is none. $r->print( @list ) Sends the specified data to the client.
$r->protocol Returns the HTTP protocol that the client uses.
$r->proxyreq Returns true if the request is a proxy request.
$r->push_handlers( $phase, \&handler ) Specifies a new handler to be called for the specified request phase.
$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.
$r->register_cleanup($code_ref) Registers a cleanup function.
$c->remote_addr Returns the port and address on the remote host.
$c->remote_host Returns the client's hostname.
$c->remote_ip Returns the client's IP address.
$c->remote_logname Returns the remote user's login name.
Apache->request([$r]) Returns a reference to the request object.
$r->request_time Returns the timestamp of the request.
$r->requires Returns an array reference with information relating to the require directive.
$r->reset_timeout Resets the current timeout.
$subr->run Executes the subroutine.
$r->send_cgi_header() Specifies CGI headers and calls send_http_header().
$r->send_fd( $filehandle ) Sends the specified file to the client.
$r->send_http_header( [$content_type] ) Sends the http header to the client.
$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.
$s->server_admin Returns the webmaster's email address.
$s->server_hostname Returns the server's hostname.
$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.
$r->set_handlers( $phase, [\&handler, ... ] ) Specifies the handlers to be called for the specified request phase.
$r->soft_timeout($string) Performs a soft timeout with the specified message.
$r->status( $integer ) Returns the 3-digit response status code for the request.
$r->status_line( $string ) Returns the response status string for the request.
$r->subprocess_env( $key, [$value] ) Returns (or sets) a value from the Apache subprocess_env table.
$r->the_request Returns the request line sent by the client.
$s->uid Returns the user ID the server uses.
Apache::unescape_url($string) Removes escapes for the specified URL.
Apache::unescape_url_info($string) Removes escapes from the specified form data.
$r->uri( [$uri] ) Returns the requested URI.
$c->user( [$user] ) Returns the authenticated user name.
$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. Copyright © 2003 O'Reilly & Associates. All rights reserved. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|