# PTelnetSocket Class Reference

A TCP/IP socket for the TELNET high level protocol. More...

`#include <telnet.h>`

Inheritance diagram for PTelnetSocket:

List of all members.

## Public Types

| IAC = 255
| Interpret As Command - escape character.
| DONT = 254
| You are not to use option.
| DO = 253
| Request to use option.
| WONT = 252
| Refuse use of option.
| WILL = 251
| Accept the use of option.
| SB = 250
| Subnegotiation begin.
| GoAhead = 249
| Function GA, you may reverse the line.
| EraseLine = 248
| Function EL, erase the current line.
| EraseChar = 247
| Function EC, erase the current character.
| AreYouThere = 246
| Function AYT, are you there?
| AbortOutput = 245
| Function AO, abort output stream.
| InterruptProcess = 244
| Function IP, interrupt process, permanently.
| Break = 243
| NVT character break.
| DataMark = 242
| Marker for connection cleaning.
| NOP = 241
| No operation.
| SE = 240
| Subnegotiation end.
| EndOfReccord = 239
| End of record for transparent mode.
| AbortProcess = 238
| Abort the entire process.
| SuspendProcess = 237
| Suspend the process.
| EndOfFile = 236
| End of file marker.
| TransmitBinary = 0
| Assume binary 8 bit data is transferred.
| EchoOption = 1
| Automatically echo characters sent.
| ReconnectOption = 2
| Prepare to reconnect.
| SuppressGoAhead = 3
| Do not use the GA protocol.
| MessageSizeOption = 4
| Negatiate approximate message size.
| StatusOption = 5
| Status packets are understood.
| TimingMark = 6
| Marker for synchronisation.
| RCTEOption = 7
| Remote controlled transmission and echo.
| OutputLineWidth = 8
| Negotiate about output line width.
| OutputPageSize = 9
| Negotiate about output page size.
| CRDisposition = 10
| Negotiate about CR disposition.
| HorizontalTabsStops = 11
| Negotiate about horizontal tabstops.
| HorizTabDisposition = 12
| Negotiate about horizontal tab disposition.
| FormFeedDisposition = 13
| Negotiate about formfeed disposition.
| VerticalTabStops = 14
| Negotiate about vertical tab stops.
| VertTabDisposition = 15
| Negotiate about vertical tab disposition.
| LineFeedDisposition = 16
| Negotiate about output LF disposition.
| ExtendedASCII = 17
| Extended ascic character set.
| ForceLogout = 18
| Force logout.
| ByteMacroOption = 19
| Byte macro.
| DataEntryTerminal = 20
| data entry terminal.
| SupDupProtocol = 21
| supdup protocol.
| SupDupOutput = 22
| supdup output.
| SendLocation = 23
| Send location.
| TerminalType = 24
| Provide terminal type information.
| EndOfRecordOption = 25
| Record boundary marker.
| TACACSUID = 26
| TACACS user identification.
| OutputMark = 27
| Output marker or banner text.
| TerminalLocation = 28
| Terminals physical location information.
| Use3270RegimeOption = 29
| 3270 regime.
| UseX3PADOption = 30
| X.3 PAD.
| WindowSize = 31
| NAWS - Negotiate About Window Size.
| TerminalSpeed = 32
| Provide terminal speed information.
| FlowControl = 33
| Remote flow control.
| LineModeOption = 34
| Terminal in line mode option.
| XDisplayLocation = 35
| X Display location.
| EnvironmentOption = 36
| Provide environment information.
| AuthenticateOption = 37
| Authenticate option.
| EncriptionOption = 38
| Encryption option.
| EncryptionOption = 38
| Duplicate to fix spelling mistake and remain backwards compatible.
| ExtendedOptionsList = 255
| Code for extended options.
| MaxOptions
| SubOptionIs = 0
| Sub-option is...
| SubOptionSend = 1
| Request to send option.
enum | Command { IAC = 255, DONT = 254, DO = 253, WONT = 252, WILL = 251, SB = 250, GoAhead = 249, EraseLine = 248, EraseChar = 247, AreYouThere = 246, AbortOutput = 245, InterruptProcess = 244, Break = 243, DataMark = 242, NOP = 241, SE = 240, EndOfReccord = 239, AbortProcess = 238, SuspendProcess = 237, EndOfFile = 236 }

enum

Options {
TransmitBinary = 0, EchoOption = 1, ReconnectOption = 2, SuppressGoAhead = 3,
MessageSizeOption = 4, StatusOption = 5, TimingMark = 6, RCTEOption = 7,
OutputLineWidth = 8, OutputPageSize = 9, CRDisposition = 10, HorizontalTabsStops = 11,
HorizTabDisposition = 12, FormFeedDisposition = 13, VerticalTabStops = 14, VertTabDisposition = 15,
LineFeedDisposition = 16, ExtendedASCII = 17, ForceLogout = 18, ByteMacroOption = 19,
DataEntryTerminal = 20, SupDupProtocol = 21, SupDupOutput = 22, SendLocation = 23,
TerminalType = 24, EndOfRecordOption = 25, TACACSUID = 26, OutputMark = 27,
TerminalLocation = 28, Use3270RegimeOption = 29, UseX3PADOption = 30, WindowSize = 31,
TerminalSpeed = 32, FlowControl = 33, LineModeOption = 34, XDisplayLocation = 35,
EnvironmentOption = 36, AuthenticateOption = 37, EncriptionOption = 38, EncryptionOption = 38,
ExtendedOptionsList = 255, MaxOptions
}

enum | SubOptionCodes { SubOptionIs = 0, SubOptionSend = 1 }

## Public Member Functions

| PTelnetSocket ()
| PTelnetSocket (const PString &address)
PBoolean | Read (void *buf, PINDEX len)
| Low level read from the channel.
PBoolean | Write (const void *buf, PINDEX len)
| Low level write to the channel.
virtual bool | SetLocalEcho (bool localEcho)
| Set local echo mode.
virtual PBoolean | Connect (const PString &address)
| Connect a socket to a remote host on the specified port number.
virtual PBoolean | Accept (PSocket &socket)
| Open a socket to a remote host on the specified port number.
virtual void | OnOutOfBand (const void *buf, PINDEX len)
| This is callback function called by the system whenever out of band data from the TCP/IP stream is received.
PBoolean | SendCommand (Command cmd, int opt=0)
| Send an escaped IAC command.
virtual PBoolean | SendDo (BYTE option)
| Send DO request.
virtual PBoolean | SendDont (BYTE option)
| Send DONT command.
virtual PBoolean | SendWill (BYTE option)
| Send WILL request.
virtual PBoolean | SendWont (BYTE option)
| Send WONT command.
PBoolean | SendSubOption (BYTE code, const BYTE *info, PINDEX len, int subCode=-1)
| Send a sub-option with the information given.
void | SetOurOption (BYTE code, PBoolean state=true)
| Set if the option on our side is possible, this does not mean it is set it only means that in response to a DO we WILL rather than WONT.
void | SetTheirOption (BYTE code, PBoolean state=true)
| Set if the option on their side is desired, this does not mean it is set it only means that in response to a WILL we DO rather than DONT.
PBoolean | IsOurOption (BYTE code) const
| Determine if the option on our side is enabled.
PBoolean | IsTheirOption (BYTE code) const
| Determine if the option on their side is enabled.
void | SetTerminalType (const PString &newType)
const PString & | GetTerminalType () const
void | SetWindowSize (WORD width, WORD height)
void | GetWindowSize (WORD &width, WORD &height) const

## Protected Member Functions

void | Construct ()
virtual void | OnDo (BYTE option)
| This callback function is called by the system when it receives a DO request from the remote system.
virtual void | OnDont (BYTE option)
| This callback function is called by the system when it receives a DONT request from the remote system.
virtual void | OnWill (BYTE option)
| This callback function is called by the system when it receives a WILL request from the remote system.
virtual void | OnWont (BYTE option)
| This callback function is called by the system when it receives a WONT request from the remote system.
virtual void | OnSubOption (BYTE code, const BYTE *info, PINDEX len)
| This callback function is called by the system when it receives a sub-option command from the remote system.
virtual PBoolean | OnCommand (BYTE code)
| This callback function is called by the system when it receives an telnet command that it does not do anything with.

## Protected Attributes

OptionInfo | option [MaxOptions]
PString | terminalType
WORD | windowWidth
WORD | windowHeight

## Classes

struct | OptionInfo

## Detailed Description

A TCP/IP socket for the TELNET high level protocol.

## Member Enumeration Documentation

enum PTelnetSocket::Command

Enumerator:

  IAC | Interpret As Command - escape character.
  DONT | You are not to use option.
  DO | Request to use option.
  WONT | Refuse use of option.
  WILL | Accept the use of option.
  SB | Subnegotiation begin.
  GoAhead | Function GA, you may reverse the line.
  EraseLine | Function EL, erase the current line.
  EraseChar | Function EC, erase the current character.
  AreYouThere | Function AYT, are you there?
  AbortOutput | Function AO, abort output stream.
  InterruptProcess | Function IP, interrupt process, permanently.
  Break | NVT character break.
  DataMark | Marker for connection cleaning.
  NOP | No operation.
  SE | Subnegotiation end.
  EndOfReccord | End of record for transparent mode.
  AbortProcess | Abort the entire process.
  SuspendProcess | Suspend the process.
  EndOfFile | End of file marker.

enum PTelnetSocket::Options

Enumerator:

  TransmitBinary | Assume binary 8 bit data is transferred.
  EchoOption | Automatically echo characters sent.
  ReconnectOption | Prepare to reconnect.
  SuppressGoAhead | Do not use the GA protocol.
  MessageSizeOption | Negatiate approximate message size.
  StatusOption | Status packets are understood.
  TimingMark | Marker for synchronisation.
  RCTEOption | Remote controlled transmission and echo.
  OutputLineWidth | Negotiate about output line width.
  OutputPageSize | Negotiate about output page size.
  CRDisposition | Negotiate about CR disposition.
  HorizontalTabsStops | Negotiate about horizontal tabstops.
  HorizTabDisposition | Negotiate about horizontal tab disposition.
  FormFeedDisposition | Negotiate about formfeed disposition.
  VerticalTabStops | Negotiate about vertical tab stops.
  VertTabDisposition | Negotiate about vertical tab disposition.
  LineFeedDisposition | Negotiate about output LF disposition.
  ExtendedASCII | Extended ascic character set.
  ForceLogout | Force logout.
  ByteMacroOption | Byte macro.
  DataEntryTerminal | data entry terminal.
  SupDupProtocol | supdup protocol.
  SupDupOutput | supdup output.
  SendLocation | Send location.
  TerminalType | Provide terminal type information.
  EndOfRecordOption | Record boundary marker.
  TACACSUID | TACACS user identification.
  OutputMark | Output marker or banner text.
  TerminalLocation | Terminals physical location information.
  Use3270RegimeOption | 3270 regime.
  UseX3PADOption | X.3 PAD.
  WindowSize | NAWS - Negotiate About Window Size.
  TerminalSpeed | Provide terminal speed information.
  FlowControl | Remote flow control.
  LineModeOption | Terminal in line mode option.
  XDisplayLocation | X Display location.
  EnvironmentOption | Provide environment information.
  AuthenticateOption | Authenticate option.
  EncriptionOption | Encryption option.
  EncryptionOption | Duplicate to fix spelling mistake and remain backwards compatible.
  ExtendedOptionsList | Code for extended options.
  MaxOptions |

enum PTelnetSocket::SubOptionCodes

Enumerator:

  SubOptionIs | Sub-option is...
  SubOptionSend | Request to send option.

## Constructor & Destructor Documentation

PTelnetSocket::PTelnetSocket | ( |  | ) |

PTelnetSocket::PTelnetSocket | ( | const PString & | address | ) |

Parameters:

  address | Address of remote machine to connect to.

## Member Function Documentation

virtual PBoolean PTelnetSocket::Accept | ( | PSocket & | socket | ) | `[virtual]`

Open a socket to a remote host on the specified port number.

This is an "accepting" socket. When a "listening" socket has a pending connection to make, this will accept a connection made by the "connecting" socket created to establish a link.

The port that the socket uses is the one used in the Listen() command of the `socket` parameter.

Note that this function will block until a remote system connects to the port number specified in the "listening" socket.

Returns:
  true if the channel was successfully opened.

Parameters:

  socket | Listening socket making the connection.

Reimplemented from PTCPSocket.

virtual PBoolean PTelnetSocket::Connect | ( | const PString & | address | ) | `[virtual]`

Connect a socket to a remote host on the specified port number.

This is typically used by the client or initiator of a communications channel. This connects to a "listening" socket at the other end of the communications channel.

The port number as defined by the object instance construction or the PIPSocket::SetPort() function.

Returns:
  true if the channel was successfully connected to the remote host.

Parameters:

  address | Address of remote machine to connect to.

Reimplemented from PIPSocket.

void PTelnetSocket::Construct | ( |  | ) | `[protected]`

Reimplemented from PChannel.

const PString& PTelnetSocket::GetTerminalType | ( |  | ) | const`[inline]`

void PTelnetSocket::GetWindowSize | ( | WORD & | width,
|  | WORD & | height |
| ) |  |  | const

Parameters:

  width | Old window width.
  height | Old window height.

PBoolean PTelnetSocket::IsOurOption | ( | BYTE | code | ) | const`[inline]`

Determine if the option on our side is enabled.

Returns:
  true if option is enabled.

Parameters:

  code | Option to check.

PBoolean PTelnetSocket::IsTheirOption | ( | BYTE | code | ) | const`[inline]`

Determine if the option on their side is enabled.

Returns:
  true if option is enabled.

Parameters:

  code | Option to check.

virtual PBoolean PTelnetSocket::OnCommand | ( | BYTE | code | ) | `[protected, virtual]`

This callback function is called by the system when it receives an telnet command that it does not do anything with.

The default action displays a message to the PError stream (when `debug` is true) and returns true;

Returns:
  true if next byte is not part of the command.

Parameters:

  code | Code received that could not be precessed.

virtual void PTelnetSocket::OnDo | ( | BYTE | option | ) | `[protected, virtual]`

This callback function is called by the system when it receives a DO request from the remote system.

The default action is to send a WILL for options that are understood by the standard TELNET class and a WONT for all others.

Returns:
  true if option is accepted.

Parameters:

  option | Option to DO

virtual void PTelnetSocket::OnDont | ( | BYTE | option | ) | `[protected, virtual]`

This callback function is called by the system when it receives a DONT request from the remote system.

The default action is to disable options that are understood by the standard TELNET class. All others are ignored.

Parameters:

  option | Option to DONT

virtual void PTelnetSocket::OnOutOfBand | ( | const void * | buf,
|  | PINDEX | len |
| ) |  |  | `[virtual]`

This is callback function called by the system whenever out of band data from the TCP/IP stream is received.

A descendent class may interpret this data according to the semantics of the high level protocol.

The TELNET socket uses this for sychronisation.

Parameters:

  buf | Data to be received as URGENT TCP data.
  len | Number of bytes pointed to by `buf`.

Reimplemented from PTCPSocket.

virtual void PTelnetSocket::OnSubOption | ( | BYTE | code,
|  | const BYTE * | info,
|  | PINDEX | len |
| ) |  |  | `[protected, virtual]`

This callback function is called by the system when it receives a sub-option command from the remote system.

Parameters:

  code | Option code for sub-option data.
  info | Extra information being sent in the sub-option.
  len | Number of extra bytes.

virtual void PTelnetSocket::OnWill | ( | BYTE | option | ) | `[protected, virtual]`

This callback function is called by the system when it receives a WILL request from the remote system.

The default action is to send a DO for options that are understood by the standard TELNET class and a DONT for all others.

Parameters:

  option | Option to WILL

virtual void PTelnetSocket::OnWont | ( | BYTE | option | ) | `[protected, virtual]`

This callback function is called by the system when it receives a WONT request from the remote system.

The default action is to disable options that are understood by the standard TELNET class. All others are ignored.

Parameters:

  option | Option to WONT

PBoolean PTelnetSocket::Read | ( | void * | buf,
|  | PINDEX | len |
| ) |  |  | `[virtual]`

Low level read from the channel.

This function may block until the requested number of characters were read or the read timeout was reached. The GetLastReadCount() function returns the actual number of bytes read.

The GetErrorCode() function should be consulted after Read() returns false to determine what caused the failure.

The TELNET channel intercepts and escapes commands in the data stream to implement the TELNET protocol.

Returns:
  true indicates that at least one character was read from the channel. false means no bytes were read due to timeout or some other I/O error.

Parameters:

  buf | Pointer to a block of memory to receive the read bytes.
  len | Maximum number of bytes to read into the buffer.

Reimplemented from PTCPSocket.

PBoolean PTelnetSocket::SendCommand | ( | Command | cmd,
|  | int | opt = `0` |
| ) |  |  |

Send an escaped IAC command.

The `opt` parameters meaning depends on the command being sent:

DO, DONT, WILL, WONT
  `opt` is Options code.

AbortOutput
  true is flush buffer.

InterruptProcess, Break, AbortProcess, SuspendProcess
  true is synchronise.

Synchronises the TELNET streams, inserts the data mark into outgoing data stream and sends an out of band data to the remote to flush all data in the stream up until the syncronisation command.

Returns:
  true if the command was successfully sent.

Parameters:

  cmd | Command code to send
  opt | Option for command code.

virtual PBoolean PTelnetSocket::SendDo | ( | BYTE | option | ) | `[virtual]`

Send DO request.

Returns:
  true if the command was successfully sent.

Parameters:

  option | Option to DO

virtual PBoolean PTelnetSocket::SendDont | ( | BYTE | option | ) | `[virtual]`

Send DONT command.

Returns:
  true if the command was successfully sent.

Parameters:

  option | Option to DONT

PBoolean PTelnetSocket::SendSubOption | ( | BYTE | code,
|  | const BYTE * | info,
|  | PINDEX | len,
|  | int | subCode = `-1` |
| ) |  |  |

Send a sub-option with the information given.

Returns:
  true if the command was successfully sent.

Parameters:

  code | Suboptions option code.
  info | Information to send.
  len | Length of information.
  subCode | Suboptions sub-code, -1 indicates no sub-code.

virtual PBoolean PTelnetSocket::SendWill | ( | BYTE | option | ) | `[virtual]`

Send WILL request.

Returns:
  true if the command was successfully sent.

Parameters:

  option | Option to WILL

virtual PBoolean PTelnetSocket::SendWont | ( | BYTE | option | ) | `[virtual]`

Send WONT command.

Returns:
  true if the command was successfully sent.

Parameters:

  option | Option to WONT

virtual bool PTelnetSocket::SetLocalEcho | ( | bool | localEcho | ) | `[virtual]`

Set local echo mode.

For some classes of channel, e.g. PConsoleChannel, data read by this channel is automatically echoed. This disables the function so things like password entry can work.

Default behaviour does nothing and return true if the channel is open.

Reimplemented from PChannel.

void PTelnetSocket::SetOurOption | ( | BYTE | code,
|  | PBoolean | state = `true` |
| ) |  |  | `[inline]`

Set if the option on our side is possible, this does not mean it is set it only means that in response to a DO we WILL rather than WONT.

Parameters:

  code | Option to check.
  state | New state for for option.

void PTelnetSocket::SetTerminalType | ( | const PString & | newType | ) |

Parameters:

  newType | New terminal type description string.

void PTelnetSocket::SetTheirOption | ( | BYTE | code,
|  | PBoolean | state = `true` |
| ) |  |  | `[inline]`

Set if the option on their side is desired, this does not mean it is set it only means that in response to a WILL we DO rather than DONT.

Parameters:

  code | Option to check.
  state | New state for for option.

void PTelnetSocket::SetWindowSize | ( | WORD | width,
|  | WORD | height |
| ) |  |  |

Parameters:

  width | New window width.
  height | New window height.

PBoolean PTelnetSocket::Write | ( | const void * | buf,
|  | PINDEX | len |
| ) |  |  | `[virtual]`

Low level write to the channel.

This function will block until the requested number of characters are written or the write timeout is reached. The GetLastWriteCount() function returns the actual number of bytes written.

The GetErrorCode() function should be consulted after Write() returns false to determine what caused the failure.

The TELNET channel intercepts and escapes commands in the data stream to implement the TELNET protocol.

Returns true if at least len bytes were written to the channel.

Parameters:

  buf | Pointer to a block of memory to write.
  len | Number of bytes to write.

Reimplemented from PTCPSocket.

## Member Data Documentation

OptionInfo PTelnetSocket::option[MaxOptions]`[protected]`

PString PTelnetSocket::terminalType `[protected]`

WORD PTelnetSocket::windowHeight `[protected]`

WORD PTelnetSocket::windowWidth `[protected]`

The documentation for this class was generated from the following file:

- telnet.h