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);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 subroutine log_error (defined in and importable from Netscape::Server). log_error has the following usage
log_error($degree, $sub, $sn, $rq, $gripe);$degree is one of the constants defined below; 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_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.
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.)
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 and the log_error() function.
AUTHOR
Benjamin Sugars <bsugars@canoe.ca>
SEE ALSO
perl(1), nsapi_perl, Netscape::Server::Session, Netscape::Server::Request