/**

* Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* 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

* which accompanies this distribution, and is available

* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:

* Telnet Session API

* 

*

*/

/**

 @file TELSESS.H

*/

#ifndef _TELSESS_H_

#define _TELSESS_H_

#include <in_sock.h>

#include <e32std.h>

#include <e32cons.h>

#include <f32file.h>

#define __TELNETSESSDEBUG__ // Put in Debug mode

class CTelnetControl;

// Used by client to retrieve RFC option state

// Flags for Telnet negotiated options

// 1 = Enabled 0 = Disabled

/**

Defines the supported, RFC-defined, option status.

@publishedAll

@released 

*/

typedef struct

    {

	/** If ETrue, the server is sending in binary (RFC 856). */

    TBool    iServerBinary; ///< RFC 856  (Server Sending in Binary)

	/** If ETrue, the client is sending in binary (RFC 856). */

    TBool    iClientBinary; ///< RFC 856  (Client Sending in Binary)

	/** If ETrue, the server is echoing data back to the client (RFC 857). */

    TBool    iEcho;         ///< RFC 857  (Server Echoing Data from Client)

	/** If ETrue, the client will negotiate about window size (RFC 1073). */

    TBool    iNAWS;         ///< RFC 1073 (Client Providing Window Size Information)

	/** If ETrue, the terminal speed option is enabled (RFC 1079). */

    TBool    iTerminalSpeed;///< RFC 1079 (Client Providing Terminal Speed Information)

	/** If ETrue, the client is providing terminal type information (RFC 1091). */

    TBool    iTerminalType; ///< RFC 1091 (Client Providing Terminal Type Information)

	/** If ETrue, if the server is providing status information (RFC 859). */

    TBool    iServerStatus; ///< RFC 859  (Server Providing Status Information)

	/** If ETrue, if the client is providing status information (RFC 859). */

    TBool    iClientStatus; ///< RFC 859  (Client Providing Status Information)

    }TOptionStatus;

// Used by client to configure the Symbian Telnet

class TTelnetConfig

/**

* Specifies telnet session configuration information.

* 

* The client must provide a reference to an instance of this class as a parameter 

* to the CTelnetSession::NewL() function. 

* 

* Configuration options can be modified, when the session is in progress, using 

* the CTelnetSession::DoModifyConfig() function. 

* 

* Configuration option state can be obtained using the CTelnetSession::OptionStatus() 

* function.

* @publishedAll

* @released 

*/

    {

 public:

	/** Constructor. */

	 TTelnetConfig() {

		              iAllowLogout = TRUE;        // RFC 727  - Default TRUE = Server Can Logout Client

					  iWindowSize.x = (TInt16)80; // RFC 1073 - Default 80 x 24

					  iWindowSize.y = (TInt16)24;

					  iTermSpeed = _L8("38400");  // RFC 1079 - Default to 38400 Baud Terminal

					  iTermType  = _L8("dumb");   // RFC 1091 - Default to base NVT Terminal

					}

	/** Destructor. */

	 ~TTelnetConfig(){}

	typedef struct

		/** 

		* Specifies the client's window size.

		* 

		* The default is 80 columns by 24 rows which constructs to x=80, y=24. 

		*/

		{

		/** The client window's width (number of columns). */

		TInt16 x;

		/** The client window's height (number of rows). */

		TInt16 y;

		}TWindowSize;

	/** 

	* Specifies the client's window size.

	* 

	* The default is 80 columns by 24 rows. 

	* 

	* (RFC 1073 -- Set to Configure Window Size) 

	*/

	TWindowSize	iWindowSize; 

	/**

	* Specifies the speed of the telnet connection.

	* 

	* The default is "38400" (in ASCII characters). Must be set to a server-supported rate.

	* 

	* (RFC 1079 -- Set to Configure Terminal Speed) 

	*/

	TBuf8<20>	iTermSpeed;  

	/**

	* Specifies the terminal type.

	* 

	* The default is "dumb" (in ASCII characters). 

	* 

	* (RFC 1091 -- Set to Configure Terminal Type) 

	*/

	TBuf8<20>	iTermType;

	/**

	* Specifies whether the telnet server can logout the client.

	* 

	* The default, ETrue, enables the server to logout the client. If EFalse any 

	* logout request from the telnet server is rejected by the client.

	*

	* (RFC 727 -- Set/Clear to Enable/Disable Server Logout) 

	*/

	TBool		iAllowLogout;

	/**

	* Enables or disables telnet server echo to client.

	* 

	* The default, ETrue, enables server echo. Note that although this is normal 

	* telnet server behaviour, it is not a formal telnet requirement. It is therefore 

	* recommended that the client implement an optional local echo. 

	*

	* (RFC 857 -- Set/Clear to Enable/Disable Server Echo to client) 

	*/

	TBool		iServerEcho;

    };

// Client can pass these in overloaded CTelnetSession::Write(TTelnetUserControl& aControlCode);

/**

* Specifies the telnet control code to send to the server.

*

* This is done using the overloaded CTelnetSession::Write() function.

* @publishedAll

* @released 

*/

enum TTelnetUserControl 

    {

	/** Control code not supported. */

    ENotSupported = 0,

	/**

	* Break (the NVT 129th ASCII break code).

	* The default is 243. This is not a valid control in Binary mode. 

	*/

    EBrk	= 243,

	/**

	* Interupt Process.

	* The default is 244.

	*/

    EIp		= 244,

	/** 

	* Abort Output.

	* The default is 245. 

	*/

    EAo		= 245,

	/**

	Are you there?

	* The default is 246. 

	*/

    EAyt	= 246,

	/**

	* Erase Character. 

	* The default is 247. This is not a valid control in Binary mode. 

	*/

    EEc		= 247,

	/** 

	* Erase Line.

	* The default is 248. This is not a valid control in Binary mode. 

	*/

    EEl		= 248,

    };

// Client MUST override this class

// Client MUST provide a pointer to an instance of this class as a parameter to CTelnetSession::NewL()

class MTelnetNotification

/**

* Symbian telnet notification interface.

* 

* Informs the client when an error occurs, when reads and writes have completed, 

* when a connection is made or closed and when configuration options change.

* @publishedAll

* @released 

*/

    {

 public:

	/** 

	* Reports errors on the Telnet connection.

	*

	* The error code is supplied by the server. If this function is called, it is 

	* likely that the connection has failed. Therefore it is recommended that the 

	* client disconnects and resets its state.

	* 

	* @param aError	Error code from server. 

	 */

    virtual void Error(TInt aError) = 0; ///< Miscellaneous Error callback

	/** 

	* Passes the data that was received from the server to the client.

	* 

	* It is recommended that the client copies the data from this buffer, as it 

	* is owned by the Symbian telnet.

	* 

	* @param aBuffer	Data received from server. 

	*/

    virtual void ReadComplete(const TDesC8& aBuffer) = 0; ///< Last Read to Server completion callback

	/** Notifies the client that a write to the server from the client has completed. */

    virtual void WriteComplete() = 0; ///< Last Write to Server completion callback

	/** Notifies the client that the connection to the server has been closed. */

    virtual void ConnectionClosed() = 0; ///< Telnet Connection Closed callback

	/** Notifies the client that a connection to the server has been made. */

    virtual void Connected() = 0; ///< Telnet Connected callback

	/** Notifies the client that telnet configuration options have changed. */

    virtual void OptionsChanged() = 0;                    ///< Telnet RFC Options Changed callback

    };

class CTelnetControl;

class CTelnetSession : public CBase

/**

* The main Symbian telnet class.

* 

* Consists of a connection interface and a protocol interface. The connection 

* interface comprises member functions that: connect to, read from, write to 

* and disconnect from a telnet server.

* 

* The protocol interface includes member functions that get and set telnet configuration.

*

* @publishedAll

* @released 

*/

    {

    //public:

    // Data Structures

 public:

    ~CTelnetSession();

    // Construction

    // Need to add max buffer size to constructor [check]

    IMPORT_C static CTelnetSession* NewL(const TTelnetConfig& aConfig,const MTelnetNotification* aNotifier);

 protected:

    IMPORT_C void ConstructL(const TTelnetConfig& aConfig,const MTelnetNotification* aNotifier);

    //

    // Connection Interface

    //

 public:

    IMPORT_C TInt Connect(const TInetAddr& aNetAddr); ///< Connects to aNetAddr on the standard telnet port (port 23)

    IMPORT_C TInt Connect(const TInetAddr& aNetAddr, TUint aPort); ///< Connects to aNetAddr on user specified port

    IMPORT_C TInt Connect(const TDesC& aServerName); ///< Connects to aSeverName on the standard telnet port (port 23)

    IMPORT_C TInt Connect(const TDesC& aServerName, TUint aPort); ///< Connects to aServerName on user specified port

    IMPORT_C TInt Disconnect(); ///< Disconnects current connection 

    IMPORT_C TInt Write(const TDesC8& aBuffer); ///< Writes a byte stream over the open telnet connection.

    IMPORT_C TInt Write(TTelnetUserControl& aControlCode); ///< Writes NVT code to stream. Prepends \<IAC\> code (255)

    IMPORT_C TInt Read(); ///< Read data received over telnet buffer.

	//

	// Protocol Interface 

	//

	IMPORT_C TInt DoForceLogout();

	IMPORT_C TInt DoModifyConfig(TTelnetConfig& aConfig);

	IMPORT_C TInt OptionStatus(TOptionStatus& aStatus);

 private:

    CTelnetSession();

 private:

    MTelnetNotification* iNotifier;

    CTelnetControl* iTelnetProtocol;

    };

#endif // _TELNETPROTOCOLAPI_H_