1.1 --- a/epoc32/include/telsess.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/telsess.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,314 @@
1.4 -telsess.h
1.5 +/**
1.6 +* Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description:
1.19 +* Telnet Session API
1.20 +*
1.21 +*
1.22 +*/
1.23 +
1.24 +
1.25 +
1.26 +
1.27 +
1.28 +/**
1.29 + @file TELSESS.H
1.30 +*/
1.31 +
1.32 +#ifndef _TELSESS_H_
1.33 +#define _TELSESS_H_
1.34 +
1.35 +#include <in_sock.h>
1.36 +#include <e32std.h>
1.37 +#include <e32cons.h>
1.38 +#include <f32file.h>
1.39 +
1.40 +#define __TELNETSESSDEBUG__ // Put in Debug mode
1.41 +
1.42 +class CTelnetControl;
1.43 +
1.44 +// Used by client to retrieve RFC option state
1.45 +// Flags for Telnet negotiated options
1.46 +// 1 = Enabled 0 = Disabled
1.47 +
1.48 +/**
1.49 +Defines the supported, RFC-defined, option status.
1.50 +
1.51 +@publishedAll
1.52 +@released
1.53 +*/
1.54 +typedef struct
1.55 + {
1.56 + /** If ETrue, the server is sending in binary (RFC 856). */
1.57 + TBool iServerBinary; ///< RFC 856 (Server Sending in Binary)
1.58 + /** If ETrue, the client is sending in binary (RFC 856). */
1.59 + TBool iClientBinary; ///< RFC 856 (Client Sending in Binary)
1.60 + /** If ETrue, the server is echoing data back to the client (RFC 857). */
1.61 + TBool iEcho; ///< RFC 857 (Server Echoing Data from Client)
1.62 + /** If ETrue, the client will negotiate about window size (RFC 1073). */
1.63 + TBool iNAWS; ///< RFC 1073 (Client Providing Window Size Information)
1.64 + /** If ETrue, the terminal speed option is enabled (RFC 1079). */
1.65 + TBool iTerminalSpeed;///< RFC 1079 (Client Providing Terminal Speed Information)
1.66 + /** If ETrue, the client is providing terminal type information (RFC 1091). */
1.67 + TBool iTerminalType; ///< RFC 1091 (Client Providing Terminal Type Information)
1.68 + /** If ETrue, if the server is providing status information (RFC 859). */
1.69 + TBool iServerStatus; ///< RFC 859 (Server Providing Status Information)
1.70 + /** If ETrue, if the client is providing status information (RFC 859). */
1.71 + TBool iClientStatus; ///< RFC 859 (Client Providing Status Information)
1.72 + }TOptionStatus;
1.73 +
1.74 +// Used by client to configure the Symbian Telnet
1.75 +class TTelnetConfig
1.76 +/**
1.77 +* Specifies telnet session configuration information.
1.78 +*
1.79 +* The client must provide a reference to an instance of this class as a parameter
1.80 +* to the CTelnetSession::NewL() function.
1.81 +*
1.82 +* Configuration options can be modified, when the session is in progress, using
1.83 +* the CTelnetSession::DoModifyConfig() function.
1.84 +*
1.85 +* Configuration option state can be obtained using the CTelnetSession::OptionStatus()
1.86 +* function.
1.87 +* @publishedAll
1.88 +* @released
1.89 +*/
1.90 + {
1.91 + public:
1.92 +
1.93 + /** Constructor. */
1.94 + TTelnetConfig() {
1.95 + iAllowLogout = TRUE; // RFC 727 - Default TRUE = Server Can Logout Client
1.96 + iWindowSize.x = (TInt16)80; // RFC 1073 - Default 80 x 24
1.97 + iWindowSize.y = (TInt16)24;
1.98 + iTermSpeed = _L8("38400"); // RFC 1079 - Default to 38400 Baud Terminal
1.99 + iTermType = _L8("dumb"); // RFC 1091 - Default to base NVT Terminal
1.100 + }
1.101 + /** Destructor. */
1.102 + ~TTelnetConfig(){}
1.103 +
1.104 + typedef struct
1.105 + /**
1.106 + * Specifies the client's window size.
1.107 + *
1.108 + * The default is 80 columns by 24 rows which constructs to x=80, y=24.
1.109 + */
1.110 + {
1.111 + /** The client window's width (number of columns). */
1.112 + TInt16 x;
1.113 + /** The client window's height (number of rows). */
1.114 + TInt16 y;
1.115 + }TWindowSize;
1.116 +
1.117 + /**
1.118 + * Specifies the client's window size.
1.119 + *
1.120 + * The default is 80 columns by 24 rows.
1.121 + *
1.122 + * (RFC 1073 -- Set to Configure Window Size)
1.123 + */
1.124 + TWindowSize iWindowSize;
1.125 +
1.126 + /**
1.127 + * Specifies the speed of the telnet connection.
1.128 + *
1.129 + * The default is "38400" (in ASCII characters). Must be set to a server-supported rate.
1.130 + *
1.131 + * (RFC 1079 -- Set to Configure Terminal Speed)
1.132 + */
1.133 + TBuf8<20> iTermSpeed;
1.134 +
1.135 + /**
1.136 + * Specifies the terminal type.
1.137 + *
1.138 + * The default is "dumb" (in ASCII characters).
1.139 + *
1.140 + * (RFC 1091 -- Set to Configure Terminal Type)
1.141 + */
1.142 + TBuf8<20> iTermType;
1.143 +
1.144 + /**
1.145 + * Specifies whether the telnet server can logout the client.
1.146 + *
1.147 + * The default, ETrue, enables the server to logout the client. If EFalse any
1.148 + * logout request from the telnet server is rejected by the client.
1.149 + *
1.150 + * (RFC 727 -- Set/Clear to Enable/Disable Server Logout)
1.151 + */
1.152 + TBool iAllowLogout;
1.153 +
1.154 + /**
1.155 + * Enables or disables telnet server echo to client.
1.156 + *
1.157 + * The default, ETrue, enables server echo. Note that although this is normal
1.158 + * telnet server behaviour, it is not a formal telnet requirement. It is therefore
1.159 + * recommended that the client implement an optional local echo.
1.160 + *
1.161 + * (RFC 857 -- Set/Clear to Enable/Disable Server Echo to client)
1.162 + */
1.163 + TBool iServerEcho;
1.164 + };
1.165 +
1.166 +// Client can pass these in overloaded CTelnetSession::Write(TTelnetUserControl& aControlCode);
1.167 +
1.168 +/**
1.169 +* Specifies the telnet control code to send to the server.
1.170 +*
1.171 +* This is done using the overloaded CTelnetSession::Write() function.
1.172 +* @publishedAll
1.173 +* @released
1.174 +*/
1.175 +enum TTelnetUserControl
1.176 + {
1.177 + /** Control code not supported. */
1.178 + ENotSupported = 0,
1.179 +
1.180 + /**
1.181 + * Break (the NVT 129th ASCII break code).
1.182 + * The default is 243. This is not a valid control in Binary mode.
1.183 + */
1.184 + EBrk = 243,
1.185 +
1.186 + /**
1.187 + * Interupt Process.
1.188 + * The default is 244.
1.189 + */
1.190 + EIp = 244,
1.191 +
1.192 + /**
1.193 + * Abort Output.
1.194 + * The default is 245.
1.195 + */
1.196 + EAo = 245,
1.197 +
1.198 + /**
1.199 + Are you there?
1.200 + * The default is 246.
1.201 + */
1.202 + EAyt = 246,
1.203 +
1.204 + /**
1.205 + * Erase Character.
1.206 + * The default is 247. This is not a valid control in Binary mode.
1.207 + */
1.208 + EEc = 247,
1.209 +
1.210 + /**
1.211 + * Erase Line.
1.212 + * The default is 248. This is not a valid control in Binary mode.
1.213 + */
1.214 + EEl = 248,
1.215 + };
1.216 +
1.217 +// Client MUST override this class
1.218 +// Client MUST provide a pointer to an instance of this class as a parameter to CTelnetSession::NewL()
1.219 +class MTelnetNotification
1.220 +/**
1.221 +* Symbian telnet notification interface.
1.222 +*
1.223 +* Informs the client when an error occurs, when reads and writes have completed,
1.224 +* when a connection is made or closed and when configuration options change.
1.225 +* @publishedAll
1.226 +* @released
1.227 +*/
1.228 + {
1.229 + public:
1.230 + /**
1.231 + * Reports errors on the Telnet connection.
1.232 + *
1.233 + * The error code is supplied by the server. If this function is called, it is
1.234 + * likely that the connection has failed. Therefore it is recommended that the
1.235 + * client disconnects and resets its state.
1.236 + *
1.237 + * @param aError Error code from server.
1.238 + */
1.239 + virtual void Error(TInt aError) = 0; ///< Miscellaneous Error callback
1.240 +
1.241 + /**
1.242 + * Passes the data that was received from the server to the client.
1.243 + *
1.244 + * It is recommended that the client copies the data from this buffer, as it
1.245 + * is owned by the Symbian telnet.
1.246 + *
1.247 + * @param aBuffer Data received from server.
1.248 + */
1.249 + virtual void ReadComplete(const TDesC8& aBuffer) = 0; ///< Last Read to Server completion callback
1.250 +
1.251 + /** Notifies the client that a write to the server from the client has completed. */
1.252 + virtual void WriteComplete() = 0; ///< Last Write to Server completion callback
1.253 +
1.254 + /** Notifies the client that the connection to the server has been closed. */
1.255 + virtual void ConnectionClosed() = 0; ///< Telnet Connection Closed callback
1.256 +
1.257 + /** Notifies the client that a connection to the server has been made. */
1.258 + virtual void Connected() = 0; ///< Telnet Connected callback
1.259 +
1.260 + /** Notifies the client that telnet configuration options have changed. */
1.261 + virtual void OptionsChanged() = 0; ///< Telnet RFC Options Changed callback
1.262 + };
1.263 +
1.264 +class CTelnetControl;
1.265 +
1.266 +class CTelnetSession : public CBase
1.267 +/**
1.268 +* The main Symbian telnet class.
1.269 +*
1.270 +* Consists of a connection interface and a protocol interface. The connection
1.271 +* interface comprises member functions that: connect to, read from, write to
1.272 +* and disconnect from a telnet server.
1.273 +*
1.274 +* The protocol interface includes member functions that get and set telnet configuration.
1.275 +*
1.276 +* @publishedAll
1.277 +* @released
1.278 +*/
1.279 + {
1.280 + //public:
1.281 + // Data Structures
1.282 + public:
1.283 + ~CTelnetSession();
1.284 + // Construction
1.285 + // Need to add max buffer size to constructor [check]
1.286 + IMPORT_C static CTelnetSession* NewL(const TTelnetConfig& aConfig,const MTelnetNotification* aNotifier);
1.287 + protected:
1.288 + IMPORT_C void ConstructL(const TTelnetConfig& aConfig,const MTelnetNotification* aNotifier);
1.289 + //
1.290 + // Connection Interface
1.291 + //
1.292 + public:
1.293 + IMPORT_C TInt Connect(const TInetAddr& aNetAddr); ///< Connects to aNetAddr on the standard telnet port (port 23)
1.294 + IMPORT_C TInt Connect(const TInetAddr& aNetAddr, TUint aPort); ///< Connects to aNetAddr on user specified port
1.295 + IMPORT_C TInt Connect(const TDesC& aServerName); ///< Connects to aSeverName on the standard telnet port (port 23)
1.296 + IMPORT_C TInt Connect(const TDesC& aServerName, TUint aPort); ///< Connects to aServerName on user specified port
1.297 + IMPORT_C TInt Disconnect(); ///< Disconnects current connection
1.298 + IMPORT_C TInt Write(const TDesC8& aBuffer); ///< Writes a byte stream over the open telnet connection.
1.299 + IMPORT_C TInt Write(TTelnetUserControl& aControlCode); ///< Writes NVT code to stream. Prepends \<IAC\> code (255)
1.300 + IMPORT_C TInt Read(); ///< Read data received over telnet buffer.
1.301 +
1.302 + //
1.303 + // Protocol Interface
1.304 + //
1.305 + IMPORT_C TInt DoForceLogout();
1.306 + IMPORT_C TInt DoModifyConfig(TTelnetConfig& aConfig);
1.307 + IMPORT_C TInt OptionStatus(TOptionStatus& aStatus);
1.308 + private:
1.309 + CTelnetSession();
1.310 +
1.311 + private:
1.312 + MTelnetNotification* iNotifier;
1.313 + CTelnetControl* iTelnetProtocol;
1.314 +
1.315 + };
1.316 +
1.317 +
1.318 +#endif // _TELNETPROTOCOLAPI_H_