The TelnetClient class allows communication with a telnet server; it can be used directly or subclassed with overridden methods to customize its behavior. More...

Public Member Functions
	constructor (string host, softint port, code log, code dbgLog)
	constructor (string connect, code log, code dbglog)
	creates the TelnetClient object
	destructor ()
	disconnects from the server if connected and deletes the object
	connect (timeout timeout=DefaultConnTimeout)
	connects to the Telnet server
bool	isConnected ()
	returns True if the client is connected to the server
	setUser (*string user)
	sets or clears (in case passed with no value) the username parameter for logging in to the telnet server
*string	getUser ()
	returns the current value of the username parameter
	disconnect ()
	disconnects from the Telnet server
	sendData (softlist arr)
	sends data to the server
	sendTextData (string str)
	sends literal string data to the server; the text dat is converted to the socket's encoding if necessary
*string	getAvailableData (timeout t=DefaultTimeout)
	returns all data available as a string (which could be an empty string if no data is available in the timeout period) or NOTHING if the connection was closed by the remote end
bool	hasFeature (int fc)
	returns True if the server has confirmed with a DO command that it supports the given feature
	windowSizeUpdated ()
	this method should be called externally when the window size has changed
Private Member Functions
	log (string msg)
	logs the message to the log closure set with the constructor (if any)
	logDbg (string msg)
	logs the message to the debug log closure set with the constructor (if any)
*string	getDisplay ()
	this method provides the value that will be given as the DISPLAY value in protocol negotiation
*string	getTerminalType ()
	this method provides the value that will be given as the terminal type in protocol negotiation
hash	getEnvironment ()
	this method provides the value that will be given as the user's environment in protocol negotiation
int	getTerminalSpeed ()
	this method provides the value that will be given as the terminal speed in protocol negotiation
hash	getWindowSize ()
	this method provides the value that will be given as the terminal window size in protocol negotiation

Detailed Description

The TelnetClient class allows communication with a telnet server; it can be used directly or subclassed with overridden methods to customize its behavior.

This class uses a Mutex lock in each TelnetClient object to ensure thread serialization to the underlying socket and its internal configuration, so it is safe to access in a multithreaded context.

Member Function Documentation

TelnetClient::TelnetClient::connect ( timeout timeout = DefaultConnTimeout )

connects to the Telnet server

If the object is already connected, it is disconnected and a new connection attempt is made.

Note:: This method is subject to thread serialization.

TelnetClient::TelnetClient::constructor	(	string	host,
		softint	port,
		*code	log,
		*code	dbgLog
	)

creates the TelnetClient object

Parameters:

host	the hostname of the telnet server (use [hostname] to explicitly specify an ipv6 connection)
port	the port number of the telnet server
log	a closure for log messages
dbgLog	a closure for debugging/technical log messages

TelnetClient::TelnetClient::constructor	(	string	connect,
		*code	log,
		*code	dbglog
	)

creates the TelnetClient object

Parameters:

connect	the hostname of the Telnet server or a hostname:port specification (use [hostname] or [address] for ipv6 connections)
log	a closure for log messages
dbglog	a closure for debugging/technical log messages

TelnetClient::TelnetClient::disconnect ( )

disconnects from the Telnet server

Note:: This method is subject to thread serialization.

*string TelnetClient::TelnetClient::getAvailableData ( timeout t = DefaultTimeout )

returns all data available as a string (which could be an empty string if no data is available in the timeout period) or NOTHING if the connection was closed by the remote end

NOTHING is only returned if the remote end closed the connection

Note:

This method could throw any exception that Socket::recvu1() could throw except SOCKET-CLOSED (in which case the exception is caught and NOTHING is returned)
This method is subject to thread serialization

*string TelnetClient::TelnetClient::getDisplay ( ) [private]

this method provides the value that will be given as the DISPLAY value in protocol negotiation

override this method in a subclass to provide a different value

hash TelnetClient::TelnetClient::getEnvironment ( ) [private]

this method provides the value that will be given as the user's environment in protocol negotiation

override this method in a subclass to provide a different value

int TelnetClient::TelnetClient::getTerminalSpeed ( ) [private]

this method provides the value that will be given as the terminal speed in protocol negotiation

override this method in a subclass to provide a different value

*string TelnetClient::TelnetClient::getTerminalType ( ) [private]

this method provides the value that will be given as the terminal type in protocol negotiation

override this method in a subclass to provide a different value

hash TelnetClient::TelnetClient::getWindowSize ( ) [private]

this method provides the value that will be given as the terminal window size in protocol negotiation

The default implementation of this method is to return the actual terminal size by calling TermIOS::getWindowSize(). Override this method in a subclass to provide a different value.

Returns:

a hash with the following keys:

rows: the number of rows in the display
columns: the number of columns in the display

bool TelnetClient::TelnetClient::hasFeature ( int fc )

returns True if the server has confirmed with a DO command that it supports the given feature

Parameters:

fc	The feature code to check; see Telnet Command Option Codes for possible values; supported features are: TOPT_TS: TerminalSpeed TOPT_XDL: XDisplayLocation TOPT_TERM: TerminalType TOPT_ENVIR_NEW: TelnetNewEnvironmentOption TOPT_SUPP: SuppressGoAhead TOPT_NAWS: NegotiateAboutWindowSize

TelnetClient::TelnetClient::sendData ( softlist arr )

sends data to the server

Parameters:

$arr

a single element or a list of elements to send to the server; elements can be as follows:

string: currently sent verbatim to the server, in particular no encoding conversions are performed on this string (possibly these should be scanned for IAC characters which should be duplicated)
integer: treated as a single-byte value; if the value is IAC (ie 255 or 0xff) then it is sent twice
binary: sent verbatim to the server

Exceptions:

SEND-ERROR	this exception is thrown if an invalid data type is passed to this method
NOT-CONNECTED-EXCEPTION	if the socket is not already connected then this exception is thrown

Note:

This method could also throw any exception that Socket::sendBinary2() or Socket::sendi1() could throw
This method is subject to thread serialization

TelnetClient::TelnetClient::sendTextData ( string str )

sends literal string data to the server; the text dat is converted to the socket's encoding if necessary

Parameters:

$str	currently sent verbatim to the server; no encoding conversions are performed on this string (possibly these should be scanned for IAC characters which should be duplicated)

Exceptions:

NOT-CONNECTED-EXCEPTION if the socket is not already connected then this exception is thrown

Note:

This method could also throw any exception that Socket::sendBinary2() could throw
This method is subject to thread serialization

TelnetClient::TelnetClient::setUser ( *string user )

sets or clears (in case passed with no value) the username parameter for logging in to the telnet server

Note:: This method is subject to thread serialization.

TelnetClient::TelnetClient::windowSizeUpdated ( )

this method should be called externally when the window size has changed

See also:: getWindowSize()

Public Member Functions

Private Member Functions

Detailed Description

Member Function Documentation