/ 
EasyTCP-0.07
River stage zero No dependents
/ Net::EasyTCP

NAME

Net::EasyTCP - Easily create TCP/IP clients and servers

FEATURES

  • One easy module to create both clients and servers

  • Object Oriented interface

  • Event-based callbacks in server mode

  • Internal protocol to take care of all the common transport problems

  • Transparent encryption

  • Transparent compression

SYNOPSIS

SERVER EXAMPLE:
use Net::EasyTCP;

$server = new Net::EasyTCP(
	mode            =>      "server",
	port            =>      2345,
	)
	|| die "ERROR CREATING SERVER: $@\n";

$server->setcallback(
	data            =>      \&gotdata,
	connect         =>      \&connected,
	disconnect	=>	\&disconnected,
	)
	|| die "ERROR SETTING CALLBACKS: $@\n";

$server->start() || die "ERROR STARTING SERVER: $@\n";

sub gotdata() {
	my $client = shift;
	my $serial = $client->serial();
	my $data = $client->data();
	print "Client $serial sent me some data, sending it right back to them again\n";
	$client->send($data) || die "ERROR SENDING TO CLIENT: $@\n";
	if ($data eq "QUIT") {
		$client->close() || die "ERROR CLOSING CLIENT: $@\n";
		}
	elsif ($data eq "DIE") {
		$server->stop() || die "ERROR STOPPING SERVER: $@\n";
		}
	}

sub connected() {
	my $client = shift;
	my $serial = $client->serial();
	print "Client $serial just connected\n";
	}

sub disconnected() {
	my $client = shift;
	my $serial = $client->serial();
	print "Client $serial just disconnected\n";
	}
CLIENT EXAMPLE:
use Net::EasyTCP;

$client = new Net::EasyTCP(
	mode            =>      "client",
	host            =>      'localhost',
	port            =>      2345,
	)
	|| die "ERROR CREATING CLIENT: $@\n";

#Send and receive a simple string
$client->send("HELLO THERE") || die "ERROR SENDING: $@\n";
$reply = $client->receive() || die "ERROR RECEIVING: $@\n";

#Send and receive complex objects/strings/arrays/hashes by reference
%hash = ("to be or" => "not to be" , "just another" => "perl hacker");
$client->send(\%hash) || die "ERROR SENDING: $@\n";
$reply = $client->receive() || die "ERROR RECEIVING: $@\n";
foreach (keys %{$reply}) {
	print "Received key: $_ = $reply->{$_}\n";
	}

#Send and receive large binary data
for (1..4096) {
	for (0..255) {
		$largedata .= chr($_);
		}
	}
$client->send($largedata) || die "ERROR SENDING: $@\n";
$reply = $client->receive() || die "ERROR RECEIVING: $@\n";

$client->close();

DESCRIPTION

This class allows you to easily create TCP/IP clients and servers and provides an OO interface to manage the connection(s). This allows you to concentrate on the application rather than on the transport.

You still have to engineer your high-level protocol. For example, if you're writing an SMTP client-server pair, you will have to teach your client to send "HELO" when it connects, and you will have to teach your server what to do once it receives the "HELO" command, and so forth.

What you won't have to do is worry about how the command will get there, about line termination, about binary data, complex-structure serialization, encryption, compression, or about fragmented packets on the received end. All of these will be taken care of by this class.

CONSTRUCTOR

new(%hash)

Constructs and returns a new Net::EasyTCP object. Such an object behaves in one of two modes (that needs to be supplied to new() on creation time). You can create either a server object (which accepts connections from several clients) or a client object (which initiates a connection to a server).

new() expects to be passed a hash. The following keys are accepted:

donotcompress

Set to 1 to forcefully disable compression even if the appropriate module(s) are found. (Optional)

donotencrypt

Set to 1 to forcefully disable encryption even if the appropriate module(s) are found. (Optional)

host

Must be set to the hostname/IP address to connect to. (Mandatory when mode is "client")

mode

Must be set to either "client" or "server" according to the type of object you want returned. (Mandatory)

password

Defines a password to use for the connection. When mode is "server" this password will be required from clients before the full connection is accepted . When mode is "client" this is the password that the server connecting to requires. (Optional)

port

Must be set to the port the client connects to (if mode is "client") or to the port to listen to (if mode is "server"). If you're writing a client+server pair, they must both use the same port number. (Mandatory)

welcome

If someone uses an interactive telnet program to telnet to the server, they will see this welcome message. (Optional and acceptable only when mode is "server")

METHODS

[C] = Available to objects created as mode "client"

[S] = Available to objects created as mode "server"

callback(%hash)

See setcallback()

clients()

[S] Returns all the clients currently connected to the server. If called in array context will return an array of client objects. If called in scalar context will return the number of clients connected.

close()

[C] Instructs a client object to close it's connection with a server.

compression()

[C] Returns the name of the module used as the compression module for this connection, undef if no compression occurs.

data()

[C] Retrieves the previously-retrieved data associated with a client object. This method is typically used from inside the callback sub associated with the "data" event, since the callback sub is passed nothing more than a client object.

disconnect()

See close()

encryption()

[C] Returns the name of the module used as the encryption module for this connection, undef if no encryption occurs.

mode()

[C][S] Identifies the mode of the object. Returns either "client" or "server"

receive($timeout)

[C] Receives data sent to the client by a server and returns it. It will block until data is received or until a certain timeout of inactivity (no data transferring) has occurred.

It accepts an optional parameter, a timeout value in seconds. If none is supplied it will default to 300.

remoteip()

[C] Returns the IP address of the host on the other end of the connection.

remoteport()

[C] Returns the port of the host on the other end of the connection.

running()

[S] Returns true if the server is running (started), false if it is not.

send($data)

[C] Sends data to a server. It can be used on client objects you create with the new() constructor, clients objects returned by the clients() method, or with client objects passed to your callback subs by a running server.

It accepts one parameter, and that is the data to send. The data can be a simple scalar or a reference to something more complex.

serial()

[C] Retrieves the serial number of a client object, This is a simple integer that allows your callback subs to easily differentiate between different clients.

setcallback(%hash)

[S] Tells the server which subroutines to call when specific events happen. For example when a client sends the server data, the server calls the "data" callback sub.

setcallback() expects to be passed a hash. Each key in the hash is the callback type identifier, and the value is a reference to a sub to call once that callback type event occurs.

Valid keys in that hash are:

connect

Called when a new client connects to the server

data

Called when an existing client sends data to the server

disconnect

Called when an existing client disconnects

Whenever a callback sub is called, it is passed a single parameter, a CLIENT OBJECT. The callback code may then use any of the methods available to client objects to do whatever it wants to do (Read data sent from the client, reply to the client, close the client connection etc...)

socket()

[C] Returns the handle of the socket (actually an IO::Socket object) associated with the supplied object. This is useful if you're interested in using IO::Select or select() and want to add a client object's socket handle to the select list.

Note that eventhough there's nothing stopping you from reading and writing directly to the socket handle you retrieve via this method, you should never do this since doing so would definately corrupt the internal protocol and may render your connection useless. Instead you should use the send() and receive() methods.

start()

[S] Starts a server and does NOT return until the server is stopped via the stop() method. Once a server is started it will accept new client connections as well as parse incoming data from clients and fire off the appropriate callbacks' subs.

stop()

[S] Instructs a running server to stop and returns immediately (does not wait for the server to actually stop, which may be a few seconds later). To check if the server is still running or not use the running() method.

COMPRESSION AND ENCRYPTION

Clients and servers written using this class will automatically compress and/or encrypt the transferred data if the appropriate modules are found.

Compression will be automatically enabled if one (or more) of: Compress::Zlib or Compress::LZF are installed on both the client and the server.

Encryption will be automatically enabled if one (or more) of: Crypt::Rijndael* Crypt::RC6* or Crypt::Blowfish* or Crypt::DES_EDE3* or Crypt::DES* or Crypt::CipherSaber are installed on both the client and the server.

Preference to the compression/encryption method used is determind by availablity checking following the order in which they are presented in the above lists.

To find out which module(s) have been negotiated for use you can use the compression() and encryption() methods.

* Note that for this class's purposes, Crypt::CBC is a requirement to use any of the encryption modules with a * next to it's name in the above list. So eventhough you may have these modules installed on both the client and the server, they will not be used unless Crypt::CBC is also installed on both ends.

If the above modules are installed but you want to forcefully disable compression or encryption, supply the "donotcompress" and/or "donotencrypt" keys to the new() constructor.

RETURN VALUES AND ERRORS

The constructor and all methods return something that evaluates to true when successful, and to false when not successful.

There are a couple of exceptions to the above rule and they are the following methods:

  • clients()

  • data()

The above methods may return something that evaluates to false (such as an empty string, an empty array, or the string "0") eventhough there was no error. In that case check if the returned value is defined or not, using the defined() Perl function.

If not successful, the variable $@ will contain a description of the error that occurred.

NOTES

Incompatability with Net::EasyTCP version 0.01

Version 0.02 and later have had their internal protocol modified to a fairly large degree. This has made compatability with version 0.01 impossible. If you're going to use version 0.02 or later (highly recommended), then you will need to make sure that none of the clients/servers are still using version 0.01.

Internal Protocol

This class implements a miniature protocol when it sends and receives data between it's clients and servers. This means that a server created using this class cannot properly communicate with a normal client of any protocol (pop3/smtp/etc..) unless that client was also written using this class. It also means that a client written with this class will not properly communicate with a different server (telnet/smtp/pop3 server for example, unless that server is implemented using this class also). This limitation will not change in future releases due to the plethora of advantages the internal protocol gives us.

In other words, if you write a server using this class, write the client using this class also, and vice versa.

Delays

This class does not use the fork() method whatsoever. This means that all it's input/output and multi-socket handling is done via select().

This leads to the following limitation: When a server calls one of your callback subs, it waits for it to return and therefore cannot do anything else. If your callback sub takes 5 minutes to return, then the server will not be able to do anything for 5 minutes, such as acknowledge new clients, or process input from other clients.

In other words, make the code in your callbacks' subs' minimal and strive to make it return as fast as possible.

Deadlocks

As with any client-server scenario, make sure you engineer how they're going to talk to each other, and the order they're going to talk to each other in, quite carefully. If both ends of the connection are waiting for the other end to say something, you've got a deadlock.

AUTHOR

Mina Naguib, <mnaguib@cpan.org>

SEE ALSO

Perl(1), IO::Socket, IO::Select, Compress::Zlib, Compress::LZF, Crypt::CBC, Crypt::DES_EDE3, Crypt::Blowfish, Crypt::DES, Crypt::CipherSaber, defined()

COPYRIGHT

Copyright (C) 2001 Mina Naguib. All rights reserved. Use is subject to the Perl license.