Annotation of libwww/Library/src/HTNet.html, revision 2.32
2.1 frystyk 1: <HTML>
2: <HEAD>
2.32 ! frystyk 3: <TITLE>W3C Reference Library libwww NET OBJECT</TITLE>
2.31 frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 26-Jan-1996 -->
2.1 frystyk 5: </HEAD>
6: <BODY>
2.2 frystyk 7:
2.17 frystyk 8: <H1>Asyncronous Socket Management</H1>
2.1 frystyk 9:
2.5 frystyk 10: <PRE>
11: /*
2.8 frystyk 12: ** (c) COPYRIGHT MIT 1995.
2.5 frystyk 13: ** Please first read the full copyright statement in the file COPYRIGH.
14: */
15: </PRE>
16:
2.1 frystyk 17: This module contains the routines for handling the set of active
2.2 frystyk 18: sockets currently in use by the multithreaded clients. It is an
19: internal module to the Library, the application interface is
2.15 frystyk 20: implemented in the <A HREF="HTEvntrg.html">Event Module</A>. Look for
2.2 frystyk 21: more information in the <A
2.17 frystyk 22: HREF="http://www.w3.org/pub/WWW/Library/User/Architecture/">
2.2 frystyk 23: Multithread Specifications</A>. <P>
2.1 frystyk 24:
2.17 frystyk 25: This module is implemented by <A HREF="HTNet.c">HTNet.c</A>, and it is
26: a part of the <A HREF="http://www.w3.org/pub/WWW/Library/">W3C
27: Reference Library</A>.
2.1 frystyk 28:
29: <PRE>
2.17 frystyk 30: #ifndef HTNET_H
31: #define HTNET_H
2.21 frystyk 32: #include "HTEvntrg.h"
2.17 frystyk 33: #include "HTReq.h"
2.1 frystyk 34: </PRE>
35:
2.17 frystyk 36: <H2>The HTNet Object</H2>
2.1 frystyk 37:
2.17 frystyk 38: The <CODE>HTNet</CODE> object is the core of the request queue
39: management. This object contains information about the socket
40: descriptor, the input read buffer etc. required to identify and
41: service a request. <P>
2.1 frystyk 42:
43: <PRE>
2.18 frystyk 44: typedef struct _HTNet HTNet;
2.1 frystyk 45: </PRE>
46:
2.24 frystyk 47: <H2>Request Call Back Functions</H2>
2.17 frystyk 48:
2.24 frystyk 49: Callback functions can be registered to be called <EM>before</EM> and
50: <EM>after</EM> a request has either been started or has
51: terminated. The following functions are the generic registration
52: mechanisms where we use lists as the basic data container. Then there
53: is two methods for binding a list of callback functions to the set
54: which is called <EM>before</EM> and to the set set which is called
55: <EM>after</EM> <P>
56:
57: In both cases there can be more than one callback function which are
2.17 frystyk 58: called on turn and each callback function can be associated with a
59: status code of the request. For example one callback function can be
60: registered for HT_LOADED, another for HT_ERROR etc.
61:
62: <H3>Register a Request Callback</H3>
2.2 frystyk 63:
2.17 frystyk 64: Register a call back function that is to be called on every
65: termination of a request. Several call back functions can be
66: registered in which case all of them are called in the reverse order
2.24 frystyk 67: of which they were registered (last one first). We name the calling
68: mechansm of calling the functions for the <EM>before</EM> loop and the
69: <EM>after</EM> loop.<P>
70:
71: In case the callback function is registered as being called
72: <EM>after</EM> the request has terminated the result of the request is
73: passed to the fucntion. The status signifies which call back function
74: to call depending of the result of the request. This can be
2.1 frystyk 75:
2.17 frystyk 76: <DL>
77: <DT>HT_ERROR
78: <DD>An error occured
79: <DT>HT_LOADED
80: <DD>The document was loaded
81: <DT>HT_NO_DATA
82: <DD>OK, but no data
83: <DT>HT_RETRY
84: <DD>Retry request after at a later time
2.24 frystyk 85: <DT>HT_REDIRECT
86: <DD>The request has been redirected and we send back the new URL
2.17 frystyk 87: <DT>HT_ALL
88: <DD>All of above
89: </DL>
2.1 frystyk 90:
2.24 frystyk 91: Any callback function any code it likes, but <B>IF NOT</B> the code is
92: <EM>HT_OK</EM>, then the callback loop is stopped. If we are in the
93: <EM>before</EM> loop and a function returns anything else than
94: <EM>HT_OK</EM> then we immediately jump to the <EM>after</EM> loop
95: <B>passing</B> the last return code from the <EM>before</EM> loop.
96:
2.1 frystyk 97: <PRE>
2.23 frystyk 98: typedef int HTNetCallback (HTRequest * request, int status);
2.17 frystyk 99:
2.24 frystyk 100: extern BOOL HTNetCall_add (HTList * list, HTNetCallback *cbf, int status);
2.9 frystyk 101: </PRE>
102:
2.24 frystyk 103: <H3>Delete a single Callbak</H3>
2.9 frystyk 104:
2.24 frystyk 105: Removes a callback function from a list
2.9 frystyk 106:
107: <PRE>
2.24 frystyk 108: extern BOOL HTNetCall_delete (HTList * list, HTNetCallback *cbf);
2.1 frystyk 109: </PRE>
110:
2.24 frystyk 111: <H3>Delete a list of Callbacks</H3>
112:
113: Unregisters all call back functions in the list
114:
115: <PRE>
116: extern BOOL HTNetCall_deleteAll (HTList * list);
117: </PRE>
118:
119: <H3>Call List of Registered Callback Functions</H3>
2.10 frystyk 120:
2.17 frystyk 121: Call all the call back functions registered in the list IF not the
2.24 frystyk 122: status is HT_IGNORE. The callback functions are called in the order
123: of which they were registered. At the moment an application callback
124: function is called, it can free the request object - it is no longer
125: used by the Library. Returns what the last callback function returns
126:
127: <PRE>
128: extern int HTNetCall_execute (HTList * list, HTRequest * request, int status);
129: </PRE>
130:
131: <H3>BEFORE Callbacks</H3>
132:
133: Global set of callback functions BEFORE the request is issued. The
134: list can be NULL.
135:
136: <PRE>
2.25 frystyk 137: extern BOOL HTNetCall_addBefore (HTNetCallback *cbf, int status);
2.24 frystyk 138: extern BOOL HTNet_setBefore (HTList * list);
139: extern HTList * HTNet_before (void);
140: extern int HTNet_callBefore (HTRequest *request, int status);
141: </PRE>
142:
143: <H3>AFTER Callbacks</H3>
144:
145: Global set of callback functions AFTER the request is issued. The list can be NULL
2.10 frystyk 146:
147: <PRE>
2.25 frystyk 148: extern BOOL HTNetCall_addAfter (HTNetCallback *cbf, int status);
2.24 frystyk 149: extern BOOL HTNet_setAfter (HTList * list);
150: extern HTList * HTNet_after (void);
151: extern int HTNet_callAfter (HTRequest *request, int status);
2.10 frystyk 152: </PRE>
153:
2.17 frystyk 154: <H2>Request Queue</H2>
155:
156: The request queue ensures that no more than a fixed number of TCP
157: connections are open at the same time. If more requests are handed to
158: the Library, they are put into the pending queue and initiated when
159: sockets become free.
160:
161: <H3>Number of Simultanous open TCP connections</H3>
2.1 frystyk 162:
2.17 frystyk 163: Set the max number of simultanous sockets. The default value is
2.19 frystyk 164: HT_MAX_SOCKETS which is 6. The number of persistent connections depend
165: on this value as a deadlock can occur if all available sockets a
166: persistent (see the <A HREF="HTDNS.html">DNS Manager</A> for more
167: information on setting the number of persistent connections). The
168: number of persistent connections can never be more than the max number
169: of sockets-2, so letting newmax=2 prevents persistent sockets.
2.1 frystyk 170:
171: <PRE>
2.17 frystyk 172: extern BOOL HTNet_setMaxSocket (int newmax);
173: extern int HTNet_maxSocket (void);
2.1 frystyk 174: </PRE>
175:
2.23 frystyk 176: <H3>List Active Queue</H3>
2.1 frystyk 177:
2.17 frystyk 178: Returns the list of active requests that are currently having an open
2.22 frystyk 179: connection. Returns list of HTNet objects or NULL if
2.29 frystyk 180: error.
2.1 frystyk 181:
182: <PRE>
2.17 frystyk 183: extern HTList *HTNet_activeQueue (void);
2.22 frystyk 184: extern BOOL HTNet_idle (void);
2.29 frystyk 185: </PRE>
186:
187: <H3>Are we Active?</H3>
188:
189: We have some small functions that tell whether there are registered
190: requests in the Net manager. There are tree queues: The
191: <EM>active</EM>, the <EM>pending</EM>, and the
192: <EM>persistent</EM>. The <EM>active</EM> queue is the set of requests
193: that are actively sending or receiving data. The <EM>pending</EM> is
194: the requests that we have registered but which are waiting for a free
195: socket. The <EM>Persistent</EM> queue are requets that are waiting to
196: use the same socket in order to save network resoures (if the server
197: understands persistent connections). <P>
198:
199: <H4>Active Reqeusts?</H4>
200:
201: Returns whether there are requests in the <EM>active</EM> queue or not
202:
203: <PRE>
204: extern BOOL HTNet_idle (void);
205: </PRE>
206:
207: <H4>Registered Requests?</H4>
208:
209: Returns whether there are requests registered in any of the lists or
210: not
211:
212: <PRE>
213: extern BOOL HTNet_isEmpty (void);
2.1 frystyk 214: </PRE>
2.17 frystyk 215:
2.23 frystyk 216: <H3>List Pending Queue</H3>
2.17 frystyk 217:
218: Returns the list of pending requests that are waiting to become
219: active. Returns list of HTNet objects or NULL if error
220:
2.1 frystyk 221: <PRE>
2.17 frystyk 222: extern HTList *HTNet_pendingQueue (void);
2.1 frystyk 223: </PRE>
224:
2.27 frystyk 225: <H2>Create an Object</H2>
2.17 frystyk 226:
2.27 frystyk 227: You can create a new HTNet object as a new request to be handled. If
2.28 frystyk 228: we have more than HTMaxActive connections already then put this into
229: the pending queue, else start the request by calling the call back
230: function registered with this access method. Returns YES if OK, else
231: NO
2.17 frystyk 232:
2.27 frystyk 233: <PRE>
2.28 frystyk 234: extern BOOL HTNet_newClient (HTRequest * request);
2.27 frystyk 235: </PRE>
2.17 frystyk 236:
2.27 frystyk 237: You can create a new HTNet object as a new request to be handled. If
2.28 frystyk 238: we have more than HTMaxActive connections already then return NO.
239: Returns YES if OK, else NO
2.17 frystyk 240:
241: <PRE>
2.31 frystyk 242: extern BOOL HTNet_newServer (HTRequest * request, SOCKET sockfd, char *access);
2.26 frystyk 243: </PRE>
244:
2.27 frystyk 245: And you can create a plain new HTNet object using the following method:
2.26 frystyk 246:
247: <PRE>
2.27 frystyk 248: extern HTNet * HTNet_new (HTRequest * request, SOCKET sockfd);
2.20 frystyk 249: </PRE>
250:
251: <H3>Duplicate an Existing Object</H3>
252:
253: Creates a new HTNet object as a duplicate of the same request.
254: Returns YES if OK, else NO.
255:
256: <PRE>
2.30 frystyk 257: extern HTNet * HTNet_dup (HTNet * src);
2.17 frystyk 258: </PRE>
2.27 frystyk 259:
260: <H2>HTNet Object Methods</H2>
2.17 frystyk 261:
2.23 frystyk 262: <H3>Make an Object Wait</H3>
2.19 frystyk 263:
264: Let a net object wait for a persistent socket. It will be launched
265: from the HTNet_delete() function when the socket gets free.
266:
267: <PRE>
268: extern BOOL HTNet_wait (HTNet *net);
269: </PRE>
270:
2.23 frystyk 271: <H3>Priority Management</H3>
272:
273: Each HTNet object is created with a priority which it inherits from
274: the <A HREF="HTReq.html">Request manager</A>. However, in some
275: stuations it is useful to be to change the current priority after the
276: request has been started. These two functions allow you to do
277: this. The effect will show up the first time (which might be
278: imidiately) the socket blocks and control returns to the event loop.
279: Also have a look at how you can do this before the request is issued
280: in the <A HREF="HTReq.html">request manager</A>.
281:
282: <PRE>
283: extern HTPriority HTNet_priority (HTNet * net);
284: extern BOOL HTNet_setPriority (HTNet * net, HTPriority priority);
285: </PRE>
286:
2.17 frystyk 287: <H3>Delete an Object</H3>
288:
289: Deletes the HTNet object from the list of active requests and calls
290: any registered call back functions IF not the status is HT_IGNORE.
291: This is used if we have internal requests that the app doesn't know
292: about. We also see if we have pending requests that can be started up
293: now when we have a socket free. The callback functions are called in
2.24 frystyk 294: the reverse order of which they were registered (last one first);
2.1 frystyk 295:
296: <PRE>
2.17 frystyk 297: extern BOOL HTNet_delete (HTNet * me, int status);
2.1 frystyk 298: </PRE>
299:
2.17 frystyk 300: <H3>Delete ALL HTNet Objects</H3>
2.1 frystyk 301:
2.17 frystyk 302: Deletes all HTNet object that might either be active or pending We DO
2.19 frystyk 303: NOT call the call back functions - A crude way of saying goodbye!
2.1 frystyk 304:
305: <PRE>
2.17 frystyk 306: extern BOOL HTNet_deleteAll (void);
2.1 frystyk 307: </PRE>
2.17 frystyk 308:
309: <H3>Kill a Request</H3>
2.1 frystyk 310:
2.17 frystyk 311: Kill the request by calling the call back function with a request for
312: closing the connection. Does not remove the object. This is done by
313: HTNet_delete() function which is called by the load routine. Returns
314: OK if success, NO on error
2.1 frystyk 315:
316: <PRE>
2.17 frystyk 317: extern BOOL HTNet_kill (HTNet * me);
2.1 frystyk 318: </PRE>
319:
2.17 frystyk 320: <H3>Kill ALL requests</H3>
2.1 frystyk 321:
2.17 frystyk 322: Kills all registered (active+pending) requests by calling the call
323: back function with a request for closing the connection. We do not
324: remove the HTNet object as it is done by HTNet_delete(). Returns OK
325: if success, NO on error
2.1 frystyk 326:
327: <PRE>
2.17 frystyk 328: extern BOOL HTNet_killAll (void);
2.28 frystyk 329: </PRE>
330:
331: <H2>Data Access Methods</H2>
332:
333: <H3>Socket Descriptor</H3>
334:
335: <PRE>
336: extern BOOL HTNet_setSocket (HTNet * net, SOCKET sockfd);
337: extern SOCKET HTNet_socket (HTNet * net);
2.17 frystyk 338: </PRE>
2.1 frystyk 339:
2.17 frystyk 340: <PRE>
341: #endif /* HTNET_H */
2.1 frystyk 342: </PRE>
343:
2.17 frystyk 344: End of declaration module
2.1 frystyk 345: </BODY>
346: </HTML>
347:
348:
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTNet.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src