Benjamin Sugars > nsapi_perl-0.24 > Netscape::Server

Download:
nsapi_perl-0.24.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.24   Source  

NAME ^

Netscape::Server - framework for integrating Perl and Netscape servers

SYNOPSIS ^

 use Netscape::Server;
 use Netscape::Server qw/:request_codes/;
 use Netscape::Server qw/:protocol_codes/;
 use Netscape::Server qw/:error_codes/;
 use Netscape::Server qw/:all/;

 log_error($degree, $sub, $sn, $rq, $gripe);
 func_exec($fname, $sn, $rq, $args);

DESCRIPTION ^

The Netscape::Server module provides a framework for other modules that implement an interface between Perl and the Netscape Server Application Programming Interface (NSAPI). Netscape::Server provides definitions of the various NSAPI constants and server functions for error logging.

For an overview of integrating Perl and NSAPI, see nsapi_perl. Suffice it to say here that nsapi_perl provides a mechanism by which a Perl interpreter is embedded into a Netscape server. The NSAPI can then be programmed to in Perl rather than in C. This is achieved by placing the appropriate hooks in the server configuration files; nsapi_perl will then call whatever Perl subroutines you wish at various stages of processing a request from a client.

Perl modules interfacing to the NSAPI will require access to the structures and constants defined in the NSAPI C header files. The two structures defined in these header files that are of most interest are the Session structure and the Request structure. These two structures are represented in Perl by instances of the Netscape::Server::Request and Netscape::Server::Session classes; see their individual man pages for full details.

The rest of this document describes the constants and functions declared in the NSAPI header files that are accessible through the Netscape::Server module.

IMPORTABLE CONSTANTS ^

Importable from the point of view of whoever is using Netscape::Server, that is.

NSAPI constants of interest to Perl fall into the following categories (for full details, see your Netscape Server documentation or the NSAPI header files).

Request-Response Codes

Request-Response codes are those constants that NSAPI C functions return to the server to tell the server what to do next. Similarly, Perl subroutines called from nsapi_perl should return one of these constants.

REQ_PROCEED

Returned by a subroutine when it has performed its task without a problem.

REQ_NOACTION

Returned by a subroutine when conditions indicate it is not appropriate for the subroutine to perform its task.

REQ_ABORTED

Returned by a subroutine when an error has occurred an the client's request cannot be completed.

REQ_EXIT

Returned by a subroutine when a read or write error to or from the client has occurred and no further communication with the client is possible.

See nsapi_perl for a description of how the server behaves when a particular constant is returned from a subroutine.

Protocol-Status Codes

Subroutines should use these constants to set the HTTP status of the server's response to the request. This should be done (using the protocol_status() method of either Netscape::Server::Session or Netscape::server::Request) before any data is sent to the client. These constants have exact analogs in the definition of the http protocol itself.

PROTOCOL_OK

Request can be fulfilled no problem.

PROTOCOL_REDIRECT

The client making the request should be sent to another URL.

PROTOCOL_NOT_MODIFIED

The requested object has not been modified since the date indicated by the client in its initial request.

PROTOCOL_BAD_REQUEST

The request was not understandable.

PROTOCOL_UNAUTHORIZED

The client did not supply proper authorization to access the requested object.

PROTOCOL_FORBIDDEN

The client is explicitly forbidden to access the requested object.

PROTOCOL_NOT_FOUND

The requested object could not be found.

PROTOCOL_SERVER_ERROR

An internal server error has occurred.

PROTOCOL_NOT_IMPLEMENTED

The server has been asked to do something it knows it cannot do.

Error-Logging Codes

Error-logging codes are used by subroutines when an error has occurred. In particular, when an error occurs, the subroutine should call the function log_error(); see "FUNCTIONS" for more details.

LOG_INFORM

An informational message.

LOG_WARN

A warning message.

LOG_MISCONFIG

An internal misconfiguration or permission problem.

LOG_SECURITY

An authentication failure.

LOG_FAILURE

A problem internal to your subroutine.

LOG_CATASTROPHE

A non-recoverable server error.

FUNCTIONS ^

The following functions may be imported in to the calling package's namespace.

log_error
 $success = log_error($degree, $sub, $sn, $rq, $gripe);

$degree is one of the constants defined in "Error-Logging Code"; it specifies the severity of your problem. $sub is a string that should contain the name of the subroutine producing the error. $sn is an instance of Netscape::Server::Session. $rq is an instance of Netscape::Server::Request. $gripe is an excuse for the error you have begat; make it a good one.

log_error returns true if the error has been successfully logged; undef otherwise (Note: the log_error function for the servers I have access to produces different return values than what the documentation says I should expect. I have built the perl log_error() function based on the return values I have emprically determined. If Netscape changes their API to agree with the documentation, the perl log_error() function might break.)

func_exec
 $proceed = func_exec($fname, $sn, $rq, $args);
 $proceed = func_exec($fname, $sn, $rq);

Call a function from the NSAPI. Returns REQ_ABORTED if no function was executed, or the return code of the called function. $fname is the function name, as it would appear in a directive line from obj.conf. $sn is an instance of Netscape::Server::Session. $rq is an instance of Netscape::Server::Request. The optional $args is a reference to a hash containing argument and value pairs.

Example:

  $proceed = func_exec('find-index', $sn, $rq,
               {'index-names' => 'my_index'});

IMPORT TAGS ^

A module wishing to import Netscape::Server symbols into its namespace can use the following tags as arguments to the use Netscape::Server call.

:request_codes

Import the constants request-response codes like REQ_PROCEED, REQ_NOACTION, etc.

:protocol_codes

Import the protocol-status codes like PROTOCOL_OK, PROTOCOL_REDIRECT, etc.

:error_codes

Import the error-logging codes like LOG_INFORM, LOG_WARN, etc. This tag also imports the log_error() function.

:all

Import all constant symbols, the log_error() and func_exec() functions.

AUTHOR ^

Benjamin Sugars <bsugars@canoe.ca>

Contributions from Steve Nielsen <spn@enteract.com> and Olivier Dehon <dehon_olivier@jpmorgan.com>.

SEE ALSO ^

perl(1), nsapi_perl, Netscape::Server::Session, Netscape::Server::Request

syntax highlighting: