TelnetClient::TelnetClient Class Reference

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

| clearStats ()
| Clears performance statistics. More...
nothing | clearWarningQueue ()
| Removes any warning Queue object from the Socket. More...
| connect (timeout timeout=DefaultConnTimeout)
| connects to the Telnet server More...
| constructor (string connect, *code log, *code dbglog)
| creates the TelnetClient object from a target string and optional log closure(s) More...
| constructor (string host, softint port, *code log, *code dbglog)
| creates the TelnetClient object More...
| destructor ()
| disconnects from the server if connected and deletes the object
| disconnect ()
| disconnects from the Telnet server More...
*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 More...
string | getTarget ()
| Returns the connection target string. More...
hash< auto > | getUsageInfo ()
| Returns performance statistics for the socket. More...
*string | getUser ()
| returns the current value of the username parameter
bool | hasFeature (int fc)
| returns True if the server has confirmed with a DO command that it supports the given feature More...
bool | isConnected ()
| returns True if the client is connected to the server
| sendData (softlist arr)
| sends data to the server More...
| sendTextData (string str)
| sends literal string data to the server; the text dat is converted to the socket's encoding if necessary More...
| setEventQueue ()
| Removes any Queue object so that socket events are no longer added to the Queue. More...
| setEventQueue (Qore::Thread::Queue queue, auto arg, *bool with_data)
| Sets a Queue object to receive socket events. More...
| setUser (*string n_user)
| sets or clears (in case passed with no value) the username parameter for logging in to the telnet server More...
nothing | setWarningQueue (int warning_ms, int warning_bs, Queue queue, any arg, timeout min_ms=1s)
| Sets a Queue object to receive socket warnings. More...
| windowSizeUpdated ()
| this method should be called externally when the window size has changed More...

## Protected Member Functions

*string | getDisplay ()
| this method provides the value that will be given as the DISPLAY value in protocol negotiation More...
hash | getEnvironment ()
| this method provides the value that will be given as the user's environment in protocol negotiation More...
int | getTerminalSpeed ()
| this method provides the value that will be given as the terminal speed in protocol negotiation More...
*string | getTerminalType ()
| this method provides the value that will be given as the terminal type in protocol negotiation More...
hash | getWindowSize ()
| this method provides the value that will be given as the terminal window size in protocol negotiation More...
| 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)

## 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

## clearStats()

TelnetClient::TelnetClient::clearStats | ( |  | ) |

Clears performance statistics.

Example:
  telnet.clearStats();

Since
  TelnetClient 1.1

See also
  TelnetClient::getUsageInfo()

## clearWarningQueue()

nothing TelnetClient::TelnetClient::clearWarningQueue | ( |  | ) |

Removes any warning Queue object from the Socket.

Example:
  telnet.clearWarningQueue();

See also
  setWarningQueue()

Since
  TelnetClient 1.1

## connect()

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.

## constructor() [1/2]

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

creates the TelnetClient object from a target string and optional log closure(s)

Parameters

  connect | the hostname of the Telnet server or a hostname:port specification (use [hostname] or [address] for ipv6 connections); also accepts URLs with a scheme `"telnet://"`, any other scheme, or of the URL contains a username, password, or path, an `INVALID-TARGET` exception will be thrown
  log | a closure or call reference for log messages; a single string argument will be passed to this code for logging
  dbglog | a closure or call reference for debugging/technical log messages; a single string argument will be passed to this code for logging

Note
  a UNIX domain socket target can be given with a URL in the following format: `scheme://socket=`url_encoded_path`/path`, where url_encoded_path is a path with URL-encoding as performed by encode_url(string, True); for example: `"telnet://socket=%2ftmp%socket-dir%2fsocket-file-1"`; this allows a filesystem path to be used in the host portion of the URL providing the path to the UNIX domain socket.

Exceptions

  INVALID-TARGET | the connection argument contains a URL with an invalid target scheme or unsupported components (username, password, or path)

## constructor() [2/2]

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 or call reference for log messages; a single string argument will be passed to this code for logging
  dbglog | a closure for debugging/technical log messages; a single string argument will be passed to this code for logging

## disconnect()

TelnetClient::TelnetClient::disconnect | ( |  | ) |

disconnects from the Telnet server

Note
  This method is subject to thread serialization.

## getAvailableData()

*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

## getDisplay()

*string TelnetClient::TelnetClient::getDisplay | ( |  | ) |

protected

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

## getEnvironment()

hash TelnetClient::TelnetClient::getEnvironment | ( |  | ) |

protected

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

## getTarget()

string TelnetClient::TelnetClient::getTarget | ( |  | ) |

Returns the connection target string.

Since
  TelnetClient 1.3

## getTerminalSpeed()

int TelnetClient::TelnetClient::getTerminalSpeed | ( |  | ) |

protected

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

## getTerminalType()

*string TelnetClient::TelnetClient::getTerminalType | ( |  | ) |

protected

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

## getUsageInfo()

hash<auto> TelnetClient::TelnetClient::getUsageInfo | ( |  | ) |

Returns performance statistics for the socket.

Example:
  hash<auto> h = telnet.getUsageInfo();

Returns
  a hash with the following keys:
  - `"bytes_sent"`: an integer giving the total amount of bytes sent
  - `"bytes_recv"`: an integer giving the total amount of bytes received
  - `"us_sent"`: an integer giving the total number of microseconds spent sending data
  - `"us_recv"`: an integer giving the total number of microseconds spent receiving data
  - `"arg"`: (only if warning values have been set with TelnetClient::setWarningQueue()) the optional argument for warning hashes
  - `"timeout"`: (only if warning values have been set with TelnetClient::setWarningQueue()) the warning timeout in microseconds
  - `"min_throughput"`: (only if warning values have been set with TelnetClient::setWarningQueue()) the minimum warning throughput in bytes/sec

Since
  TelnetClient 1.1

See also
  TelnetClient::clearStats()

## getWindowSize()

hash TelnetClient::TelnetClient::getWindowSize | ( |  | ) |

protected

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

## hasFeature()

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

## sendData()

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

## sendTextData()

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

## setEventQueue() [1/2]

TelnetClient::TelnetClient::setEventQueue | ( |  | ) |

Removes any Queue object so that socket events are no longer added to the Queue.

Example:
  telnet.setEventQueue();

See also
  I/O Event Handling for more information

Since
  TelnetClient 1.6

## setEventQueue() [2/2]

TelnetClient::TelnetClient::setEventQueue | ( | Qore::Thread::Queue | queue,
|  | auto | arg,
|  | *bool | with_data
| ) |  |

Sets a Queue object to receive socket events.

Example:
  telnet.setEventQueue(queue);

Parameters

  queue | the Queue object to receive socket events; note that the Queue passed cannot have any maximum size set or a QUEUE-ERROR will be thrown
  arg | an argument that will be included in each event hash in the arg key
  with_data | if True, then the actual raw data transferred / received is also included in the events

Exceptions

  QUEUE-ERROR | the Queue passed has a maximum size set

See also
  I/O Event Handling for more information

Since
  TelnetClient 1.6

## setUser()

TelnetClient::TelnetClient::setUser | ( | *string | n_user | ) |

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

Parameters

  n_user | the username to use for logins

Note
  This method is subject to thread serialization.

## setWarningQueue()

nothing TelnetClient::TelnetClient::setWarningQueue | ( | int | warning_ms,
|  | int | warning_bs,
|  | Queue | queue,
|  | any | arg,
|  | timeout | min_ms = `1s`
| ) |  |

Sets a Queue object to receive socket warnings.

Example:
  telnet.setWarningQueue(5000, 5000, queue, "socket-1");

Parameters

  warning_ms

  the threshold in milliseconds for individual socket actions (send, receive, connect), if exceeded, a socket warning is placed on the warning queue with the following keys:
  - `"type"`: a string with the constant value `"SOCKET-OPERATION-WARNING"`
  - `"operation"`: a string giving the operation that caused the warning (ex: `"connect"`)
  - `"us"`: an integer giving the number of microseconds for the operation
  - `"timeout"`: an integer giving the warning threshold in microseconds
  - `"arg"`: if any `"arg"` argument is passed to the TelnetClient::setWarningQueue() method, it will be included in the warning hash here

  warning_bs

  value in bytes per second; if any call has performance below this threshold, a socket warning is placed on the warning queue with the following keys:
  - `"type"`: a string with the constant value `"SOCKET-THROUGHPUT-WARNING"`
  - `"dir"`: either `"send"` or `"recv"` depending on the direction of the data flow
  - `"bytes"`: the amount of bytes sent
  - `"us"`: an integer giving the number of microseconds for the operation
  - `"bytes_sec"`: a float giving the transfer speed in bytes per second
  - `"threshold"`: an integer giving the warning threshold in bytes per second
  - `"arg"`: if any `"arg"` argument is passed to the TelnetClient::setWarningQueue() method, it will be included in the warning hash here

  queue | the Queue object to receive warning events
  arg | an optional argument to be placed in the `"arg"` key in each warning hash (could be used to identify the socket for example)
  min_ms | the minimum transfer time with a resolution of milliseconds for a transfer to be eligible for triggering a warning; transfers that take less than this period of time are not eligible for raising a warning

Exceptions

  QUEUE-ERROR | the Queue passed has a maximum size set
  SOCKET-SETWARNINGQUEUE-ERROR | at least one of warning_ms and warning_bs must be > 0

See also
  TelnetClient::clearWarningQueue()

Since
  TelnetClient 1.1

## windowSizeUpdated()

TelnetClient::TelnetClient::windowSizeUpdated | ( |  | ) |

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

See also
  getWindowSize()