Class Telnet

Introduction

This class provides Telnet protocol communications over a supplied transport, which must be a member of a class derived from Transport -- typically a Socket. While Telnet is not a secure protocol for business applications, it is used by the Synergy/DE remote debugger -- which is why I created this class and its extensions. The CodeCoverage class uses a Telnet connection to the Synergy/DE debugger to sample code coverage.

Contents

  1. Introduction
  2. Contents
  3. Explanation of symbols used
  4. Member reference
    1. (constructor)
    2. GetChar - get the next character sent by the peer
    3. GetLine - get the next line of text sent by the peer
    4. Ready - is the connection ready for additional characters to be sent?
    5. Send - send text over the transport
    6. SendLine - send text over the transport, with line termination
  5. Related classes
    1. TelnetClient - a Telnet client over TCP/IP
      1. (constructors)
      2. Run - process a client session
    2. TelnetInputHandler - handler for Telnet input events
      1. OnConnect - respond to connection event
      2. OnDisconnect - respond to disconnection event
      3. OnInput - respond to input received
      4. OnReady - respond to a ready state
    3. TelnetServer - a Telnet server over TCP/IP
      1. (constructor)
      2. Run - process a server session

Explanation of symbols used

Words in italics indicate an instance of a class. The word corresponds to the class name, except where more than one instance is represented in the same statement. In that case a number (2, 3, etc.) is appended to the class name.

Words in normal typeface are to be taken literally (required punctuation, class name in a static reference, method name, etc.)

The symbol => is used to separate an expression (on the left) from its return value (on the right).

An ellipsis (...) indicates that the previous argument may be repeated any number of times. The description will indicate whether one instance is required.

Member reference

constructor

new Telnet(transport) => telnet
Creates a telnet session (client or server) using the provided transport, which must already be connected. Negotiation of Telnet options is initiated immediately.

method GetChar

telnet.GetChar() => a

Returns the next character received from the peer, excluding Telnet command characters (which are processed automatically). Text is received from the peer in chunks of up to 1024 bytes, but is buffered until requested by this method or the GetLine method.

Three Telnet commands return characters from this method: EC (erase character) returns a char(8) (backspace), EL (erase line) returns a char(21) (Ctrl+U), and GA (go ahead) returns a char(0) (NULL).

method GetLine

telnet.GetLine(a) => i
Returns the next line of text received from the peer in a, which must be writable. The number of characters returned in a is returned as i. This will be the lesser of the size of a or the index of an appropriate terminator (which is included in the returned text). Note that carriage-return is not considered a terminator, but line-feed is -- because the standard line termination for Telnet is a CR/LF pair. Here are all the special case characters:
  • NULL (char(0)) - not returned, but treated as a line terminator.
  • Backspace (char(8)) - not returned. If not the first character in the buffer, removes the previous character.
  • Ctrl+U (char(21)) - not returned. Erases all text up to this point in the buffer and begins anew.
  • Carriage-return (char(13)) - returned as a normal character.
  • All other control characters (char(1) thru char(31)) - returned and treated as a line terminator.

property Ready

telnet.Ready => boolean
This read-only property indicates whether the Telnet peer has sent a Go-Ahead authorization (GA) since our last transmission. Note that if the peer has requested to suppress go-ahead, this property will always be false. This implementation prefers to enable go-ahead, and attempts to negotiate such.

method Send

telnet.Send(a) => boolean
Sends the text in a over the transport associated with this connection, returning true if successful. Note that success does not imply that the peer has received the characters, merely that they were sent successfully. They could be buffered pending receipt.

method SendLine

telnet.SendLine(a) => boolean
Same as Send, but automatically appends a carriage-return and line-feed character to the end of a.