|
1 File : README.TXT |
|
2 Author : Robert Cripps for Symbian Ltd May 1999 |
|
3 (c) Copyright Symbian Ltd 1998 |
|
4 Abstract : Overview of the design of the Symbian Telnet implementation |
|
5 and miscellaneous handover notes for BETA Release 1.0 |
|
6 |
|
7 1) Overall Structure |
|
8 The Symbian Telnet (Telsess.dll) export entry points are declared in telsess.h |
|
9 and described in TelApi.Doc .There is a basic sample Telnet Client TTelnet.exe |
|
10 with Source code that demonstrates most of the API calls. |
|
11 |
|
12 2) Class Overview |
|
13 2.1) CTelnetSession |
|
14 Main derivation from CBase |
|
15 Top level class created by client applications. |
|
16 Creates the CTelnetControl control object and contains the export entry |
|
17 points for client applications. |
|
18 |
|
19 2.2) CTelnetControl |
|
20 Main derivation from CBase |
|
21 Created by CTelnetSession. |
|
22 The main Symbian Telnet control object handles client calls/callbacks and |
|
23 generally coordinates Symbian Telnet operation. |
|
24 Creates instances of :- |
|
25 |
|
26 CTelnetResolver |
|
27 CProto |
|
28 CIOBufferControl |
|
29 CActiveWriter |
|
30 CActiveReader |
|
31 |
|
32 2.3) CTelnetResolver |
|
33 Main derivation from CActive |
|
34 Handles connection/disconnection to Telnet Server using state machine |
|
35 Owns the Socket handle |
|
36 |
|
37 2.4) CActiveWriter |
|
38 Main derivation from CActive |
|
39 Handles Writes to the Socket |
|
40 |
|
41 2.5) CActiveReader |
|
42 Main derivation from CActive |
|
43 Handles Reads from the Socket |
|
44 |
|
45 2.6) CIOBufferControl |
|
46 Main derivation from CBase |
|
47 Provides buffering between the ActiveRead/Write objects and the |
|
48 CTelnetControl control object. |
|
49 |
|
50 2.7) CProto |
|
51 Main derivation from CBase |
|
52 The Telnet Protocol handler coordinates RFC 854 |
|
53 Manipulates data stream to and from the Telnet Server. |
|
54 ALL calls into this object are effectively synchronous. |
|
55 Contains the main Server receive state machine. |
|
56 |
|
57 Creates instances of :- |
|
58 |
|
59 CBinaryOption RFC 856 |
|
60 CWindowSizeOption RFC 1073 |
|
61 CTerminalTypeOption RFC 1091 |
|
62 CTerminalSpeedOption RFC 1079 |
|
63 CSuppressGAOption RFC 858 |
|
64 CStatusOption RFC 859 |
|
65 CEchoOption RFC 857 |
|
66 CLogoutOption RFC 727 |
|
67 CUnknownOption |
|
68 |
|
69 The above RFC classes are derived from CRFCOptionBase which conatins an |
|
70 option negotiation state machine as described in RFC 1143 |
|
71 |
|
72 3) Creation Heirarchy |
|
73 CTelnetSession |
|
74 | |
|
75 | |
|
76 CTelnetControl |
|
77 | |
|
78 |--------------|---------------|--------------|----------------| |
|
79 | | | | | |
|
80 | | | | | |
|
81 CActiveReader CActiveWriter CProto CTelnetResolver CIOBufferControl |
|
82 | |
|
83 | |
|
84 CBinaryOption |
|
85 CWindowSizeOption |
|
86 CTerminalTypeOption |
|
87 CTerminalSpeedOption |
|
88 CSuppressGAOption |
|
89 CStatusOption |
|
90 CEchoOption |
|
91 CLogoutOption |
|
92 CUnknownOption |
|
93 |
|
94 4) File Overview |
|
95 4.1) Telsess.cpp & Telsess.h |
|
96 Symbian Telnet DLL export methods |
|
97 |
|
98 4.2) Telcontrol.cpp & Telcontrol |
|
99 Code & declarations for the Symbian Telnet control class CTelnetControl |
|
100 |
|
101 4.3) Telfsm.cpp & Telfsm.h |
|
102 Implementation of all the Telnet RFC's |
|
103 |
|
104 4.4) Telresol.cpp & Telresol.h |
|
105 Code & declarations for the Symbian Telnet Resolver class CTelnetResolver |
|
106 |
|
107 4.5) IOBuffers.cpp & IOBuffers.h |
|
108 Code & declarations for the intermmediate buffering class CIOBufferControl |
|
109 |
|
110 4.6) ActiveIO.cpp & ActiveIO.h |
|
111 Code & declarations for the Socket write and Socket read Active Objects |
|
112 CActiveReader, CActiveWriter |
|
113 |
|
114 |
|
115 |
|
116 5) Connect/Disconnect overview |
|
117 Data paths travelling from Server to the Client contain notification |
|
118 (M)Interface callbacks. |
|
119 |
|
120 5.1) Connect to Server |
|
121 |
|
122 Telnet Client Telnet Client |
|
123 | ^ |
|
124 | | |
|
125 CTelnetSession::Connect (M) CTelnetSession::Connected |
|
126 | | |
|
127 | | |
|
128 CTelnetControl::Connect (M) CTelnetControl::ResolverConnected |
|
129 | | |
|
130 | | |
|
131 CTelnetResolver::IssueConnect CTelnetResolver Async Completion |
|
132 | | |
|
133 V | |
|
134 -------Telnet Server------| |
|
135 |
|
136 5.2) Disconnect by Server |
|
137 |
|
138 Telnet Server |
|
139 | |
|
140 | |
|
141 CTelnetResolver notified of EOF on Socket by CActiveReader |
|
142 | |
|
143 | |
|
144 (M) CTelnetControl::ResolverDisconnected |
|
145 | |
|
146 | |
|
147 (M) CTelnetSession::ConnectionClosed |
|
148 | |
|
149 V |
|
150 Telnet Client |
|
151 |
|
152 |
|
153 5.3) Disconnect by Client |
|
154 |
|
155 |
|
156 Telnet Client Telnet Client |
|
157 | ^ |
|
158 | | |
|
159 CTelnetSession::Disconnect (M) CTelnetSession::ConnectionClosed |
|
160 | | |
|
161 | | |
|
162 CTelnetControl::Disconnect (M) CTelnetControl::ResolverDisconnected |
|
163 | | |
|
164 | | |
|
165 CTelnetResolver::IssueDisconnect CTelnetResolver notified of EOF on Socket |
|
166 | | |
|
167 V | |
|
168 -------Telnet Server------| |
|
169 |
|
170 |
|
171 6) Data Transfer |
|
172 Data paths travelling from Server to the Client contain notification |
|
173 (M)Interface callbacks. |
|
174 6.1) Write to Server |
|
175 |
|
176 Telnet Client Telnet Client |
|
177 | ^ |
|
178 | | |
|
179 CTelnetSession::Write (M) CTelnetSession::WriteComplete |
|
180 | ^ |
|
181 | | |
|
182 CTelnetControl::Write --> (M) CTelnetControl::WriteComplete |
|
183 | ^ | | |
|
184 V | | | |
|
185 CProto::ProtoWrite | | |
|
186 | | |
|
187 | | |
|
188 |---------------| | |
|
189 | | |
|
190 CIOBufferControl::Write (M) CIOBufferControl::WriteComplete |
|
191 | | |
|
192 | | |
|
193 CActiveWriter::IssueWrite CActiveWriter Completes Asynchronously |
|
194 | | |
|
195 V | |
|
196 ------Telnet Server------| |
|
197 |
|
198 |
|
199 |
|
200 6.2) Read from Server |
|
201 |
|
202 Telnet Client Telnet Client |
|
203 | ^ |
|
204 | | |
|
205 CTelnetSession::Read (M) CTelnetSession::ReadComplete |
|
206 | | |
|
207 | | |
|
208 | CProto::ProtoRead--->| | |
|
209 | | | | |
|
210 | | V | |
|
211 CTelnetSession::Read (M) CTelnetControl::ReadComplete |
|
212 | | |
|
213 | | |
|
214 CIOBufferControl::Read (M) CIOBufferControl::ReadComplete |
|
215 | | |
|
216 | | |
|
217 CActiveReader::IssueRead CActiveReader Completes Asynchronously |
|
218 | | |
|
219 V | |
|
220 ------Telnet Server------| |
|
221 |
|
222 |
|
223 7) Sample Telnet Client |
|
224 There are only 2 files in this project TTelnet.cpp and TTelnet.h . |
|
225 This code is not perfect but is fairly easy to understand. |
|
226 |
|
227 8) Miscellaneous Issues |
|
228 |
|
229 8.1) Debugs |
|
230 Debugging has been left in, mainly for Telnet Protocol events. This can be easily removed |
|
231 when it's no longer useful. |
|
232 |
|
233 8.2) Testing in Binary Mode |
|
234 Binary mode is successfully negotiated if a Terminal Type other than "dumb" is selected, |
|
235 however, we do not have a Terminal emulation to test Binary mode properly. |
|
236 I have done basic testing to make sure the permitted control signals work in Binary mode |
|
237 and have carefully desk checked the code that handles the RFC 854 defined behaviour for |
|
238 receive and transmit in Binary. |
|
239 As soon as a Terminal emulation, vt100 for example, is "plugged in" over the top of the |
|
240 Symbian Telnet API, it should be fairly easy to test that Binary mode is working correctly |
|
241 using "vi" or other Unix applications that require more complex client terminal formatting. |
|
242 |
|
243 8.3) Finishing Off |
|
244 |
|
245 i) Error Checks |
|
246 I need to "Epocise" the code for checking buffer overflows etc |
|
247 |
|
248 ii) Safe Objects |
|
249 I'm not sure whether I need to implement things like safe copy constructors. |
|
250 |
|
251 iii) Error Notifications |
|
252 I have not looked into to every single error that can occur on sockets and the resolver, |
|
253 therefore I've not documented all the error codes that could be passed up to the client. |
|
254 |
|
255 iv) Coding Standards |
|
256 Code needs to be checked against the coding standards by myself and then submitted for |
|
257 review |
|
258 |
|
259 v) Destructive Testing |
|
260 Anything I/we can think of to break it. |
|
261 |
|
262 vi) Final Documentation |
|
263 Finish off and make the API official. |
|
264 |