Annotation of libwww/Library/src/HTNet.html, revision 2.34
2.1 frystyk 1: <HTML>
2: <HEAD>
2.32 frystyk 3: <TITLE>W3C Reference Library libwww NET OBJECT</TITLE>
2.34 ! frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 5-Apr-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.1 frystyk 32: </PRE>
33:
2.17 frystyk 34: <H2>The HTNet Object</H2>
2.1 frystyk 35:
2.17 frystyk 36: The <CODE>HTNet</CODE> object is the core of the request queue
37: management. This object contains information about the socket
38: descriptor, the input read buffer etc. required to identify and
39: service a request. <P>
2.1 frystyk 40:
41: <PRE>
2.18 frystyk 42: typedef struct _HTNet HTNet;
2.34 ! frystyk 43:
! 44: #include "HTEvntrg.h"
! 45: #include "HTReq.h"
! 46: #include "HTTrans.h"
! 47: #include "HTHost.h"
! 48: #include "HTChannl.h"
! 49: #include "HTDNS.h"
2.1 frystyk 50: </PRE>
51:
2.24 frystyk 52: <H2>Request Call Back Functions</H2>
2.17 frystyk 53:
2.24 frystyk 54: Callback functions can be registered to be called <EM>before</EM> and
55: <EM>after</EM> a request has either been started or has
56: terminated. The following functions are the generic registration
57: mechanisms where we use lists as the basic data container. Then there
58: is two methods for binding a list of callback functions to the set
59: which is called <EM>before</EM> and to the set set which is called
60: <EM>after</EM> <P>
61:
62: In both cases there can be more than one callback function which are
2.17 frystyk 63: called on turn and each callback function can be associated with a
64: status code of the request. For example one callback function can be
65: registered for HT_LOADED, another for HT_ERROR etc.
66:
67: <H3>Register a Request Callback</H3>
2.2 frystyk 68:
2.17 frystyk 69: Register a call back function that is to be called on every
70: termination of a request. Several call back functions can be
71: registered in which case all of them are called in the reverse order
2.24 frystyk 72: of which they were registered (last one first). We name the calling
73: mechansm of calling the functions for the <EM>before</EM> loop and the
74: <EM>after</EM> loop.<P>
75:
76: In case the callback function is registered as being called
77: <EM>after</EM> the request has terminated the result of the request is
78: passed to the fucntion. The status signifies which call back function
79: to call depending of the result of the request. This can be
2.1 frystyk 80:
2.17 frystyk 81: <DL>
82: <DT>HT_ERROR
83: <DD>An error occured
84: <DT>HT_LOADED
85: <DD>The document was loaded
86: <DT>HT_NO_DATA
87: <DD>OK, but no data
88: <DT>HT_RETRY
89: <DD>Retry request after at a later time
2.24 frystyk 90: <DT>HT_REDIRECT
91: <DD>The request has been redirected and we send back the new URL
2.17 frystyk 92: <DT>HT_ALL
93: <DD>All of above
94: </DL>
2.1 frystyk 95:
2.24 frystyk 96: Any callback function any code it likes, but <B>IF NOT</B> the code is
97: <EM>HT_OK</EM>, then the callback loop is stopped. If we are in the
98: <EM>before</EM> loop and a function returns anything else than
99: <EM>HT_OK</EM> then we immediately jump to the <EM>after</EM> loop
100: <B>passing</B> the last return code from the <EM>before</EM> loop.
101:
2.1 frystyk 102: <PRE>
2.23 frystyk 103: typedef int HTNetCallback (HTRequest * request, int status);
2.17 frystyk 104:
2.24 frystyk 105: extern BOOL HTNetCall_add (HTList * list, HTNetCallback *cbf, int status);
2.9 frystyk 106: </PRE>
107:
2.24 frystyk 108: <H3>Delete a single Callbak</H3>
2.9 frystyk 109:
2.24 frystyk 110: Removes a callback function from a list
2.9 frystyk 111:
112: <PRE>
2.24 frystyk 113: extern BOOL HTNetCall_delete (HTList * list, HTNetCallback *cbf);
2.1 frystyk 114: </PRE>
115:
2.24 frystyk 116: <H3>Delete a list of Callbacks</H3>
117:
118: Unregisters all call back functions in the list
119:
120: <PRE>
121: extern BOOL HTNetCall_deleteAll (HTList * list);
122: </PRE>
123:
124: <H3>Call List of Registered Callback Functions</H3>
2.10 frystyk 125:
2.17 frystyk 126: Call all the call back functions registered in the list IF not the
2.24 frystyk 127: status is HT_IGNORE. The callback functions are called in the order
128: of which they were registered. At the moment an application callback
129: function is called, it can free the request object - it is no longer
130: used by the Library. Returns what the last callback function returns
131:
132: <PRE>
133: extern int HTNetCall_execute (HTList * list, HTRequest * request, int status);
134: </PRE>
135:
136: <H3>BEFORE Callbacks</H3>
137:
138: Global set of callback functions BEFORE the request is issued. The
139: list can be NULL.
140:
141: <PRE>
2.25 frystyk 142: extern BOOL HTNetCall_addBefore (HTNetCallback *cbf, int status);
2.24 frystyk 143: extern BOOL HTNet_setBefore (HTList * list);
144: extern HTList * HTNet_before (void);
145: extern int HTNet_callBefore (HTRequest *request, int status);
146: </PRE>
147:
148: <H3>AFTER Callbacks</H3>
149:
150: Global set of callback functions AFTER the request is issued. The list can be NULL
2.10 frystyk 151:
152: <PRE>
2.25 frystyk 153: extern BOOL HTNetCall_addAfter (HTNetCallback *cbf, int status);
2.24 frystyk 154: extern BOOL HTNet_setAfter (HTList * list);
155: extern HTList * HTNet_after (void);
156: extern int HTNet_callAfter (HTRequest *request, int status);
2.10 frystyk 157: </PRE>
158:
2.17 frystyk 159: <H2>Request Queue</H2>
160:
161: The request queue ensures that no more than a fixed number of TCP
162: connections are open at the same time. If more requests are handed to
163: the Library, they are put into the pending queue and initiated when
164: sockets become free.
165:
166: <H3>Number of Simultanous open TCP connections</H3>
2.1 frystyk 167:
2.17 frystyk 168: Set the max number of simultanous sockets. The default value is
2.19 frystyk 169: HT_MAX_SOCKETS which is 6. The number of persistent connections depend
170: on this value as a deadlock can occur if all available sockets a
171: persistent (see the <A HREF="HTDNS.html">DNS Manager</A> for more
172: information on setting the number of persistent connections). The
173: number of persistent connections can never be more than the max number
174: of sockets-2, so letting newmax=2 prevents persistent sockets.
2.1 frystyk 175:
176: <PRE>
2.17 frystyk 177: extern BOOL HTNet_setMaxSocket (int newmax);
178: extern int HTNet_maxSocket (void);
2.1 frystyk 179: </PRE>
180:
2.23 frystyk 181: <H3>List Active Queue</H3>
2.1 frystyk 182:
2.17 frystyk 183: Returns the list of active requests that are currently having an open
2.22 frystyk 184: connection. Returns list of HTNet objects or NULL if
2.29 frystyk 185: error.
2.1 frystyk 186:
187: <PRE>
2.17 frystyk 188: extern HTList *HTNet_activeQueue (void);
2.22 frystyk 189: extern BOOL HTNet_idle (void);
2.29 frystyk 190: </PRE>
191:
192: <H3>Are we Active?</H3>
193:
194: We have some small functions that tell whether there are registered
195: requests in the Net manager. There are tree queues: The
196: <EM>active</EM>, the <EM>pending</EM>, and the
197: <EM>persistent</EM>. The <EM>active</EM> queue is the set of requests
198: that are actively sending or receiving data. The <EM>pending</EM> is
199: the requests that we have registered but which are waiting for a free
200: socket. The <EM>Persistent</EM> queue are requets that are waiting to
201: use the same socket in order to save network resoures (if the server
202: understands persistent connections). <P>
203:
204: <H4>Active Reqeusts?</H4>
205:
206: Returns whether there are requests in the <EM>active</EM> queue or not
207:
208: <PRE>
209: extern BOOL HTNet_idle (void);
210: </PRE>
211:
212: <H4>Registered Requests?</H4>
213:
214: Returns whether there are requests registered in any of the lists or
215: not
216:
217: <PRE>
218: extern BOOL HTNet_isEmpty (void);
2.1 frystyk 219: </PRE>
2.17 frystyk 220:
2.23 frystyk 221: <H3>List Pending Queue</H3>
2.17 frystyk 222:
223: Returns the list of pending requests that are waiting to become
224: active. Returns list of HTNet objects or NULL if error
225:
2.1 frystyk 226: <PRE>
2.17 frystyk 227: extern HTList *HTNet_pendingQueue (void);
2.1 frystyk 228: </PRE>
229:
2.27 frystyk 230: <H2>Create an Object</H2>
2.17 frystyk 231:
2.27 frystyk 232: You can create a new HTNet object as a new request to be handled. If
2.28 frystyk 233: we have more than HTMaxActive connections already then put this into
234: the pending queue, else start the request by calling the call back
235: function registered with this access method. Returns YES if OK, else
236: NO
2.17 frystyk 237:
2.27 frystyk 238: <PRE>
2.28 frystyk 239: extern BOOL HTNet_newClient (HTRequest * request);
2.27 frystyk 240: </PRE>
2.17 frystyk 241:
2.27 frystyk 242: You can create a new HTNet object as a new request to be handled. If
2.28 frystyk 243: we have more than HTMaxActive connections already then return NO.
244: Returns YES if OK, else NO
2.17 frystyk 245:
246: <PRE>
2.31 frystyk 247: extern BOOL HTNet_newServer (HTRequest * request, SOCKET sockfd, char *access);
2.26 frystyk 248: </PRE>
249:
2.27 frystyk 250: And you can create a plain new HTNet object using the following method:
2.26 frystyk 251:
252: <PRE>
2.27 frystyk 253: extern HTNet * HTNet_new (HTRequest * request, SOCKET sockfd);
2.20 frystyk 254: </PRE>
255:
256: <H3>Duplicate an Existing Object</H3>
257:
258: Creates a new HTNet object as a duplicate of the same request.
259: Returns YES if OK, else NO.
260:
261: <PRE>
2.30 frystyk 262: extern HTNet * HTNet_dup (HTNet * src);
2.17 frystyk 263: </PRE>
2.27 frystyk 264:
265: <H2>HTNet Object Methods</H2>
2.17 frystyk 266:
2.23 frystyk 267: <H3>Make an Object Wait</H3>
2.19 frystyk 268:
269: Let a net object wait for a persistent socket. It will be launched
270: from the HTNet_delete() function when the socket gets free.
271:
272: <PRE>
273: extern BOOL HTNet_wait (HTNet *net);
274: </PRE>
275:
2.23 frystyk 276: <H3>Priority Management</H3>
277:
278: Each HTNet object is created with a priority which it inherits from
279: the <A HREF="HTReq.html">Request manager</A>. However, in some
280: stuations it is useful to be to change the current priority after the
281: request has been started. These two functions allow you to do
282: this. The effect will show up the first time (which might be
283: imidiately) the socket blocks and control returns to the event loop.
284: Also have a look at how you can do this before the request is issued
285: in the <A HREF="HTReq.html">request manager</A>.
286:
287: <PRE>
288: extern HTPriority HTNet_priority (HTNet * net);
289: extern BOOL HTNet_setPriority (HTNet * net, HTPriority priority);
290: </PRE>
291:
2.33 frystyk 292: <H3>Persistent Connections</H3>
293:
294: You can set a Net object to handle persistent connections for example
295: using HTTP, NNTP, or FTP. You can control whether a Net object
296: supports persistent connections or not using this function.
297:
298: <PRE>
299: extern BOOL HTNet_persistent (HTNet * net);
300: </PRE>
301:
302: You can set or disable a Net object supporting persistent connections
303: using this function:
304:
305: <PRE>
306: extern BOOL HTNet_setPersistent (HTNet * net, BOOL persistent);
307: </PRE>
308:
2.17 frystyk 309: <H3>Delete an Object</H3>
310:
311: Deletes the HTNet object from the list of active requests and calls
312: any registered call back functions IF not the status is HT_IGNORE.
313: This is used if we have internal requests that the app doesn't know
314: about. We also see if we have pending requests that can be started up
315: now when we have a socket free. The callback functions are called in
2.24 frystyk 316: the reverse order of which they were registered (last one first);
2.1 frystyk 317:
318: <PRE>
2.17 frystyk 319: extern BOOL HTNet_delete (HTNet * me, int status);
2.1 frystyk 320: </PRE>
321:
2.17 frystyk 322: <H3>Delete ALL HTNet Objects</H3>
2.1 frystyk 323:
2.17 frystyk 324: Deletes all HTNet object that might either be active or pending We DO
2.19 frystyk 325: NOT call the call back functions - A crude way of saying goodbye!
2.1 frystyk 326:
327: <PRE>
2.17 frystyk 328: extern BOOL HTNet_deleteAll (void);
2.1 frystyk 329: </PRE>
2.17 frystyk 330:
331: <H3>Kill a Request</H3>
2.1 frystyk 332:
2.17 frystyk 333: Kill the request by calling the call back function with a request for
334: closing the connection. Does not remove the object. This is done by
335: HTNet_delete() function which is called by the load routine. Returns
336: OK if success, NO on error
2.1 frystyk 337:
338: <PRE>
2.17 frystyk 339: extern BOOL HTNet_kill (HTNet * me);
2.1 frystyk 340: </PRE>
341:
2.17 frystyk 342: <H3>Kill ALL requests</H3>
2.1 frystyk 343:
2.17 frystyk 344: Kills all registered (active+pending) requests by calling the call
345: back function with a request for closing the connection. We do not
346: remove the HTNet object as it is done by HTNet_delete(). Returns OK
347: if success, NO on error
2.1 frystyk 348:
349: <PRE>
2.17 frystyk 350: extern BOOL HTNet_killAll (void);
2.28 frystyk 351: </PRE>
352:
2.34 ! frystyk 353: <H3>Create Input and Output Streams</H3>
! 354:
! 355: You create the input stream and bind it to the channel using the
! 356: following methods. Please read the description in the <A
! 357: HREF="HTIOStream.html">HTIOStream module</A> on the parameters
! 358: <EM>target</EM>, <EM>param</EM>, and <EM>mode</EM>. Both methods
! 359: return YES if OK, else NO.
! 360:
! 361: <PRE>
! 362: extern HTInputStream * HTNet_getInput (HTNet * net, HTStream * target,
! 363: void * param, int mode);
! 364:
! 365: extern HTOutputStream * HTNet_getOutput (HTNet * net, void * param, int mode);
! 366: </PRE>
! 367:
2.28 frystyk 368: <H2>Data Access Methods</H2>
369:
2.34 ! frystyk 370: We have some methods for accessing the internals of the Net object
! 371:
2.28 frystyk 372: <H3>Socket Descriptor</H3>
373:
374: <PRE>
375: extern BOOL HTNet_setSocket (HTNet * net, SOCKET sockfd);
376: extern SOCKET HTNet_socket (HTNet * net);
2.17 frystyk 377: </PRE>
2.1 frystyk 378:
2.34 ! frystyk 379: <H3>The Transport Object</H3>
! 380:
! 381: The <A HREF="HTTransport.html">transport object</A> is normally set up
! 382: automatically but can be changed at a later time.
! 383:
2.17 frystyk 384: <PRE>
2.34 ! frystyk 385: extern BOOL HTNet_setTransport (HTNet * net, HTTransport * tp);
! 386: extern HTTransport * HTNet_transport (HTNet * net);
! 387: </PRE>
! 388:
! 389: <H3>The Channel Object</H3>
! 390:
! 391: <PRE>
! 392: extern BOOL HTNet_setChannel (HTNet * net, HTChannel * channel);
! 393: extern HTChannel * HTNet_channel (HTNet * net);
! 394: </PRE>
! 395:
! 396: <H3>The Host Object</H3>
! 397:
! 398: <PRE>
! 399: extern BOOL HTNet_setHost (HTNet * net, HTHost * host);
! 400: extern HTHost * HTNet_host (HTNet * net);
! 401: </PRE>
! 402:
! 403: <H3>The DNS Object</H3>
! 404:
! 405: <PRE>
! 406: extern BOOL HTNet_setDns (HTNet * net, HTdns * dns);
! 407: extern HTdns * HTNet_dns (HTNet * net);
! 408: </PRE>
! 409:
! 410: <PRE>
2.17 frystyk 411: #endif /* HTNET_H */
2.1 frystyk 412: </PRE>
413:
2.34 ! frystyk 414: <HR>
! 415: <ADDRESS>
! 416: @(#) $Id: Date Author State $
! 417: </ADDRESS>
2.1 frystyk 418: </BODY>
419: </HTML>
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