1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
|
<html>
<head>
<title>AOLserver</title>
</head>
<body>
<h1>Communications Driver Development Guide</h1>
<p>
<p>
$Header: /cvsroot/aolserver/aolserver.com/docs/devel/driver/com/index.html,v 1.1 2002/03/07 19:15:35 kriston Exp $
<p>
<font color=red><b>NOTICE: This document is under review for
formatting and correctness. Please check back at a later date to see
if the new version is ready to view.</b></font>
<p>
<a href=#1>Background</a>
<p>
<a href=#2>Technical Details</a>
<p>
<a href=#3>Interface</a>
<p>
<a href=#4>Communications Driver Functions</a>
<p>
<h2><a name=1>Background</a></h2>
<font color=red><b>NOTICE: This document is under review for
formatting and correctness. Please check back at a later date to see
if the new version is ready to view.</b></font>
<p>
The AOLserver is modular/extensible with respect to its basic
communications interface. This is accomplished by defining a set of
functions that the server calls for all communications operations. So,
an AOLserver communications "driver" is just a server module that
implements these special functions. The communications driver
framework is intended to support technical AOLserver users who must
create their own communications drivers to meet their customization
requirements--no matter how bizarre. Note that there are also
architecturally similar, but functionally independent "database
drivers" that we will not discuss here.
<p>
The standard AOLserver distribution includes socket, SSL, and file
communications drivers. The socket driver implements the basic
socket-based communications. The ssl driver is the same code as the
socket driver, recompiled with #ifdefs that include ssl-specific code.
In this document, we'll outline the basic communications driver
mechanism and show how these 3 communications drivers fit into the
framework. Access to AOLserver source code for existing drivers is
assumed.
<p>
<h2><a name=2>Technical Details</a></h2>
<font color=red><b>NOTICE: This document is under review for
formatting and correctness. Please check back at a later date to see
if the new version is ready to view.</b></font>
<p>
Initialization
<p>
A communications driver module identifies itself to the server by
calling Ns_RegisterDriver in its module init function. The
Ns_RegisterDriver call tells the server everything it needs to know
about the communications driver, including pointers to all special
functions via the Ns_DrvProc structure pointer that is passed in, and
a driver-specific context for future reference. The functions that are
identified via the Ns_DrvProc structure are listed and explained in
the Communications Driver Functions section.
<p>
<h2><a name=3>Interface</a></h2>
<font color=red><b>NOTICE: This document is under review for
formatting and correctness. Please check back at a later date to see
if the new version is ready to view.</b></font>
<p>
Typical calling sequence from comm driver's perspective:
<br>
1. Ns_ModuleInit
<br>
2. Start - driver initialization
<br>
3. Accept - wait for connection
<br>
4. Init - connection initialization
<br>
5. Read/Write - connection I/O occurs
<br>
6. Close
<br>
7. Free
<br>
8. goto step 3
<br>
<p>
Notes on existing drivers:
<p>
socket
<p>
Notice that the socket driver, by default, does not register the
Start, Accept, or Init functions. It makes the socket, bind, and
listen calls in its ModuleInit function, and sets up a callback which
actually does the accept and queues the connection. If, however, you
configure the nssock module via ListenThread=on (this was
undocumented), the driver will register an Accept function which will
be run in a separate thread by the server.
<p>
SSL
<p>
Unlike the socket driver, the SSL driver registers an Init
function. This is where the SSL driver does all of the
per-connection SSL session setup (see ssl_init_server() is
nssock/ssl.c). After this Init function has completed for a
connection, the SSL driver simply uses symmetric encryption in
the Read/Write routines.
<p>
file
<p>
The file module is unique in that it doesn't really talk to a
stateful peer. It simply reads and writes files. Because of
this simplicity, the file module is a good place to start when
studying communications drivers.
<p>
Driver Developer Guidelines
<p>
If feel the urge to create a new communications driver, first review
the following: For a socket-based driver, consider modifying/extending
the current socket driver to meet your needs. If modification of the
existing socket driver doesn't seem appropriate, you may be able to
reuse much existing code by adding #ifdefs to the existing socket code
to produce a new module--analogous to the SSL approach that is
currently in place. For a non-socket-based driver, you'll need to
create a new driver, modeling your code after the existing socket or
file driver. Review the Communications Driver Functions section and
the existing drivers to determine which function points you'll need to
create.
<p>
Important Files
<p>
The code that implements the framework discussed here can be found in:
<p>
<br>
* inc/nsdriver.h
<br>
* nsd/drv.c
<br>
* nsd/conn.c
<br>
* nssock/socket.c
<br>
* nsfile/file.c
<br>
<p>
<h2><a name=4>Communications Driver Functions</a></h2>
<font color=red><b>NOTICE: This document is under review for
formatting and correctness. Please check back at a later date to see
if the new version is ready to view.</b></font>
<p>
All communications driver functions that can be specified via the
Ns_DrvProc structure are listed below. Note that the actual
enumeration type for each function name (Ns_DrvId) can be derived by
prepending Ns_DrvId to each name, e.g. DrvIdName, DrvIdStart, etc.
<p>
These functions are generic, and some may not make sense for certain
drivers, so it's typically a subset that needs to be implemented for a
particular driver. If you examine how the Ns_DrvProc structure is
initialized in existing drivers, you'll notice a NULL-terminated array
of ID/functionPointer pairs, where each pair identifies an implemented
function. Mandatory functions are shown in bold.
<p>
Format of this reference: Name; Description; PreConditions;
PostConditions
<p>
Preconditions and postconditions reflect the contract that a driver
has with the server. Preconditions represent the driver developer's
assumptions before the function is called. Postconditions represent
the server's assumptions after the function has completed.
<p>
Name; Returns a (char *) that identifies the driver, e.g. "nssock",
"nsssl", "nsfile".
<p>
Start; Called at driver initialization time (not to be confused with
Init which is called when a connection is initialized); ModuleInit has
already executed; All driver initialization is complete;
<p>
Accept Called when a driver can begin accepting connections; this may
block; Start function has completed (if defined); Driver has
established a connection with peer;
<p>
Stop Called at driver shutdown time; Driver has terminated connections
with peer;
<p>
Init Called when a connection is to be initialized; A connection has
been established via Accept Per connection initialization is complete;
<p>
Read Called to read data from a peer; Server is ready to receive data;
Driver has received data from peer;
<p>
Write Called to write data to a peer; Server has data to transmit;
Driver has transmitted data to peer;
<p>
Close Called to close a connection; A connection has been established;
connection info is contained in the context; Driver has closed
connection with peer;
<p>
Free Called to close a connection and free the context; A connection
has been established; connection info is contained in the context;
<p>
Driver has closed connection and freed resources associated with the
context;
<p>
Peer Returns the (char *) identifier of the peer (IP address in the
case of socket-based drivers)
<p>
Location Returns the (char *) complete location that identifies the
driver, e;g; https://www;docs-R-us;com:81
<p>
Host Returns the (char *) hostname that identifies the driver
<p>
Port Returns the (int) port number associated with the driver
<p>
SendFd Called to send an open file File descriptor is open/valid;
<p>
Driver has transmitted entire file;
<p>
SendFile Called to send a named file (currently unused by all provided
drivers) Filename is valid/readable; Driver has transmitted entire
file;
<p>
Detach Called to support socket KEEPALIVE function; In socket driver
case: creates a new connection context that is marked as requeued;
Returns a (void *) pointer to a new connection context, or NULL if
existing context is NULL; Connection info is contained in the context,
or the context is NULL; Driver has created a new connection context to
represent the detached state;
<p>
</body>
</html>
|
