NAME

Netscape::Server::Socket - Netscape httpd/client socket class

SYNOPSIS

use Netscape::Server::Socket;
tie(*FILEHANDLE, 'Netscape::Server::Socket', $sn, $rq);

DESCRIPTION

Netscape::Server::Socket provides a perl implementation of the socket connection between the Netscape httpd and clients connecting to the server. It is intended to be used by nsapi_perl modules that wish to send or receive data to a client.

For the full details of nsapi_perl, 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.

The remainder of this document describes the usage and internals of Netscape::Server::Socket.

USAGE

Users of Netscape::Server::Socket will generally want to tie a filehandle to the class. Subsequent transactions on that filehandle will then read to or from the client. Indeed, at this time, all of Netscape::Server::Socket's class and instance methods are for use by tie().

Generally, it is therefore sufficient to call tie() as follows

tie(*FILEHANDLE, 'Netscape::Server::Socket', $sn, $rq);

*FILEHANDLE is the typeglob of the filehandle you wish to tie; $sn is an instance of Netscape::Server::Session; $rq is an instance of Netscape::Server::Request.

The above call will return an instance Netscape::Server::Socket if successful. Most likely you will not need to call instance methods on this object. Rather, you will let the magic of tie() call the appropriate instance methods whenever a read or write is attempted on the tied filehandle.

Currently the following actions on the tied filehandle are supported:

print FILEHANDLE LIST

printf FILEHANDLE FORMAT, LIST

read FILEHANDLE,SCALAR,LENGTH,OFFSET

sysread FILEHANDLE,SCALAR,LENGTH,OFFSET

At this time there is no support for reading from the filehandle using the diamond operator or using getc(). In other words, doing a

my $line = <FILEHANDLE>
my $char = getc(FILEHANDLE);

for a tied FILEHANDLE will not work.

Most of you can stop reading at this point; if you're interested in the internals of the module, read on.

METHODS

The user need not call these methods directly but can rely on the magic of tie() to do that for them. The methods are listed here for completeness.

Constructor

TIEHANDLE

my $socket = TIEHANDLE Netscape::Server::Socket, $sn, $rq;

The TIEHANDLE method returns an instance of Netscape::Server::Socket. $sn is an instance of Netscape::Server::Session. $rq is an instance of Netscape::Server::Request.

Instance Methods

PRINT

$socket->PRINT(@stuff);

Causes @stuff to be sent to the client. Until a completely empty line is received, the data is assumed to comprise the http header. Subsequent data is assumed to comprise the http message body. In other words, things like

$socket->PRINT("Content-type: text/plain\n",
               "\n",
               "This came from the server\n");

will work as expected.

PRINTF

$socket->PRINTF($format, @stuff);

Works like the perl built-in printf function, but sends the data to the client. This is just a wrapper around PRINT(), so it has the same behaviour regarding the http header/body.

READ

$socket->READ($scalar, $length, $offset);

Attempts to read $length bytes of data from the body of the client's request to the server starting at $offset. Stores the results in $scalar. Returns the actual number of bytes read.

Note that this method does not read data from the header of the client's request. To do this, look at the Netscape::Server::Request man page.

Note also that this method does not (yet) return undef in the case of an I/O error. This is an ugly bug that will be fixed in future release.

AUTHOR

Benjamin Sugars <bsugars@canoe.ca>

SEE ALSO

perl(1), perltie(3)

nsapi_perl, Netscape::Server::Session, Netscape::Server::Request

cpanm Netscape::Server

perl -MCPAN -e shell
install Netscape::Server