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.