diff -r 000000000000 -r b16258d2340f applayerprotocols/telnetengine/Documentation/README.TXT --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/applayerprotocols/telnetengine/Documentation/README.TXT Tue Feb 02 01:09:52 2010 +0200 @@ -0,0 +1,264 @@ +File : README.TXT +Author : Robert Cripps for Symbian Ltd May 1999 + (c) Copyright Symbian Ltd 1998 +Abstract : Overview of the design of the Symbian Telnet implementation + and miscellaneous handover notes for BETA Release 1.0 + +1) Overall Structure +The Symbian Telnet (Telsess.dll) export entry points are declared in telsess.h +and described in TelApi.Doc .There is a basic sample Telnet Client TTelnet.exe +with Source code that demonstrates most of the API calls. + +2) Class Overview +2.1) CTelnetSession +Main derivation from CBase +Top level class created by client applications. +Creates the CTelnetControl control object and contains the export entry +points for client applications. + +2.2) CTelnetControl +Main derivation from CBase +Created by CTelnetSession. +The main Symbian Telnet control object handles client calls/callbacks and +generally coordinates Symbian Telnet operation. +Creates instances of :- + +CTelnetResolver +CProto +CIOBufferControl +CActiveWriter +CActiveReader + +2.3) CTelnetResolver +Main derivation from CActive +Handles connection/disconnection to Telnet Server using state machine +Owns the Socket handle + +2.4) CActiveWriter +Main derivation from CActive +Handles Writes to the Socket + +2.5) CActiveReader +Main derivation from CActive +Handles Reads from the Socket + +2.6) CIOBufferControl +Main derivation from CBase +Provides buffering between the ActiveRead/Write objects and the +CTelnetControl control object. + +2.7) CProto +Main derivation from CBase +The Telnet Protocol handler coordinates RFC 854 +Manipulates data stream to and from the Telnet Server. +ALL calls into this object are effectively synchronous. +Contains the main Server receive state machine. + +Creates instances of :- + +CBinaryOption RFC 856 +CWindowSizeOption RFC 1073 +CTerminalTypeOption RFC 1091 +CTerminalSpeedOption RFC 1079 +CSuppressGAOption RFC 858 +CStatusOption RFC 859 +CEchoOption RFC 857 +CLogoutOption RFC 727 +CUnknownOption + +The above RFC classes are derived from CRFCOptionBase which conatins an +option negotiation state machine as described in RFC 1143 + +3) Creation Heirarchy + CTelnetSession + | + | + CTelnetControl + | + |--------------|---------------|--------------|----------------| + | | | | | + | | | | | + CActiveReader CActiveWriter CProto CTelnetResolver CIOBufferControl + | + | + CBinaryOption + CWindowSizeOption + CTerminalTypeOption + CTerminalSpeedOption + CSuppressGAOption + CStatusOption + CEchoOption + CLogoutOption + CUnknownOption + +4) File Overview +4.1) Telsess.cpp & Telsess.h +Symbian Telnet DLL export methods + +4.2) Telcontrol.cpp & Telcontrol +Code & declarations for the Symbian Telnet control class CTelnetControl + +4.3) Telfsm.cpp & Telfsm.h +Implementation of all the Telnet RFC's + +4.4) Telresol.cpp & Telresol.h +Code & declarations for the Symbian Telnet Resolver class CTelnetResolver + +4.5) IOBuffers.cpp & IOBuffers.h +Code & declarations for the intermmediate buffering class CIOBufferControl + +4.6) ActiveIO.cpp & ActiveIO.h +Code & declarations for the Socket write and Socket read Active Objects +CActiveReader, CActiveWriter + + + +5) Connect/Disconnect overview +Data paths travelling from Server to the Client contain notification +(M)Interface callbacks. + +5.1) Connect to Server + + Telnet Client Telnet Client + | ^ + | | + CTelnetSession::Connect (M) CTelnetSession::Connected + | | + | | + CTelnetControl::Connect (M) CTelnetControl::ResolverConnected + | | + | | + CTelnetResolver::IssueConnect CTelnetResolver Async Completion + | | + V | + -------Telnet Server------| + +5.2) Disconnect by Server + + Telnet Server + | + | + CTelnetResolver notified of EOF on Socket by CActiveReader + | + | + (M) CTelnetControl::ResolverDisconnected + | + | + (M) CTelnetSession::ConnectionClosed + | + V + Telnet Client + + +5.3) Disconnect by Client + + + Telnet Client Telnet Client + | ^ + | | + CTelnetSession::Disconnect (M) CTelnetSession::ConnectionClosed + | | + | | + CTelnetControl::Disconnect (M) CTelnetControl::ResolverDisconnected + | | + | | + CTelnetResolver::IssueDisconnect CTelnetResolver notified of EOF on Socket + | | + V | + -------Telnet Server------| + + +6) Data Transfer +Data paths travelling from Server to the Client contain notification +(M)Interface callbacks. +6.1) Write to Server + + Telnet Client Telnet Client + | ^ + | | + CTelnetSession::Write (M) CTelnetSession::WriteComplete + | ^ + | | + CTelnetControl::Write --> (M) CTelnetControl::WriteComplete + | ^ | | + V | | | + CProto::ProtoWrite | | + | | + | | + |---------------| | + | | + CIOBufferControl::Write (M) CIOBufferControl::WriteComplete + | | + | | + CActiveWriter::IssueWrite CActiveWriter Completes Asynchronously + | | + V | + ------Telnet Server------| + + + +6.2) Read from Server + + Telnet Client Telnet Client + | ^ + | | + CTelnetSession::Read (M) CTelnetSession::ReadComplete + | | + | | + | CProto::ProtoRead--->| | + | | | | + | | V | + CTelnetSession::Read (M) CTelnetControl::ReadComplete + | | + | | + CIOBufferControl::Read (M) CIOBufferControl::ReadComplete + | | + | | + CActiveReader::IssueRead CActiveReader Completes Asynchronously + | | + V | + ------Telnet Server------| + + +7) Sample Telnet Client +There are only 2 files in this project TTelnet.cpp and TTelnet.h . +This code is not perfect but is fairly easy to understand. + +8) Miscellaneous Issues + +8.1) Debugs +Debugging has been left in, mainly for Telnet Protocol events. This can be easily removed +when it's no longer useful. + +8.2) Testing in Binary Mode +Binary mode is successfully negotiated if a Terminal Type other than "dumb" is selected, +however, we do not have a Terminal emulation to test Binary mode properly. +I have done basic testing to make sure the permitted control signals work in Binary mode +and have carefully desk checked the code that handles the RFC 854 defined behaviour for +receive and transmit in Binary. +As soon as a Terminal emulation, vt100 for example, is "plugged in" over the top of the +Symbian Telnet API, it should be fairly easy to test that Binary mode is working correctly +using "vi" or other Unix applications that require more complex client terminal formatting. + +8.3) Finishing Off + +i) Error Checks +I need to "Epocise" the code for checking buffer overflows etc + +ii) Safe Objects +I'm not sure whether I need to implement things like safe copy constructors. + +iii) Error Notifications +I have not looked into to every single error that can occur on sockets and the resolver, +therefore I've not documented all the error codes that could be passed up to the client. + +iv) Coding Standards +Code needs to be checked against the coding standards by myself and then submitted for +review + +v) Destructive Testing +Anything I/we can think of to break it. + +vi) Final Documentation +Finish off and make the API official. +