include/ptclib/telnet.h

   1 /*
   2  * telnet.h
   3  *
   4  * TELNET Socket class.
   5  *
   6  * Portable Windows Library
   7  *
   8  * Copyright (c) 1993-2002 Equivalence Pty. Ltd.
   9  *
  10  * The contents of this file are subject to the Mozilla Public License
  11  * Version 1.0 (the "License"); you may not use this file except in
  12  * compliance with the License. You may obtain a copy of the License at
  13  * http://www.mozilla.org/MPL/
  14  *
  15  * Software distributed under the License is distributed on an "AS IS"
  16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  17  * the License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * The Original Code is Portable Windows Library.
  21  *
  22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
  23  *
  24  * Contributor(s): ______________________________________.
  25  *
  26  * $Log$
  27  * Revision 1.23  2002/11/06 22:47:24  robertj
  28  * Fixed header comment (copyright etc)
  29  *
  30  * Revision 1.22  2002/09/16 01:08:59  robertj
  31  * Added #define so can select if #pragma interface/implementation is used on
  32  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
  33  *
  34  * Revision 1.21  1999/03/09 08:01:47  robertj
  35  * Changed comments for doc++ support (more to come).
  36  *
  37  * Revision 1.20  1999/02/16 08:07:10  robertj
  38  * MSVC 6.0 compatibility changes.
  39  *
  40  * Revision 1.19  1998/11/30 02:50:56  robertj
  41  * New directory structure
  42  *
  43  * Revision 1.18  1998/09/23 06:20:04  robertj
  44  * Added open source copyright license.
  45  *
  46  * Revision 1.17  1996/08/08 10:08:54  robertj
  47  * Directory structure changes for common files.
  48  *
  49  * Revision 1.16  1995/06/17 11:13:32  robertj
  50  * Documentation update.
  51  *
  52  * Revision 1.15  1995/06/17 00:47:38  robertj
  53  * Changed overloaded Open() calls to 3 separate function names.
  54  * More logical design of port numbers and service names.
  55  *
  56  * Revision 1.14  1995/06/04 12:46:26  robertj
  57  * Slight redesign of port numbers on sockets.
  58  *
  59  * Revision 1.13  1995/04/25 11:12:30  robertj
  60  * Fixed functions hiding ancestor virtuals.
  61  *
  62  * Revision 1.12  1995/04/01 08:32:10  robertj
  63  * Finally got a working TELNET.
  64  *
  65  * Revision 1.11  1995/03/18 06:27:50  robertj
  66  * Rewrite of telnet socket protocol according to RFC1143.
  67  *
  68  * Revision 1.10  1995/03/14  12:42:47  robertj
  69  * Updated documentation to use HTML codes.
  70  *
  71  * Revision 1.9  1995/02/21  11:25:33  robertj
  72  * Further implementation of telnet socket, feature complete now.
  73  *
  74  * Revision 1.8  1995/01/03  09:36:23  robertj
  75  * Documentation.
  76  *
  77  * Revision 1.7  1995/01/01  01:07:33  robertj
  78  * More implementation.
  79  *
  80  * Revision 1.6  1994/11/28  12:38:59  robertj
  81  * Added DONT and WONT states.
  82  *
  83  * Revision 1.5  1994/08/23  11:32:52  robertj
  84  * Oops
  85  *
  86  * Revision 1.4  1994/08/22  00:46:48  robertj
  87  * Added pragma fro GNU C++ compiler.
  88  *
  89  * Revision 1.3  1994/08/21  23:43:02  robertj
  90  * Changed type of socket port number for better portability.
  91  *
  92  * Revision 1.2  1994/07/25  03:36:03  robertj
  93  * Added sockets to common, normalising to same comment standard.
  94  *
  95  */
  96
  97 #ifndef _PTELNETSOCKET
  98 #define _PTELNETSOCKET
  99
 100 #ifdef P_USE_PRAGMA
 101 #pragma interface
 102 #endif
 103
 104 #include <ptlib/sockets.h>
 105
 106
 107 /** A TCP/IP socket for the TELNET high level protocol.
 108  */
 109 class PTelnetSocket : public PTCPSocket
 110 {
 111   PCLASSINFO(PTelnetSocket, PTCPSocket)
 112
 113   public:
 114     PTelnetSocket();
 115     // Create an unopened TELNET socket.
 116
 117     PTelnetSocket(
 118       const PString & address  // Address of remote machine to connect to.
 119     );
 120     // Create an opened TELNET socket.
 121
 122
 123   // Overrides from class PChannel
 124     /** Low level read from the channel. This function may block until the
 125        requested number of characters were read or the read timeout was
 126        reached. The GetLastReadCount() function returns the actual number
 127        of bytes read.
 128
 129        The GetErrorCode() function should be consulted after Read() returns
 130        FALSE to determine what caused the failure.
 131
 132        The TELNET channel intercepts and escapes commands in the data stream to
 133        implement the TELNET protocol.
 134
 135        @return
 136        TRUE indicates that at least one character was read from the channel.
 137        FALSE means no bytes were read due to timeout or some other I/O error.
 138      */
 139     BOOL Read(
 140       void * buf,   // Pointer to a block of memory to receive the read bytes.
 141       PINDEX len    // Maximum number of bytes to read into the buffer.
 142     );
 143
 144     /** Low level write to the channel. This function will block until the
 145        requested number of characters are written or the write timeout is
 146        reached. The GetLastWriteCount() function returns the actual number
 147        of bytes written.
 148
 149        The GetErrorCode() function should be consulted after Write() returns
 150        FALSE to determine what caused the failure.
 151
 152        The TELNET channel intercepts and escapes commands in the data stream to
 153        implement the TELNET protocol.
 154
 155        Returns TRUE if at least len bytes were written to the channel.
 156      */
 157     BOOL Write(
 158       const void * buf, // Pointer to a block of memory to write.
 159       PINDEX len        // Number of bytes to write.
 160     );
 161
 162
 163     /** Connect a socket to a remote host on the specified port number. This is
 164        typically used by the client or initiator of a communications channel.
 165        This connects to a "listening" socket at the other end of the
 166        communications channel.
 167
 168        The port number as defined by the object instance construction or the
 169        <A>PIPSocket::SetPort()</A> function.
 170
 171        @return
 172        TRUE if the channel was successfully connected to the remote host.
 173      */
 174     virtual BOOL Connect(
 175       const PString & address   // Address of remote machine to connect to.
 176     );
 177
 178
 179     /** Open a socket to a remote host on the specified port number. This is an
 180        "accepting" socket. When a "listening" socket has a pending connection
 181        to make, this will accept a connection made by the "connecting" socket
 182        created to establish a link.
 183
 184        The port that the socket uses is the one used in the <A>Listen()</A>
 185        command of the <CODE>socket</CODE> parameter.
 186
 187        Note that this function will block until a remote system connects to the
 188        port number specified in the "listening" socket.
 189
 190        @return
 191        TRUE if the channel was successfully opened.
 192      */
 193     virtual BOOL Accept(
 194       PSocket & socket          // Listening socket making the connection.
 195     );
 196
 197
 198     /** This is callback function called by the system whenever out of band data
 199        from the TCP/IP stream is received. A descendent class may interpret
 200        this data according to the semantics of the high level protocol.
 201
 202        The TELNET socket uses this for sychronisation.
 203      */
 204     virtual void OnOutOfBand(
 205       const void * buf,   // Data to be received as URGENT TCP data.
 206       PINDEX len          // Number of bytes pointed to by <CODE>buf</CODE>.
 207     );
 208
 209
 210   // New functions
 211     enum Command {
 212       IAC           = 255,    // Interpret As Command - escape character.
 213       DONT          = 254,    // You are not to use option.
 214       DO            = 253,    // Request to use option.
 215       WONT          = 252,    // Refuse use of option.
 216       WILL          = 251,    // Accept the use of option.
 217       SB            = 250,    // Subnegotiation begin.
 218       GoAhead       = 249,    // Function GA, you may reverse the line.
 219       EraseLine     = 248,    // Function EL, erase the current line.
 220       EraseChar     = 247,    // Function EC, erase the current character.
 221       AreYouThere   = 246,    // Function AYT, are you there?
 222       AbortOutput   = 245,    // Function AO, abort output stream.
 223       InterruptProcess = 244, // Function IP, interrupt process, permanently.
 224       Break         = 243,    // NVT character break.
 225       DataMark      = 242,    // Marker for connection cleaning.
 226       NOP           = 241,    // No operation.
 227       SE            = 240,    // Subnegotiation end.
 228       EndOfReccord  = 239,    // End of record for transparent mode.
 229       AbortProcess  = 238,    // Abort the entire process
 230       SuspendProcess= 237,    // Suspend the process.
 231       EndOfFile     = 236     // End of file marker.
 232     };
 233     // Defined telnet commands codes
 234
 235     /** Send an escaped IAC command. The <CODE>opt</CODE> parameters meaning
 236        depends on the command being sent:
 237
 238        <DL>
 239        <DT>DO, DONT, WILL, WONT    <DD><CODE>opt</CODE> is Options code.
 240
 241        <DT>AbortOutput             <DD>TRUE is flush buffer.
 242
 243        <DT>InterruptProcess,
 244           Break, AbortProcess,
 245           SuspendProcess           <DD>TRUE is synchronise.
 246        </DL>
 247
 248        Synchronises the TELNET streams, inserts the data mark into outgoing
 249        data stream and sends an out of band data to the remote to flush all
 250        data in the stream up until the syncronisation command.
 251
 252        @return
 253        TRUE if the command was successfully sent.
 254      */
 255     BOOL SendCommand(
 256       Command cmd,  // Command code to send
 257       int opt = 0  // Option for command code.
 258     );
 259
 260
 261     enum Options {
 262       TransmitBinary      = 0,    // Assume binary 8 bit data is transferred.
 263       EchoOption          = 1,    // Automatically echo characters sent.
 264       ReconnectOption     = 2,    // Prepare to reconnect
 265       SuppressGoAhead     = 3,    // Do not use the GA protocol.
 266       MessageSizeOption   = 4,    // Negatiate approximate message size
 267       StatusOption        = 5,    // Status packets are understood.
 268       TimingMark          = 6,    // Marker for synchronisation.
 269       RCTEOption          = 7,    // Remote controlled transmission and echo.
 270       OutputLineWidth     = 8,    // Negotiate about output line width.
 271       OutputPageSize      = 9,    // Negotiate about output page size.
 272       CRDisposition       = 10,   // Negotiate about CR disposition.
 273       HorizontalTabsStops = 11,   // Negotiate about horizontal tabstops.
 274       HorizTabDisposition = 12,   // Negotiate about horizontal tab disposition
 275       FormFeedDisposition = 13,   // Negotiate about formfeed disposition.
 276       VerticalTabStops    = 14,   // Negotiate about vertical tab stops.
 277       VertTabDisposition  = 15,   // Negotiate about vertical tab disposition.
 278       LineFeedDisposition = 16,   // Negotiate about output LF disposition.
 279       ExtendedASCII       = 17,   // Extended ascic character set.
 280       ForceLogout         = 18,   // Force logout.
 281       ByteMacroOption     = 19,   // Byte macro.
 282       DataEntryTerminal   = 20,   // data entry terminal.
 283       SupDupProtocol      = 21,   // supdup protocol.
 284       SupDupOutput        = 22,   // supdup output.
 285       SendLocation        = 23,   // Send location.
 286       TerminalType        = 24,   // Provide terminal type information.
 287       EndOfRecordOption   = 25,   // Record boundary marker.
 288       TACACSUID           = 26,   // TACACS user identification.
 289       OutputMark          = 27,   // Output marker or banner text.
 290       TerminalLocation    = 28,   // Terminals physical location infromation.
 291       Use3270RegimeOption = 29,   // 3270 regime.
 292       UseX3PADOption      = 30,   // X.3 PAD
 293       WindowSize          = 31,   // NAWS - Negotiate About Window Size.
 294       TerminalSpeed       = 32,   // Provide terminal speed information.
 295       FlowControl         = 33,   // Remote flow control.
 296       LineModeOption      = 34,   // Terminal in line mode option.
 297       XDisplayLocation    = 35,   // X Display location.
 298       EnvironmentOption   = 36,   // Provide environment information.
 299       AuthenticateOption  = 37,   // Authenticate option.
 300       EncriptionOption    = 38,   // Encryption option.
 301       ExtendedOptionsList = 255,  // Code for extended options.
 302       MaxOptions
 303     };
 304     // Defined TELNET options.
 305
 306
 307     /** Send DO request.
 308
 309        @return
 310        TRUE if the command was successfully sent.
 311      */
 312     virtual BOOL SendDo(
 313       BYTE option    // Option to DO
 314     );
 315
 316     /** Send DONT command.
 317
 318        @return
 319        TRUE if the command was successfully sent.
 320      */
 321     virtual BOOL SendDont(
 322       BYTE option    // Option to DONT
 323     );
 324
 325     /** Send WILL request.
 326
 327        @return
 328        TRUE if the command was successfully sent.
 329      */
 330     virtual BOOL SendWill(
 331       BYTE option    // Option to WILL
 332     );
 333
 334     /** Send WONT command.
 335
 336        @return
 337        TRUE if the command was successfully sent.
 338      */
 339     virtual BOOL SendWont(
 340       BYTE option    // Option to WONT
 341     );
 342
 343     enum SubOptionCodes {
 344       SubOptionIs       = 0,  // Sub-option is...
 345       SubOptionSend     = 1,  // Request to send option.
 346     };
 347     // Codes for sub option negotiation.
 348
 349     /** Send a sub-option with the information given.
 350
 351        @return
 352        TRUE if the command was successfully sent.
 353      */
 354     BOOL SendSubOption(
 355       BYTE code,          // Suboptions option code.
 356       const BYTE * info,  // Information to send.
 357       PINDEX len,         // Length of information.
 358       int subCode = -1    // Suboptions sub-code, -1 indicates no sub-code.
 359     );
 360
 361     /** Set if the option on our side is possible, this does not mean it is set
 362        it only means that in response to a DO we WILL rather than WONT.
 363      */
 364     void SetOurOption(
 365       BYTE code,          // Option to check.
 366       BOOL state = TRUE   // New state for for option.
 367     ) { option[code].weCan = state; }
 368
 369     /** Set if the option on their side is desired, this does not mean it is set
 370        it only means that in response to a WILL we DO rather than DONT.
 371      */
 372     void SetTheirOption(
 373       BYTE code,          // Option to check.
 374       BOOL state = TRUE  // New state for for option.
 375     ) { option[code].theyShould = state; }
 376
 377     /** Determine if the option on our side is enabled.
 378
 379        @return
 380        TRUE if option is enabled.
 381      */
 382     BOOL IsOurOption(
 383       BYTE code    // Option to check.
 384     ) const { return option[code].ourState == OptionInfo::IsYes; }
 385
 386     /** Determine if the option on their side is enabled.
 387
 388        @return
 389        TRUE if option is enabled.
 390      */
 391     BOOL IsTheirOption(
 392       BYTE code    // Option to check.
 393     ) const { return option[code].theirState == OptionInfo::IsYes; }
 394
 395     void SetTerminalType(
 396       const PString & newType   // New terminal type description string.
 397     );
 398     // Set the terminal type description string for TELNET protocol.
 399
 400     const PString & GetTerminalType() const { return terminalType; }
 401     // Get the terminal type description string for TELNET protocol.
 402
 403     void SetWindowSize(
 404       WORD width,   // New window width.
 405       WORD height   // New window height.
 406     );
 407     // Set the width and height of the Network Virtual Terminal window.
 408
 409     void GetWindowSize(
 410       WORD & width,   // Old window width.
 411       WORD & height   // Old window height.
 412     ) const;
 413     // Get the width and height of the Network Virtual Terminal window.
 414
 415
 416   protected:
 417     void Construct();
 418     // Common construct code for TELNET socket channel.
 419
 420     /** This callback function is called by the system when it receives a DO
 421        request from the remote system.
 422
 423        The default action is to send a WILL for options that are understood by
 424        the standard TELNET class and a WONT for all others.
 425
 426        @return
 427        TRUE if option is accepted.
 428      */
 429     virtual void OnDo(
 430       BYTE option   // Option to DO
 431     );
 432
 433     /** This callback function is called by the system when it receives a DONT
 434        request from the remote system.
 435
 436        The default action is to disable options that are understood by the
 437        standard TELNET class. All others are ignored.
 438      */
 439     virtual void OnDont(
 440       BYTE option   // Option to DONT
 441     );
 442
 443     /** This callback function is called by the system when it receives a WILL
 444        request from the remote system.
 445
 446        The default action is to send a DO for options that are understood by
 447        the standard TELNET class and a DONT for all others.
 448      */
 449     virtual void OnWill(
 450       BYTE option   // Option to WILL
 451     );
 452
 453     /** This callback function is called by the system when it receives a WONT
 454        request from the remote system.
 455
 456        The default action is to disable options that are understood by the
 457        standard TELNET class. All others are ignored.
 458      */
 459     virtual void OnWont(
 460       BYTE option   // Option to WONT
 461     );
 462
 463     /** This callback function is called by the system when it receives a
 464        sub-option command from the remote system.
 465      */
 466     virtual void OnSubOption(
 467       BYTE code,          // Option code for sub-option data.
 468       const BYTE * info,  // Extra information being sent in the sub-option.
 469       PINDEX len          // Number of extra bytes.
 470     );
 471
 472
 473     /** This callback function is called by the system when it receives an
 474        telnet command that it does not do anything with.
 475
 476        The default action displays a message to the <A>PError</A> stream
 477        (when <CODE>debug</CODE> is TRUE) and returns TRUE;
 478
 479        @return
 480        TRUE if next byte is not part of the command.
 481      */
 482     virtual BOOL OnCommand(
 483       BYTE code  // Code received that could not be precessed.
 484     );
 485
 486
 487   // Member variables.
 488     struct OptionInfo {
 489       enum {
 490         IsNo, IsYes, WantNo, WantNoQueued, WantYes, WantYesQueued
 491       };
 492       unsigned weCan:1;      // We can do the option if they want us to do.
 493       unsigned ourState:3;
 494       unsigned theyShould:1; // They should if they will.
 495       unsigned theirState:3;
 496     };
 497
 498     OptionInfo option[MaxOptions];
 499     // Information on protocol options.
 500
 501     PString terminalType;
 502     // Type of terminal connected to telnet socket, defaults to "UNKNOWN"
 503
 504     WORD windowWidth, windowHeight;
 505     // Size of the "window" used by the NVT.
 506
 507     BOOL debug;
 508     // Debug socket, output messages to PError stream.
 509
 510
 511   private:
 512     enum State {
 513       StateNormal,
 514       StateCarriageReturn,
 515       StateIAC,
 516       StateDo,
 517       StateDont,
 518       StateWill,
 519       StateWont,
 520       StateSubNegotiations,
 521       StateEndNegotiations
 522     };
 523     // Internal states for the TELNET decoder
 524
 525     State state;
 526     // Current state of incoming characters.
 527
 528     PBYTEArray subOption;
 529     // Storage for sub-negotiated options
 530
 531     unsigned synchronising;
 532
 533     BOOL StartSend(const char * which, BYTE code);
 534 };
 535
 536
 537 #endif
 538
 539
 540 // End Of File ///////////////////////////////////////////////////////////////
 541