## Net::FileShare ver 1.04		02/03/03
## Gene Gallistel			<gravalo@uwm.edu>
#
# Copyright (C) 2003, Gene Gallistel, All Rights Reserved.
# Permission is granted to copy and modify this program for
# non-commercial purposes, so long as this copyright notice is
# preserved.  This software is distributed without warranty.
#


DESCRIPTION
-----------

Net::FileShare provides an object interface for creating file sharing clients and servers. This project started while I was developing an ICB bot. I wanted a simple interface to allow people to share files. My original thought was that this should be developed into a module to allow individuals to easily integrate file sharing functionality into chatter bots or chat clients. Thus began the development of Net::FileShare. 

Net::FileShare uses a very basic ascii based protocol for communication between servers and clients. Clients and servers developed with Net::FileShare will only function with other clients/servers developed with this module. 

Only four options can be passed to the object you're creating. They are: _send_only, _socket, _directory, and _debug._send_only and _debug function similiar to bool variables. They use a 1/0 (on/off) mechanism. _send_only must be set for both clients and servers. This may seem very redundant, but I perfer to err on the side of security. _socket needs to be set to a scalar as it will become a ref to a socket object created with IO::Socket::INET. _directory holds the dir path of where to look for files to serve, for the server, and where to files for the client. 

After setting the previously mentioned four options, then execute the server_connection() sub or the client_connection() sub. The server_connection sub will take only one optional argument, which is the port to bind to, if other than 3000. The client_connection() sub takes three options. These are the host(ie. IP x.x.x.x), port (3000 - by default) and file to request. 

The communication between client and server is rather simple. A client connects to server, and begins by sending a query packet, containing the name of the file. The server will determine if the file exists, and if so, will return an acknowledgement packet along with the file size. The server and client will both open a file, the server opening the requested file and the client creating a new file with ".copy" appended to the name. The server will read the contents of the file and print them over the connection, while the client reads from the socket and prints to the file. The client will read from the socket until size specified by the server has been reached. 

Currently servers created using Net::FileShare can only handle one connection at a time, and transfer one file at a time. As of today, 01-24-03, work is being done to allow servers to handle multiple files/clients at a time. 


USAGE
-----

	## the following is the source for constructing a file sharing server
	#!/usr/bin/perl -w
	use strict;
	use Net::FileShare;
	my ($fh) = Net::FileShare->new(
			_send_only => 1,
			_socket    => 1,
		 	_directory => '/path/to/files/to/serve',
		 	_debug     => 1);
  	$fh->server_connection;

	## the following is the complimentary client constructed with the module
	#!/usr/bin/perl -w
	use strict;
	use Net::FileShare;

	my ($fh) = Net::FileShare->new(
			_send_only => 0,
			_socket    => 1,
			_directory => '/home/usr_id',
			_debug     => 1);
  	$fh->client_connection("x.x.x.x", "port", "some_file");


BUILDING THE MODULE
-------------------

Net::FileShare is all perl, no compilation. To build and test the module:

    perl Makefile.PL
    make
    make test

INSTALLATION
------------

    make install

FEEDBACK
--------

How to report a problem with Net::FileShare.

To help me help you, I need of the following information:

1. The version of Perl and the operating system name and version you
    are running.  The command 'perl -V' should provide everything.

2. The version of Net::FileShare you currently have installed. Look for the line:
	$VERSION = 'X.XX';

3. Also send the sorce for the client or server you're attempting to build. 

4. Finally if this is a bug, a fix or a small example of the bug.

5. Email to gravalo@uwm.edu or use the contact form on my website:
	http://www.uwm.edu/cgi-bin/gravalo/mailme.pl

CHANGES
-------

See the Changes file.

Gene Gallistel <gravalo@uwm.edu>