1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
|
use strict;
use warnings;
package IO::Socket::Telnet::HalfDuplex;
use base 'IO::Socket::Telnet';
=head1 NAME
IO::Socket::Telnet::HalfDuplex - more reliable telnet communication
=head1 SYNOPSIS
use IO::Socket::Telnet::HalfDuplex;
my $socket = IO::Socket::Telnet::HalfDuplex->new(PeerAddr => 'localhost');
while (1) {
$socket->send(scalar <>);
print $socket->read;
}
=head1 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, L<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 C<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 L</read> method provided by
this module; the rest of the interface is just inherited from
L<IO::Socket::Telnet>.
=cut
=head1 CONSTRUCTOR
=head2 new(PARAMHASH)
The constructor takes mostly the same arguments as L<IO::Socket::INET>, but
also accepts the key C<PingOption>, which takes an integer between 40 and 239
to use for the ping/pong mechanism. This defaults to 99 if not specified.
=cut
sub new {
my $class = shift;
my %args = @_;
my $ping = delete $args{PingOption} || 99;
die "Invalid option: $ping (must be 40-239)" if $ping < 40 || $ping >= 240;
my $self = $class->SUPER::new(@_);
${*{$self}}{ping_option} = $ping;
$self->IO::Socket::Telnet::telnet_simple_callback(\&_telnet_negotiation);
return $self;
}
sub telnet_simple_callback {
my $self = shift;
${*$self}{halfduplex_simple_cb} = $_[0] if @_;
${*$self}{halfduplex_simple_cb};
}
=head1 METHODS
=cut
=head2 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.
=cut
sub read {
my $self = shift;
my $buffer;
$self->do(chr(${*{$self}}{ping_option}));
${*{$self}}{got_pong} = 0;
eval {
local $SIG{__DIE__};
while (1) {
my $b;
defined $self->recv($b, 4096, 0) and do {
$buffer .= $b;
die "got pong\n" if ${*{$self}}{got_pong};
next;
};
die "Disconnected from server: $!" unless $!{EINTR};
}
};
die $@ if $@ !~ /^got pong\n/;
return $buffer;
}
sub _telnet_negotiation {
my $self = shift;
my $option = shift;
my $external_callback = ${*{$self}}{halfduplex_simple_cb};
my $ping = ${*{$self}}{ping_option};
if ($option =~ / $ping$/) {
${*{$self}}{got_pong} = 1;
return '' unless $external_callback;
return $self->$external_callback($option);
}
return unless $external_callback;
return $self->$external_callback($option);
}
=head1 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.
=head1 BUGS
No known bugs.
Please report any bugs through RT: email
C<bug-io-socket-telnet-halfduplex at rt.cpan.org>, or browse to
L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=IO-Socket-Telnet-HalfDuplex>.
=head1 SEE ALSO
L<IO::Socket::Telnet>, L<IO::Socket::INET>, L<IO::Socket>, L<IO::Handle>
L<http://www.ietf.org/rfc/rfc854.txt>
=head1 CREDITS
This algorithm (and most of the implementation) is due to Shawn Moore (L<http://search.cpan.org/~sartak/>) for projects such as L<TAEB> and L<http://interhack.us>.
=head1 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:
=over 4
=item * AnnoCPAN: Annotated CPAN documentation
L<http://annocpan.org/dist/IO-Socket-Telnet-HalfDuplex>
=item * CPAN Ratings
L<http://cpanratings.perl.org/d/IO-Socket-Telnet-HalfDuplex>
=item * RT: CPAN's request tracker
L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=IO-Socket-Telnet-HalfDuplex>
=item * Search CPAN
L<http://search.cpan.org/dist/IO-Socket-Telnet-HalfDuplex>
=back
=head1 AUTHOR
Jesse Luehrs <doy at tozt dot net>
=head1 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.
=cut
1;
|
