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
|
<!--plsfield:text-->
<HTML><HEAD>
<TITLE>C API Reference -- Ns_SockCallback</TITLE>
<LINK rel=Previous href="c-ch359.htm">
<LINK rel=ToC href="toc.htm">
<LINK rel=Index href="master.htm">
<LINK rel=Next href="c-ch361.htm">
</HEAD><BODY BGCOLOR="#ffffff"><A NAME="topofpage"></A>
<TABLE WIDTH=100%>
<TR>
<TD ALIGN=LEFT>
<A NAME="topofpage"></A> <IMG SRC="as-c-sm.gif">
</TD>
<TD ALIGN=RIGHT>
<A href="c-ch359.htm"><IMG BORDER="0" src=navbprev.gif alt="[ Previous ]"></A>
<A href=toc.htm> <IMG BORDER="0" src=navbhome.gif alt="[ Contents ]"></A>
<A href=master.htm> <IMG BORDER="0" src=navbhelp.gif alt="[ Index ]"></A>
<A href="c-ch361.htm"> <IMG BORDER="0" src=navbnext.gif alt="[ Next ]"></A>
<A name="7983"> </A>
</TD>
</TR>
</TABLE>
<a name="305084">
</a><h3>Ns_SockCallback</h3>
<a name="289240">
</a><h4>Overview</h4>
Register a socket callback function
<a name="289241">
</a><a name="289242">
</a><h4>Syntax</h4>
<pre> <a name="289243"></a>int Ns_SockCallback (
<a name="289244"></a>SOCKET sock,
<a name="289245"></a>Ns_SockProc *proc,
<a name="289246"></a>void *ctx,
<a name="289247"></a>int when
<a name="289248"></a>);
</pre><p><a name="289249">
</a><h4>Description</h4>
<p><a name="289250">
</a>Ns_SockCallback registers a user-defined socket callback function and should be called by your module at startup time. You must create a listening TCP socket (named <code>sock</code>). The <code>ctx</code> argument is your context which will be passed back as the second argument of your callback function.</p>
<p><a name="624809">
</a>The <code>when</code> argument is a bitmask with one or more of the following options specified:<Table Border = "3">
<tr><td><p><a name="624794">
</a>NS_SOCK_READ:</p>
<td><p><a name="624796">
</a> the socket is readable</p>
<tr><td><p><a name="624798">
</a>NS_SOCK_WRITE:</p>
<td><p><a name="624800">
</a> the socket is writeable</p>
<tr><td><p><a name="624802">
</a>NS_SOCK_EXCEPTION:</p>
<td><p><a name="624804">
</a> the socket has an exceptional condition</p>
<tr><td><p><a name="624806">
</a>NS_SOCK_EXIT: </p>
<td><p><a name="624808">
</a>the server is shutting down</p>
</Table></p>
<p><a name="289251">
</a>The <code>proc</code> is your socket callback function in the following format: </p>
<pre> <a name="620999"></a>typedef int (Ns_SockProc) (int sock, void *arg, int why);
</pre><p><p><a name="289269">
</a>The sock will be a readable, writable socket. The arg is the ctx you passed to Ns_SockCallback. The why argument is the when you passed to Ns_SockCallback.</p>
<p><a name="289273">
</a>At startup time, AOLserver creates a single socket service thread dedicated to handling socket callbacks. Since several sockets are needed to listen for connection requests, and because connection requests are handled so quickly, all the socket drivers share a single thread for that purpose.</p>
<a name="289278">
</a><h4>Examples</h4>
<ol>
<li>Create a C callback function to handle a request. The callback function must execute without blocking so that other sockets can get serviced. Typically, the callback function just performs an accept() call and queues the request. The prototype is:
<a name="289279">
</a><p>
<pre> <a name="289280"></a>typedef int (Ns_SockProc) (SOCKET sock, void *context, int
why);
</pre><p><dl>
<dt>The parameters are:<Table Border = "3">
<tr><td><p><a name="289283">
</a><code>sock</code></p>
<td><p><a name="289285">
</a>the registered socket</p>
<tr><td><p><a name="289287">
</a><code>context</code></p>
<td><p><a name="289289">
</a>your context passed to Ns_SockCallback()</p>
<tr><td><p><a name="289291">
</a><code>why</code></p>
<td><p><a name="289293">
</a>the reason the function was called, which is one of the following:</p>
<p><a name="289294">
</a>NS_SOCK_READ: the socket is readable</p>
<p><a name="289295">
</a>NS_SOCK_WRITE: the socket is writeable</p>
<p><a name="289296">
</a>NS_SOCK_EXCEPTION: the socket has an exceptional condition</p>
<p><a name="289297">
</a>NS_SOCK_EXIT: the server is shutting down</p>
</Table><a name="289298">
</a>
<p><dt>The callback function must return either NS_TRUE to tell the socket thread to keep watching the socket or NS_FALSE to tell the socket thread to stop watching the socket. <a name="289299">
</a>
<p><dt>For example:<a name="289300">
</a>
<p></dl>
<pre> <a name="289301"></a>int
<a name="289302"></a>MySock(SOCKET sock, void *context, int why)
<a name="289303"></a>{
<a name="289304"></a> if (why == NS_SOCK_READ) {
<a name="289305"></a> .. handle read ..
<a name="289306"></a> if (error) {
<a name="289307"></a> return NS_FALSE;
<a name="289308"></a> } else {
<a name="289309"></a> return NS_TRUE;
<a name="289310"></a> }
<a name="289311"></a> } else if (why == NS_SOCK_EXIT) {
<a name="289312"></a> .. free(context) ..
<a name="289313"></a> return NS_FALSE;
<a name="289314"></a> }
<a name="289315"></a>}
</pre><p><li>At server startup time, your module must register your callback function with the server using the Ns_SockCallback() function.
<a name="289316">
</a><p>
<dl>
<dt>This example specifies that MySock will be called when the socket is readable or when the server is shutting down:<a name="289317">
</a>
<p></dl>
<pre> <a name="289318"></a>Ns_SockCallback(sock, MySock, myCtx,
<a name="289319"></a> NS_SOCK_READ | NS_SOCK_EXIT);
</pre><p><dl>
<dt>Remember that there is only one socket service thread, so your callback function must return immediately without blocking!<a name="289320">
</a>
<p></dl>
</ol>
<TABLE BORDER="2" CELLPADDING="1" width="100%">
<TR><TD COLSPAN=3><P ALIGN=Center>
<IMG SRC="bluebult.gif">
<A HREF="#topofpage">
<FONT SIZE=-1>Top of Page</FONT></A>
<IMG SRC="bluebult.gif">
</TD></TR>
<TR><TD COLSPAN=3><P ALIGN=Center>
<A href="c-ch359.htm">
<IMG BORDER="0" src=navbprev.gif alt="[ Previous ]"></A>
<A href=toc.htm>
<IMG BORDER="0" src=navbhome.gif alt="[ Contents ]"></A>
<A href=master.htm>
<IMG BORDER="0" src=navbhelp.gif alt="[ Index ]"></A>
<A href="c-ch361.htm">
<IMG BORDER="0" src=navbnext.gif alt="[ Next ]"></A>
<BR align=center>
<FONT size=-1>Copyright © 1998-99 America Online,
Inc.</FONT>
</TD></TR></TABLE></BODY></HTML><!--plsfield:end-->
|
