/ 
IO-Socket-Telnet-HalfDuplex-0.02
River stage zero No dependents
/ IO::Socket::Telnet::HalfDuplex

NAME

IO::Socket::Telnet::HalfDuplex - more reliable telnet communication

VERSION

version 0.02

SYNOPSIS

use IO::Socket::Telnet::HalfDuplex;
my $socket = IO::Socket::Telnet::HalfDuplex->new(PeerAddr => 'localhost');
while (1) {
    $socket->send(scalar <>);
    print $socket->read;
}

DESCRIPTION

A common issue when communicating over a network is deciding when input is done being received. If the communication is a fixed protocol, the protocol should define this clearly, but this isn't always the case; in particular, interactive telnet sessions provide no way to tell whether or not the data that has been sent is the full amount of data that the server wants to send, or whether that was just a single packet which should be combined with future packets to form the full message. This module attempts to alleviate this somewhat by providing a way to estimate how much time you should wait before assuming that all the data has arrived.

The method used is a slight abuse of the telnet out-of-band option negotiation - most telnet servers, when told to DO an option that they don't understand, will respond that they WONT do that option, and will continue to do so every time (this is not guaranteed by the telnet spec, however - if this isn't the case, IO::Socket::Telnet is the only option). We can use this method to get an estimate of how long we should wait for the data. This module sends a ping in the out-of-band data before reading, with the assumption that by the time it gets to the server, all the output that has been generated by your most recent send will already be queued up in the server's output buffer. This would be guaranteed if we were just communicating with the telnet server directly, but typically we are communicating with a subprocess spawned by the telnet server, which means that the telnet server can respond to the ping while the subprocess is continuing to send data, making this not failsafe. It's generally a safe assumption for interactive programs across a network, though, since interactive programs tend to respond quickly, relative to network latency. After sending the ping, we just read as much as we can until we get the pong. This process is all wrapped up in the "read" method provided by this module; the rest of the interface is just inherited from IO::Socket::Telnet.

CONSTRUCTOR

new(PARAMHASH)

The constructor takes mostly the same arguments as IO::Socket::INET, but also accepts the key PingOption, which takes an integer between 40 and 239 to use for the ping/pong mechanism. This defaults to 99 if not specified.

METHODS

read()

Performs a (hopefully) full read on the socket. Returns the data read. Throws an exception if the connection ends before all data is read.

CAVEATS

This is not actually guaranteed half-duplex communication - that's not possible in general over a telnet connection without specifying a protocol in advance. This module just does its best to get as close as possible, and tends to do reasonably well in practice.

BUGS

No known bugs.

Please report any bugs through RT: email bug-io-socket-telnet-halfduplex at rt.cpan.org, or browse to http://rt.cpan.org/NoAuth/ReportBug.html?Queue=IO-Socket-Telnet-HalfDuplex.

SEE ALSO

IO::Socket::Telnet, IO::Socket::INET, IO::Socket, IO::Handle

http://www.ietf.org/rfc/rfc854.txt

CREDITS

This algorithm (and most of the implementation) is due to Shawn Moore (http://search.cpan.org/~sartak/) for projects such as TAEB and http://interhack.us.

SUPPORT

You can find this documentation for this module with the perldoc command.

perldoc IO::Socket::Telnet::HalfDuplex

You can also look for information at:

AUTHOR

Jesse Luehrs <doy at tozt dot net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2009 by Jesse Luehrs.

This is free software; you can redistribute it and/or modify it under the same terms as perl itself.