NAME

Agent::TCPIP - A simplified interface to TCP/IP.

SYNOPSIS

use Agent::TCPIP;
$server = new Agent::TCPIP( Listen => 5 );
$client = new Agent::TCPIP( Address => 'w.x.y.z' );

DESCRIPTION

TCPIP breaks TCP/IP communications down into two kinds of connection: A Client connection, and a Server connection. This greatly simplifies the code needed to set up and use such a connection. This module was designed with Agent.pm in mind. This documentation is slightly out of date.

CONSTRUCTOR

New may be called in a number of ways, depending on the type of connection you'd like to establish. First you must choose between a server or a client: if a Listen argument exists, a server is created. If you are creating a client then you should decide on the Address and Port you want to connect to. Or, if you're creating a server, you might want to choose a Port to set it up on. In both cases you can specify the Timeout value (ie: time to wait before giving up on some socket ops). More explicitly:

A server:
    Listen => $number_of_remote_connections
    Port => $port_to_listen_on

A client:
    Address => 'remote.inet.address'
    Port => $remote_port

If no socket could be made, a client will try to connect to the same address a default of 5 times, whereas a server will try to secure one of 5 different ports before giving up. With that said, the arguments default to:

Listen  => [undefined]
Address => '127.0.0.1'
Port    => 24368
Timeout => 60
Try     => 5

Note: Any other arguments you pass will be tossed right to IO::Socket, so I suggest you read that before playing.

METHODS

Unless noted otherwise, all methods accept arguments in the form of a hash array, and they all [should] return () when something doesn't work right (ie: when trying to close a socket that is not open).

$obj->Open( %args )

Serer only. Waits for an incoming connection and opens it, unless Timeout is reached. Closes any previous connection.

$obj->Close( %args )

Disconnects from the remote host unless Server is defined, in which case it kills the server socket only (and not any remote connections the server might have open at the time). This might be usefull if a subprocess were to handle remote connections.

$obj->Send( @data )

Client only. Sends @data to the remote host.

$obj->Recv( %args )

Server only. Recieves a line of data from the remote host.

$obj->Timeout( %args )

Sets the timeout value if Time is defined, returns it otherwise. If you want to set the Server's timeout value, call this with 'Server => 1', otherwise it will default to the remote connection (ie: not the listening connection), be it client or server.

$obj->Status( %args )

Returns the connection status in a hash. Calling with 'Dump => 1' will dump the status to STDERR. The status keys speak for themselves.

NOTES

Servers commonly serve more than one connection at a time. For this reason, some sort of forking routine will be needed under win32. The caller can worry about this. (perhaps Process.pm?)

TODO

* Allow user to specify a 'remote' when Open is called - server will hangup on any incoming connections unless they originate from said host. * Support for 'port:address' in 'new'. Currently testing this. * Write a 'client' and 'server' for @EXPORT_OK for lazy people (like me). * Simulate two-way communications so the user doesn't have to [optional].

SEE ALSO

IO::Socket and the socket(1) man page for more technical information.

AUTHOR

Steve Purkis <spurkis@engsoc.carleton.ca>

THANKS

Kudos to Graham Barr for an excellent job on IO::Socket (amongst others), and James Duncan for Tom, and for getting me started on this binge ;-).