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