NAME
Net::Telnet::Options - Telnet options over any socketVERSION
This document describes Net::Telnet::Options version 0.0.1
SYNOPSIS
use Net::Telnet::Options;
my %options = (BINARY => { 'DO' => sub {} },
MSP => { 'DO' => sub {} } );
my $nto = Net::Telnet::Options->new(%options);
OR
my $nto = Net::Telnet::Options->new();
# Accept and deal with incoming TERM TYPE option requests
$nto->acceptDoOption('TTYPE', {'SB' => \&ttype_sb_callback } );
sub ttype_sb_callback
{
my ($cmd, $subcmd, $data, $pos) = @_;
$nto->sendOpt($socket, 'SB', 24, 'IS', 'VT100');
return ;
}
# Actively ask the connected party to do the NAWS option
$nto->activeDoOption('NAWS', {'SB' => \&naws_sb_callback } );
# Parse and use the NAWS information
sub naws_sb_callback
{
my ($cmd, $subcmd, $data, $pos) = @_;
print ("NAWS SB: $cmd\n");
return unless($cmd eq 'IS');
my ($width, $height) = unpack('nn', $subcmd);
print ("NAWS width, height: $width, $height\n");
return ;
}
# Add a callback to deal with incoming ECHO requests
$nto->addOption(0, 'ECHO', {'WILL' => \&willecho_callback,
'WONT' => \&wontecho_callback });
# Agree to to let them do MXP
$nto->acceptWillOption('MXP');
# Send the active options to the connected party
$nto->doActiveOptions($socket);
# Assuming $socket is an IO::Handle/Socket
# Let NTO parse telnet options from incoming data:
my $data;
recv($socket, $data, 1024, 0);
$data = $nto->answerTelnetOpts($socket, $data);DESCRIPTION
This module is intended to handle Telnet Option requests on any given socket. Per default it refuses to do any option asked of it by the connected party. Any known telnet option can be set to be explicitly accepted or actively asked of the other side. Callback subroutines allow the user to execute some action upon receiving a particular option.
An instance of Net::Telnet::Options must be created for each socket, to keep track of the current state of each client.
INTERFACE
new (%options)
The new method can be passed a hash of default option callbacks to set. The keys of the hash are either option names, as given in the %possoptions hash at the top of this module, or option numbers from the appropriate RFCs.
The values of each item are hash references, with the keys being the option types to be handled, one of either WILL, WONT, DO, DONT, SB or RAW. The values should contain sub references of the callbacks to be called.
addOption ($activeflag, %opts)
The addOption method can be used to add more options in the same format as the new command, after the instance has been created. The additional activeflag can be set to either 0 or 1 to activate an option. An active option is one that is actively requested of the connected party.
acceptDoOption (option name/number or hash reference)
Agree to do the specific option. If just an option name/number is given, just agrees to do this option whenever requested by the connected party. (Sets up an empty callback). Can also be passed a hashref as with the hash references passed to the new method, containing callbacks to be called.
acceptWillOption (option name/number or hash reference)
Agree that the connected party will do a specific option. If just an option name/number is given, just agrees that the other party will do this option wheneverrrequested. (Sets up an empty callback). Can also be passed a hash reference as above to run callbacks.
activeDoOption (option name/number or hash reference)
Actively ask the connected party to DO a specific option. If just passed an option name/number, will just ask and ignore the response. If passed a hash reference containing WILL/WONT callbacks, these will be run when the connected party answers the request.
activeWillOption (option name/number or hash reference)
Actively declare that we want to do a specific option. If just passes an option name/number, will just declare what we want to do, and ignore any response. If passed a hash reference containing DO/DONT callbacks, these will be run when the connected party answers the request.
removeOption (option name/number)
Remove the given option from the set of options we are answering.
doActiveOptions (socket)
Requests any options set as active, and not yet negotiated, of the connected party.
getTelnetOptState (option name/number)
Returns a hash reference containing any callbacks set for any particular command, plus 'STATUS_ME', 'STATUS_YOU' which can be any of NONE, ASKING, or WILL. STATUS_ME is the status of the local socket with regard to the option, and STATUS_ME is the status of the connected party.
answerTelnetOpts (socket, data)
This method must be called whenever data has been received from the connected party, before any other operations are done. It parses any telnet option information out of the given data, answering options as appropriate. The cleaned data is passed back. The socket is needed in order to send answers to any option requests.
If a incomplete telnet option is found in the data, eg an IAC WILL and no option number, the data will be retained, and prepended to the data given in the next call, to be checked again. Thus you can also pass in data a byte at a time and still have the options parsed.
sendOpt (socket, command, option name/number, suboptioncmd, suboption)
Send a raw telnet option to the connected party. But only if it makes sense. Eg. if DOing NAWS has been negotiated, attempting a DO NAWS with sendOpt will refuse, on the grounds that we are already doing this. Useful for testing and turning off options by hand.
CALLBACKS
Methods are provided for adding callbacks to each part of the negotiation process. Callbacks for WILL, WONT, DO, DONT commands are passed out the passed in data string, with the option removed. This string may still have other following options in it, so should be treated with caution! The callback is also passed the position which the option was found in the string. It may return a new copy of the data string which will be used for further parsing. In most cases you will not need to look at or return the data string. Be sure to return undef as the last statement in your callback, if you are not changing the data, to not accidently return the value of your last statement.
Sub option callbacks are slightly more complex. Suboptions generally have one of 2 different subcommands, either a SEND which means please send me some information, or IS, which defines the wanted information. The callback is passed either 'SEND' or 'IS' or 'SB' as the first parameter, if IS is passed, the 2nd parameter contains the information being passed, for SEND it is empty and for SB it contains the subcommand and the any information together. The 3rd parameter contains the data string, minus the actual telnet option commands, and the 4th parameter is the position the suboption was in the string.
Currently it is assumed that the module user will remember which callback has been associated with which option. (Thus the callback does not get passed the option name/number for which it is fired)
Telnet Options Explained
Telnet options are simple but complex. The definition is simple, the implementation is complex as one has to avoid entering endless negotiation loops. The simple explanation should suffice here, as this module intends to hide the complex negotiating from you.
Each Telnet connection consists of two parties, one on either side of the connection. When dealing with telnet options it is unimportant which side is the server and which is the client, important is just 'us' and 'them'. 'us' here is the side using this module, and 'them' is the party we are connected to.
There are 4 basic telnet option commands, WILL, WONT, DO, DONT. If we receive a WILL command, it means the other side wishes to start using an option themselves. If we receive a DO command, the other side wants us to start using an option. These are two separate things. We can use an option that they are not using, and vice versa. WONT and DONT are used to refuse an option.
Example:
1a. We receive a DO TTYPE from them. 1b i. We wish to comply, so we send a WILL TTYPE. 1b ii. We do not wish to comply so we send a WONT TTYPE.
2a. We would like to echo, so we send a WILL ECHO. 2b i. Thats ok with them, so they send a DO ECHO. 2b ii. They dont want us to use echo, so they send us a DONT ECHO.
Once an option has been set in this manner, each side has to remember which options both ends are using. The default for all options is WONT/DONT.
Some options have additional suboptions to set internal parameters. These are sent enclosed in SB and SE commands. (suboption, suboptionend). For example, settting the TTYPE option just indicates we are willing to answer 'what is your terminal type' questions, these are posed and answered using SB commands.
DIAGNOSTICS
(TODO)
CONFIGURATION AND ENVIRONMENT
Net:Telnet::Options requires no configuration files or environment variables.
DEPENDENCIES
None.
INCOMPATIBILITIES
None.
BUGS AND LIMITATIONS
No bugs have been reported.
Please report any bugs or feature requests to bug-<RT NAME@rt.cpan.org>, or through the web interface at http://rt.cpan.org.
FURTHER INFORMATION
A list of available options: http://www.networksorcery.com/enp/protocol/telnet.htm
TODO
Support multiple sockets per instance. Output list of options/names.
AUTHOR
Jess Robinson castaway@desert-island.m.isar.de
LICENCE AND COPYRIGHT
Copyright (c) 2004,2005, Jess Robinson castaway@desert-island.m.isar.de. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
DISCLAIMER OF WARRANTY
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.