williamr@2: /**
williamr@2: * Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@2: * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:
williamr@2: * Telnet Session API
williamr@2: * 
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2:  @file TELSESS.H
williamr@2: */
williamr@2: 
williamr@2: #ifndef _TELSESS_H_
williamr@2: #define _TELSESS_H_
williamr@2: 
williamr@2: #include <in_sock.h>
williamr@2: #include <e32std.h>
williamr@2: #include <e32cons.h>
williamr@2: #include <f32file.h>
williamr@2: 
williamr@2: #define __TELNETSESSDEBUG__ // Put in Debug mode
williamr@2: 
williamr@2: class CTelnetControl;
williamr@2: 
williamr@2: // Used by client to retrieve RFC option state
williamr@2: // Flags for Telnet negotiated options
williamr@2: // 1 = Enabled 0 = Disabled
williamr@2: 
williamr@2: /**
williamr@2: Defines the supported, RFC-defined, option status.
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released 
williamr@2: */
williamr@2: typedef struct
williamr@2:     {
williamr@2: 	/** If ETrue, the server is sending in binary (RFC 856). */
williamr@2:     TBool    iServerBinary; ///< RFC 856  (Server Sending in Binary)
williamr@2: 	/** If ETrue, the client is sending in binary (RFC 856). */
williamr@2:     TBool    iClientBinary; ///< RFC 856  (Client Sending in Binary)
williamr@2: 	/** If ETrue, the server is echoing data back to the client (RFC 857). */
williamr@2:     TBool    iEcho;         ///< RFC 857  (Server Echoing Data from Client)
williamr@2: 	/** If ETrue, the client will negotiate about window size (RFC 1073). */
williamr@2:     TBool    iNAWS;         ///< RFC 1073 (Client Providing Window Size Information)
williamr@2: 	/** If ETrue, the terminal speed option is enabled (RFC 1079). */
williamr@2:     TBool    iTerminalSpeed;///< RFC 1079 (Client Providing Terminal Speed Information)
williamr@2: 	/** If ETrue, the client is providing terminal type information (RFC 1091). */
williamr@2:     TBool    iTerminalType; ///< RFC 1091 (Client Providing Terminal Type Information)
williamr@2: 	/** If ETrue, if the server is providing status information (RFC 859). */
williamr@2:     TBool    iServerStatus; ///< RFC 859  (Server Providing Status Information)
williamr@2: 	/** If ETrue, if the client is providing status information (RFC 859). */
williamr@2:     TBool    iClientStatus; ///< RFC 859  (Client Providing Status Information)
williamr@2:     }TOptionStatus;
williamr@2: 
williamr@2: // Used by client to configure the Symbian Telnet
williamr@2: class TTelnetConfig
williamr@2: /**
williamr@2: * Specifies telnet session configuration information.
williamr@2: * 
williamr@2: * The client must provide a reference to an instance of this class as a parameter 
williamr@2: * to the CTelnetSession::NewL() function. 
williamr@2: * 
williamr@2: * Configuration options can be modified, when the session is in progress, using 
williamr@2: * the CTelnetSession::DoModifyConfig() function. 
williamr@2: * 
williamr@2: * Configuration option state can be obtained using the CTelnetSession::OptionStatus() 
williamr@2: * function.
williamr@2: * @publishedAll
williamr@2: * @released 
williamr@2: */
williamr@2:     {
williamr@2:  public:
williamr@2: 
williamr@2: 	/** Constructor. */
williamr@2: 	 TTelnetConfig() {
williamr@2: 		              iAllowLogout = TRUE;        // RFC 727  - Default TRUE = Server Can Logout Client
williamr@2: 					  iWindowSize.x = (TInt16)80; // RFC 1073 - Default 80 x 24
williamr@2: 					  iWindowSize.y = (TInt16)24;
williamr@2: 					  iTermSpeed = _L8("38400");  // RFC 1079 - Default to 38400 Baud Terminal
williamr@2: 					  iTermType  = _L8("dumb");   // RFC 1091 - Default to base NVT Terminal
williamr@2: 					}
williamr@2: 	/** Destructor. */
williamr@2: 	 ~TTelnetConfig(){}
williamr@2: 
williamr@2: 	typedef struct
williamr@2: 		/** 
williamr@2: 		* Specifies the client's window size.
williamr@2: 		* 
williamr@2: 		* The default is 80 columns by 24 rows which constructs to x=80, y=24. 
williamr@2: 		*/
williamr@2: 		{
williamr@2: 		/** The client window's width (number of columns). */
williamr@2: 		TInt16 x;
williamr@2: 		/** The client window's height (number of rows). */
williamr@2: 		TInt16 y;
williamr@2: 		}TWindowSize;
williamr@2: 
williamr@2: 	/** 
williamr@2: 	* Specifies the client's window size.
williamr@2: 	* 
williamr@2: 	* The default is 80 columns by 24 rows. 
williamr@2: 	* 
williamr@2: 	* (RFC 1073 -- Set to Configure Window Size) 
williamr@2: 	*/
williamr@2: 	TWindowSize	iWindowSize; 
williamr@2: 	
williamr@2: 	/**
williamr@2: 	* Specifies the speed of the telnet connection.
williamr@2: 	* 
williamr@2: 	* The default is "38400" (in ASCII characters). Must be set to a server-supported rate.
williamr@2: 	* 
williamr@2: 	* (RFC 1079 -- Set to Configure Terminal Speed) 
williamr@2: 	*/
williamr@2: 	TBuf8<20>	iTermSpeed;  
williamr@2: 	
williamr@2: 	/**
williamr@2: 	* Specifies the terminal type.
williamr@2: 	* 
williamr@2: 	* The default is "dumb" (in ASCII characters). 
williamr@2: 	* 
williamr@2: 	* (RFC 1091 -- Set to Configure Terminal Type) 
williamr@2: 	*/
williamr@2: 	TBuf8<20>	iTermType;
williamr@2: 	
williamr@2: 	/**
williamr@2: 	* Specifies whether the telnet server can logout the client.
williamr@2: 	* 
williamr@2: 	* The default, ETrue, enables the server to logout the client. If EFalse any 
williamr@2: 	* logout request from the telnet server is rejected by the client.
williamr@2: 	*
williamr@2: 	* (RFC 727 -- Set/Clear to Enable/Disable Server Logout) 
williamr@2: 	*/
williamr@2: 	TBool		iAllowLogout;
williamr@2: 	
williamr@2: 	/**
williamr@2: 	* Enables or disables telnet server echo to client.
williamr@2: 	* 
williamr@2: 	* The default, ETrue, enables server echo. Note that although this is normal 
williamr@2: 	* telnet server behaviour, it is not a formal telnet requirement. It is therefore 
williamr@2: 	* recommended that the client implement an optional local echo. 
williamr@2: 	*
williamr@2: 	* (RFC 857 -- Set/Clear to Enable/Disable Server Echo to client) 
williamr@2: 	*/
williamr@2: 	TBool		iServerEcho;
williamr@2:     };
williamr@2: 
williamr@2: // Client can pass these in overloaded CTelnetSession::Write(TTelnetUserControl& aControlCode);
williamr@2: 
williamr@2: /**
williamr@2: * Specifies the telnet control code to send to the server.
williamr@2: *
williamr@2: * This is done using the overloaded CTelnetSession::Write() function.
williamr@2: * @publishedAll
williamr@2: * @released 
williamr@2: */
williamr@2: enum TTelnetUserControl 
williamr@2:     {
williamr@2: 	/** Control code not supported. */
williamr@2:     ENotSupported = 0,
williamr@2: 	
williamr@2: 	/**
williamr@2: 	* Break (the NVT 129th ASCII break code).
williamr@2: 	* The default is 243. This is not a valid control in Binary mode. 
williamr@2: 	*/
williamr@2:     EBrk	= 243,
williamr@2: 	
williamr@2: 	/**
williamr@2: 	* Interupt Process.
williamr@2: 	* The default is 244.
williamr@2: 	*/
williamr@2:     EIp		= 244,
williamr@2: 	
williamr@2: 	/** 
williamr@2: 	* Abort Output.
williamr@2: 	* The default is 245. 
williamr@2: 	*/
williamr@2:     EAo		= 245,
williamr@2: 	
williamr@2: 	/**
williamr@2: 	Are you there?
williamr@2: 	* The default is 246. 
williamr@2: 	*/
williamr@2:     EAyt	= 246,
williamr@2: 	
williamr@2: 	/**
williamr@2: 	* Erase Character. 
williamr@2: 	* The default is 247. This is not a valid control in Binary mode. 
williamr@2: 	*/
williamr@2:     EEc		= 247,
williamr@2: 	
williamr@2: 	/** 
williamr@2: 	* Erase Line.
williamr@2: 	* The default is 248. This is not a valid control in Binary mode. 
williamr@2: 	*/
williamr@2:     EEl		= 248,
williamr@2:     };
williamr@2: 
williamr@2: // Client MUST override this class
williamr@2: // Client MUST provide a pointer to an instance of this class as a parameter to CTelnetSession::NewL()
williamr@2: class MTelnetNotification
williamr@2: /**
williamr@2: * Symbian telnet notification interface.
williamr@2: * 
williamr@2: * Informs the client when an error occurs, when reads and writes have completed, 
williamr@2: * when a connection is made or closed and when configuration options change.
williamr@2: * @publishedAll
williamr@2: * @released 
williamr@2: */
williamr@2:     {
williamr@2:  public:
williamr@2: 	/** 
williamr@2: 	* Reports errors on the Telnet connection.
williamr@2: 	*
williamr@2: 	* The error code is supplied by the server. If this function is called, it is 
williamr@2: 	* likely that the connection has failed. Therefore it is recommended that the 
williamr@2: 	* client disconnects and resets its state.
williamr@2: 	* 
williamr@2: 	* @param aError	Error code from server. 
williamr@2: 	 */
williamr@2:     virtual void Error(TInt aError) = 0; ///< Miscellaneous Error callback
williamr@2: 	
williamr@2: 	/** 
williamr@2: 	* Passes the data that was received from the server to the client.
williamr@2: 	* 
williamr@2: 	* It is recommended that the client copies the data from this buffer, as it 
williamr@2: 	* is owned by the Symbian telnet.
williamr@2: 	* 
williamr@2: 	* @param aBuffer	Data received from server. 
williamr@2: 	*/
williamr@2:     virtual void ReadComplete(const TDesC8& aBuffer) = 0; ///< Last Read to Server completion callback
williamr@2: 	
williamr@2: 	/** Notifies the client that a write to the server from the client has completed. */
williamr@2:     virtual void WriteComplete() = 0; ///< Last Write to Server completion callback
williamr@2: 	
williamr@2: 	/** Notifies the client that the connection to the server has been closed. */
williamr@2:     virtual void ConnectionClosed() = 0; ///< Telnet Connection Closed callback
williamr@2: 	
williamr@2: 	/** Notifies the client that a connection to the server has been made. */
williamr@2:     virtual void Connected() = 0; ///< Telnet Connected callback
williamr@2: 	
williamr@2: 	/** Notifies the client that telnet configuration options have changed. */
williamr@2:     virtual void OptionsChanged() = 0;                    ///< Telnet RFC Options Changed callback
williamr@2:     };
williamr@2: 
williamr@2: class CTelnetControl;
williamr@2: 
williamr@2: class CTelnetSession : public CBase
williamr@2: /**
williamr@2: * The main Symbian telnet class.
williamr@2: * 
williamr@2: * Consists of a connection interface and a protocol interface. The connection 
williamr@2: * interface comprises member functions that: connect to, read from, write to 
williamr@2: * and disconnect from a telnet server.
williamr@2: * 
williamr@2: * The protocol interface includes member functions that get and set telnet configuration.
williamr@2: *
williamr@2: * @publishedAll
williamr@2: * @released 
williamr@2: */
williamr@2:     {
williamr@2:     //public:
williamr@2:     // Data Structures
williamr@2:  public:
williamr@2:     ~CTelnetSession();
williamr@2:     // Construction
williamr@2:     // Need to add max buffer size to constructor [check]
williamr@2:     IMPORT_C static CTelnetSession* NewL(const TTelnetConfig& aConfig,const MTelnetNotification* aNotifier);
williamr@2:  protected:
williamr@2:     IMPORT_C void ConstructL(const TTelnetConfig& aConfig,const MTelnetNotification* aNotifier);
williamr@2:     //
williamr@2:     // Connection Interface
williamr@2:     //
williamr@2:  public:
williamr@2:     IMPORT_C TInt Connect(const TInetAddr& aNetAddr); ///< Connects to aNetAddr on the standard telnet port (port 23)
williamr@2:     IMPORT_C TInt Connect(const TInetAddr& aNetAddr, TUint aPort); ///< Connects to aNetAddr on user specified port
williamr@2:     IMPORT_C TInt Connect(const TDesC& aServerName); ///< Connects to aSeverName on the standard telnet port (port 23)
williamr@2:     IMPORT_C TInt Connect(const TDesC& aServerName, TUint aPort); ///< Connects to aServerName on user specified port
williamr@2:     IMPORT_C TInt Disconnect(); ///< Disconnects current connection 
williamr@2:     IMPORT_C TInt Write(const TDesC8& aBuffer); ///< Writes a byte stream over the open telnet connection.
williamr@2:     IMPORT_C TInt Write(TTelnetUserControl& aControlCode); ///< Writes NVT code to stream. Prepends \<IAC\> code (255)
williamr@2:     IMPORT_C TInt Read(); ///< Read data received over telnet buffer.
williamr@2:     
williamr@2: 	//
williamr@2: 	// Protocol Interface 
williamr@2: 	//
williamr@2: 	IMPORT_C TInt DoForceLogout();
williamr@2: 	IMPORT_C TInt DoModifyConfig(TTelnetConfig& aConfig);
williamr@2: 	IMPORT_C TInt OptionStatus(TOptionStatus& aStatus);
williamr@2:  private:
williamr@2:     CTelnetSession();
williamr@2: 
williamr@2:  private:
williamr@2:     MTelnetNotification* iNotifier;
williamr@2:     CTelnetControl* iTelnetProtocol;
williamr@2: 
williamr@2:     };
williamr@2: 
williamr@2: 
williamr@2: #endif // _TELNETPROTOCOLAPI_H_