NAME

ZipTie::Telnet - Telnet implementation of the ZipTie::CLIProtocol interface/abstract class.

SYNOPSIS

        use ZipTie::CLIProtocol;
        use ZipTie::CLIProtocolFactory;

        my $telnet = ZipTie::CLIProtocolFactory->create("Telnet", "10.10.10.10", 22);
        $telnet->connect($telnet->get_ip_address(), $ssh->get_port());

DESCRIPTION

ZipTie::Telnet provides an Telnet implementation of the ZipTie::CLIProtocol interface/abstract class. It leverages the implemented methods from ZipTie::CLIProtocol and utilizes the Net::Telnet module to provide Telnet-specifc support to the interface methods.

METHODS

Please refer to the ``METHOD'' section of the ZipTie::CLIProtocol documentation to know what methods there are and how they are used. Any additional documentation to methods that have their own unique implementation for Telnet purposes will be documented below.

new($ioHandle)

Creates a new instance of the ZipTie::Telnet class with a default timeout value of 30 seconds. While this constructor method can be called on its own, it is recommend that the ZipTie::CLIProtocolFactory and its create method be used for creating objects based off of the ZipTie::CLIProtocol class.

$ioHandle - an optional argument. If an already open IO handle is provided, then the connect method will
	do nothing and all send and receive methods will read and write from the provided filehandle.

connect($ip_address, $port)

Connects to a device at a specified IP address and port. Although the interface specified by the ZipTie::CLIProtocol class specifies that connect() also takes in a a username and password, these are not need and not used by the ZipTie::Telnet implementation.

$ip_address - The administrative IP address of the device.

$port - The port to connect to on the device.

disconnect()

Disconnects from the device this ZipTie::Telnet object is already connected to.

send($input)

Sends an input string to the device. In order to retrieve the output, it is expected that the user will call wait_for() method with a valid regular expression after the call to send().

put($input)

Same as send except that no line separator, e.g. a CRLF, is appended to the $input.

send_as_bytes($input)

Converts an input string into a hexadecimal byte representation and sends it to the device. Unlike send(), send_as_bytes() will not append any special CRLF character/bytes to the end of the input. The input will simply be converted into hexadecimal and will be sent as is. It is expected that the command interpreter on the device should know how to handle the byte information coming in.

In order to retrieve the output, it is expected that the user will call wait_for() with a valid regular expression after the call to send_as_bytes().

set_timeout($timeout)

Set the length (in seconds) for how long the wait_for() method should wait on a response from a device before timing out. This time out value will only be used if the the wait_for() method is used with the matching regular expression as its only parameter.

wait_for($regex, $timeout)

Waits for the response from a device and checks to see if the response matches a specified regular expression. If a match is found, all of the response preceeding AND including the match will be returned. It is assumed that this function will be called directly after a call to send().

$regex - A valid regular expression to match the response from the device.

$timeout -	Optional. Specifies the amount of time (in seconds) to wait for a response from the device.
	If this parameter is specified, the timeout specified by a call to `set_timeout()` will be ignored
	for this function call only.

get_response($timeout)

Waits a specified window of time for a response to come back from the device. Given a window of time, if any data is sent from the device, it will be collected and stored as part of the overall response from the device. If the window of time goes by without any response from the device, it is then assumed that the device is done responding and the overall response will be returned.

The use of get_response($timeout) might be desireable over wait_for($regex, $timeout) if there is not a particular part of the response from a device you are waiting for, or if the response from a device comes back in an unexpected format/flow.

$timeout -	Optional; 5 seconds by default. Specifies the a window of time (in seconds) to wait for a response
	from the device.


=item C<output_record_separator($charSequence)>

Set or get the output record separator. The $charSequence argument is optional. If no argument is given, this method simply returns the current value of the output record separator, such as a CR or CRLF.

_log_and_die($error_message)

NOTE: This method is only used as a callback when Net::Telnet encounters a fatal situation, instead of die-ing.

Invokes the the ZipTie::Logger singleton's fatal($message) method with a specified error message. This method is used as a callback whenever Net::Telnet encounters a fatal situation. This is done by calling the errmode($code_reference) method on the Net::Telnet instance; once registered, Net::Telnet will call this method with the error message it generated.

LICENSE

The contents of this file are subject to the AlterPoint Open Technology License (the ``License''); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://inventory.alterpoint.com/license

Software distributed under the License is distributed on an ``AS IS'' basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License.

The Original Code is Ziptie Client Framework.

AUTHOR

Contributor(s): dwhite Date: May 8, 2007