NAME

HTTP::Server::Connection - represents a client connection

INHERITANCE

SYNOPSIS

DESCRIPTION

The connection relates to one client. Each time, a browser connects to the socket, a new ::Connection object will be created. Internally, this object maintains a list of received requests, which will be handled in the order they arrived.

METHODS

Constructors

$obj->async(REQUEST, RUN, CALLBACK)

The RUN code reference is called in a forked-off process. The returned value (LIST context) is passed to CALLBACK which runs in the daemon process. The CALLBACK must deliver a response.

example:

 sub handler($$$)
 {   my ($conn, $request, $uri) = @_;
     my $fn    = '$rootdir/'.$uri->path;
     my $fread = sub      # (closure) in other process
       { my @lines = File::Slurp::read_file($fn);
         scalar @lines;
       };
     my $cb    = sub
       { my $text = join '#', @_;
         $conn->sendResponse($request, RC_OK, [], $text);
       };
     $conn->async($request, $fread, \&cb);
     undef;
  }

$obj->cancelConnection

Kill connection.

$obj->closeConnection

No not accept any more requests, but handle which were already received.

$obj->directoryList(DIRECTORY, REQUEST, CALLBACK, OPTIONS)

Returns file information from a directory. This is executed in a seperate process. Your CALLBACK should return the response object which has already been sent. Your CALLBACK will not be called, when the directory cannot be read.

See "Return of directoryList" about the returned output.

 Option       --Default
 filter         <undef>
 hide_symlinks  <false>
 names          <skip hidden files>

. filter => CODE

For each of the selected names (see names option) the lstat() is called. That data is expanded into a HASH, but not all additional fields are yet filled-in (only the ones which come for free).

. hide_symlinks => BOOLEAN

. names => CODE|Regexp

Reduce the returned list. The CODE reference is called with the found filename, and should return true when the name is acceptable. The default regexp (on UNIX) is qr/^[^.]/

$obj->load(FILENAME|FILEHANDLE, CALLBACK)

Asynchronously read the FILE via the multiplexer, not blocking the activities for the other clients. After everything has been read, the CALLBACK will be called with a reference to the data read, or undef on failure. The CALLBACK must continue the work to end in a response.

$obj->save(FILE, DATA, CALLBACK)

Asynchronously write the FILE via the multiplexer, not blocking the activities for the other clients. The FILE is specified either as file name or file handle. The DATA is a string or SCALAR-ref (the latter usually providing a better performance).

After everything has been written, the user CALLBACK will be called. The CALLBACK must continue the work to end in a response, because writing is just an intermediate activity.

$obj->sendFile(REQUEST, FILE, [HEADER-ARRAY, [CALLBACK]])

The FILE is either a filename or file handle. In the latter case, you have to specify the content type in the HEADER ARRAY (list of key value pairs)

$obj->sendRedirect(REQUEST, STATUS, LOCATION, [CONTENT])

$obj->sendResponse(REQUEST, STATUS, HEADER, [CONTENT])

The CONNECTION information is used to figure-out where the REQUEST (a HTTP::Request object) came from. The STATUS code is used in the response, preferrable use the constants from HTTP::Status. The HEADER is an ARRAY of header line pairs to be used in the answer.

You can use a scalar CONTENT, which will be used as response body. In case the CONTENT parameter is a CODE reference, that CODE will be called until undef is returned. The result of every call will become a chunk in a chunked transfer encoded response.

$obj->sendStatus(REQUEST, STATUS, [TEXT])

DETAILS

Return of directoryList

The directoryList() method returns a HASH of HASHes, where the primary keys are the directory entries, each refering to a HASH with details. It is designed to ease the connection to template systems.

The details contain the lstat information plus some additional helpers. The lstat call provides the fields dev, ino, mode, nlink, uid, gid, rdev, size, atime, mtime, ctime, blksize, blocks -as far as supported by your OS. The entry's name and path are added.

The kind field contains the string DIRECTORY, FILE, SYMLINK, or OTHER. Besides, you get either an is_directory, is_file, is_symlink, or is_other field set to true. Equivalent are:

   if($entry->{kind} eq 'DIRECTORY')
   if($entry->{is_directory})

It depends on the kind of entry which of the following fields are added additionally. Symlinks will get symlink_dest, symlink_dest_exists. Files hace the size_nice, which is the size in pleasant humanly readable format.

Files and directories have the mtime_nice (in localtime). The user and group which are textual representations of the numeric uid and gid are added. The flags represents the UNIX standard permission-bit display, as produced by the "ls -l" command.

SEE ALSO

This module is part of HTTP-Server-Multiplex distribution version 0.11, built on October 01, 2008. Website: http://perl.overmeer.net/httpd-multiplex/

LICENSE

Copyrights 2008 by Mark Overmeer. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html

cpanm HTTP::Server::Multiplex

perl -MCPAN -e shell
install HTTP::Server::Multiplex