Annotation of libwww/Library/src/HTNet.html, revision 2.42
2.1 frystyk 1: <HTML>
2: <HEAD>
2.36 eric 3: <!-- Changed by: Henrik Frystyk Nielsen, 13-Apr-1996 -->
2.37 frystyk 4: <!-- Changed by: Eric Prud'hommeaux, 14-May-1996 -->
2.40 frystyk 5: <!-- Changed by: Henrik Frystyk Nielsen, 5-Jul-1996 -->
2.37 frystyk 6: <TITLE>W3C Reference Library libwww HTNet Class</TITLE>
2.1 frystyk 7: </HEAD>
8: <BODY>
2.37 frystyk 9: <H1>The Net Class
2.36 eric 10: </H1>
2.5 frystyk 11: <PRE>
12: /*
2.8 frystyk 13: ** (c) COPYRIGHT MIT 1995.
2.5 frystyk 14: ** Please first read the full copyright statement in the file COPYRIGH.
15: */
16: </PRE>
2.36 eric 17: <P>
2.38 frystyk 18: The Net class manages information related to a "thread" in libwww. As libwww
19: threads are not really threads but a notion of using interleaved, non-blocking
20: I/O for accessing data objects from the network (or local file system), they
21: can be used on any platform with or without support for native threads. In
22: the case where you have an application using real threads the Net class is
23: simply a object maintaining links to all other objects involved in serving
24: the request. If you are using the libwww pseudo threads then the Net object
25: contains enough information to stop and start a request based on which BSD
26: sockets are ready. In practise this is of course transparent to the application
27: - this is just to explain the difference.
28: <P>
29: When a <A HREF="HTReq.html">Request object</A> is passed to the Library ,
30: the core creates a new HTNet object pr <A HREF="HTChannl.html">channel</A>
31: used by the request. In many cases a request only uses a single
32: <A HREF="HTChannl.html">channel object </A>but for example FTP requests use
33: at least two - one for the control connection and one for the data connection.
34: <P>
35: You can find more information about the libwww pseudo thread model in the
36: <A HREF="../User/Architecture/"> Multithread Specifications</A>.
2.36 eric 37: <P>
38: This module is implemented by <A HREF="HTNet.c">HTNet.c</A>, and it is a
39: part of the <A HREF="http://www.w3.org/pub/WWW/Library/">W3C Reference
40: Library</A>.
2.1 frystyk 41: <PRE>
2.17 frystyk 42: #ifndef HTNET_H
43: #define HTNET_H
2.1 frystyk 44: </PRE>
2.36 eric 45: <P>
46: The <CODE>HTNet</CODE> object is the core of the request queue management.
47: This object contains information about the socket descriptor, the input read
48: buffer etc. required to identify and service a request.
2.1 frystyk 49: <PRE>
2.18 frystyk 50: typedef struct _HTNet HTNet;
2.34 frystyk 51:
2.36 eric 52: #include "HTEvent.h"
2.34 frystyk 53: #include "HTReq.h"
54: #include "HTTrans.h"
55: #include "HTHost.h"
56: #include "HTChannl.h"
57: #include "HTDNS.h"
2.1 frystyk 58: </PRE>
2.36 eric 59: <H2>
2.38 frystyk 60: <A NAME="callout">Net Callback Functions</A>
2.36 eric 61: </H2>
62: <P>
2.24 frystyk 63: Callback functions can be registered to be called <EM>before</EM> and
2.36 eric 64: <EM>after</EM> a request has either been started or has terminated. The following
65: functions are the generic registration mechanisms where we use lists as the
66: basic data container. Then there is two methods for binding a list of callback
67: functions to the set which is called <EM>before</EM> and to the set set which
68: is called <EM>after</EM>
69: <P>
70: In both cases there can be more than one callback function which are called
71: on turn and each callback function can be associated with a status code of
2.38 frystyk 72: the request. For example one callback function can be registered for
73: <CODE>HT_LOADED</CODE>, another for <CODE>HT_ERROR</CODE> etc.
2.36 eric 74: <H3>
2.37 frystyk 75: Register a Net Callback
2.36 eric 76: </H3>
77: <P>
78: Register a call back function that is to be called on every termination of
79: a request. Several call back functions can be registered in which case all
80: of them are called in the reverse order of which they were registered (last
81: one first). We name the calling mechansm of calling the functions for the
82: <EM>before</EM> loop and the <EM>after</EM> loop.
83: <P>
84: In case the callback function is registered as being called <EM>after</EM>
85: the request has terminated the result of the request is passed to the fucntion.
86: The status signifies which call back function to call depending of the result
87: of the request. This can be
2.17 frystyk 88: <DL>
2.36 eric 89: <DT>
90: HT_ERROR
91: <DD>
92: An error occured
93: <DT>
94: HT_LOADED
95: <DD>
96: The document was loaded
97: <DT>
98: HT_NO_DATA
99: <DD>
100: OK, but no data
101: <DT>
102: HT_RETRY
103: <DD>
104: Retry request after at a later time
105: <DT>
2.40 frystyk 106: HT_PERM_REDIRECT
2.36 eric 107: <DD>
2.40 frystyk 108: The request has been permanently redirected and we send back the new URL
109: <DT>
110: HT_TEMP_REDIRECT
111: <DD>
112: The request has been temporaryly redirected and we send back the new URL
2.36 eric 113: <DT>
114: HT_ALL
115: <DD>
116: All of above
2.17 frystyk 117: </DL>
2.36 eric 118: <P>
2.24 frystyk 119: Any callback function any code it likes, but <B>IF NOT</B> the code is
120: <EM>HT_OK</EM>, then the callback loop is stopped. If we are in the
2.36 eric 121: <EM>before</EM> loop and a function returns anything else than <EM>HT_OK</EM>
122: then we immediately jump to the <EM>after</EM> loop <B>passing</B> the last
123: return code from the <EM>before</EM> loop.
2.1 frystyk 124: <PRE>
2.35 frystyk 125: typedef int HTNetCallback (HTRequest * request, void * param, int status);
2.17 frystyk 126:
2.35 frystyk 127: extern BOOL HTNetCall_add (HTList * list, HTNetCallback *cbf,
128: void * param, int status);
2.9 frystyk 129: </PRE>
2.36 eric 130: <H3>
2.37 frystyk 131: Delete a single Callback
2.36 eric 132: </H3>
133: <P>
2.24 frystyk 134: Removes a callback function from a list
2.9 frystyk 135: <PRE>
2.24 frystyk 136: extern BOOL HTNetCall_delete (HTList * list, HTNetCallback *cbf);
2.1 frystyk 137: </PRE>
2.36 eric 138: <H3>
139: Delete a list of Callbacks
140: </H3>
141: <P>
2.24 frystyk 142: Unregisters all call back functions in the list
143: <PRE>
144: extern BOOL HTNetCall_deleteAll (HTList * list);
145: </PRE>
2.36 eric 146: <H3>
147: Call List of Registered Callback Functions
148: </H3>
149: <P>
150: Call all the call back functions registered in the list IF not the status
151: is HT_IGNORE. The callback functions are called in the order of which they
152: were registered. At the moment an application callback function is called,
153: it can free the request object - it is no longer used by the Library. Returns
154: what the last callback function returns
2.24 frystyk 155: <PRE>
156: extern int HTNetCall_execute (HTList * list, HTRequest * request, int status);
157: </PRE>
2.36 eric 158: <H3>
2.37 frystyk 159: Handling BEFORE Callbacks
2.36 eric 160: </H3>
161: <P>
162: Global set of callback functions BEFORE the request is issued. The list can
163: be NULL.
2.24 frystyk 164: <PRE>
2.35 frystyk 165: extern BOOL HTNetCall_addBefore (HTNetCallback *cbf, void * param, int status);
2.42 ! frystyk 166: extern BOOL HTNetCall_deleteBefore (HTNetCallback * cbf);
! 167:
2.24 frystyk 168: extern BOOL HTNet_setBefore (HTList * list);
169: extern HTList * HTNet_before (void);
2.42 ! frystyk 170:
2.24 frystyk 171: extern int HTNet_callBefore (HTRequest *request, int status);
172: </PRE>
2.36 eric 173: <H3>
2.37 frystyk 174: Handling AFTER Callbacks
2.36 eric 175: </H3>
176: <P>
177: Global set of callback functions AFTER the request is issued. The list can
178: be NULL
2.10 frystyk 179: <PRE>
2.35 frystyk 180: extern BOOL HTNetCall_addAfter (HTNetCallback *cbf, void * param, int status);
2.42 ! frystyk 181: extern BOOL HTNetCall_deleteAfter (HTNetCallback * cbf);
! 182:
2.24 frystyk 183: extern BOOL HTNet_setAfter (HTList * list);
184: extern HTList * HTNet_after (void);
2.42 ! frystyk 185:
2.24 frystyk 186: extern int HTNet_callAfter (HTRequest *request, int status);
2.10 frystyk 187: </PRE>
2.36 eric 188: <H2>
2.38 frystyk 189: Request Queueing and Resource Management
2.36 eric 190: </H2>
191: <P>
192: The request queue ensures that no more than a fixed number of TCP connections
193: are open at the same time. If more requests are handed to the Library, they
194: are put into the pending queue and initiated when sockets become free.
195: <H3>
196: Number of Simultanous open TCP connections
197: </H3>
198: <P>
199: Set the max number of simultanous sockets. The default value is HT_MAX_SOCKETS
200: which is 6. The number of persistent connections depend on this value as
201: a deadlock can occur if all available sockets a persistent (see the
202: <A HREF="HTDNS.html">DNS Manager</A> for more information on setting the
203: number of persistent connections). The number of persistent connections can
204: never be more than the max number of sockets-2, so letting newmax=2 prevents
205: persistent sockets.
2.1 frystyk 206: <PRE>
2.17 frystyk 207: extern BOOL HTNet_setMaxSocket (int newmax);
208: extern int HTNet_maxSocket (void);
2.1 frystyk 209: </PRE>
2.36 eric 210: <H3>
211: List Active Queue
212: </H3>
213: <P>
214: Returns the list of active requests that are currently having an open connection.
215: Returns list of HTNet objects or NULL if error.
2.1 frystyk 216: <PRE>
2.17 frystyk 217: extern HTList *HTNet_activeQueue (void);
2.22 frystyk 218: extern BOOL HTNet_idle (void);
2.29 frystyk 219: </PRE>
2.36 eric 220: <H3>
221: Are we Active?
222: </H3>
223: <P>
224: We have some small functions that tell whether there are registered requests
225: in the Net manager. There are tree queues: The <EM>active</EM>, the
226: <EM>pending</EM>, and the <EM>persistent</EM>. The <EM>active</EM> queue
227: is the set of requests that are actively sending or receiving data. The
228: <EM>pending</EM> is the requests that we have registered but which are waiting
229: for a free socket. The <EM>Persistent</EM> queue are requets that are waiting
230: to use the same socket in order to save network resoures (if the server
231: understands persistent connections).
232: <H4>
233: Active Reqeusts?
234: </H4>
235: <P>
2.29 frystyk 236: Returns whether there are requests in the <EM>active</EM> queue or not
237: <PRE>
238: extern BOOL HTNet_idle (void);
239: </PRE>
2.36 eric 240: <H4>
241: Registered Requests?
242: </H4>
243: <P>
244: Returns whether there are requests registered in any of the lists or not
2.29 frystyk 245: <PRE>
246: extern BOOL HTNet_isEmpty (void);
2.1 frystyk 247: </PRE>
2.36 eric 248: <H3>
249: List Pending Queue
250: </H3>
251: <P>
252: Returns the list of pending requests that are waiting to become active. Returns
253: list of HTNet objects or NULL if error
2.1 frystyk 254: <PRE>
2.17 frystyk 255: extern HTList *HTNet_pendingQueue (void);
2.1 frystyk 256: </PRE>
2.36 eric 257: <H2>
2.37 frystyk 258: Creation and Deletion Methods
2.36 eric 259: </H2>
260: <P>
2.37 frystyk 261: The Net object is intended to live as long as the request is still active.
262: In that regard it is very similar to the <A HREF="HTReq.html">Request Object
263: </A>. However, the main difference is that a Net object represents a "thread"
264: in the Library and a request may have multiple "threads" - an example is
265: a FTP request which has a thread to handle the control connection and one
266: to handle the data connections.
267: <H3>
268: Create a new Object
269: </H3>
270: <P>
271: If we have more than HTMaxActive connections already then put this into the
272: pending queue, else start the request by calling the call back function
273: registered with this access method. Returns YES if OK, else NO
2.27 frystyk 274: <PRE>
2.28 frystyk 275: extern BOOL HTNet_newClient (HTRequest * request);
2.27 frystyk 276: </PRE>
2.36 eric 277: <P>
278: You can create a new HTNet object as a new request to be handled. If we have
279: more than HTMaxActive connections already then return NO. Returns YES if
280: OK, else NO
2.17 frystyk 281: <PRE>
2.39 frystyk 282: extern BOOL HTNet_newServer (HTRequest * request, HTNet * net, char *access);
2.26 frystyk 283: </PRE>
2.36 eric 284: <P>
2.27 frystyk 285: And you can create a plain new HTNet object using the following method:
2.26 frystyk 286: <PRE>
2.39 frystyk 287: extern HTNet * HTNet_new (SOCKET sockfd, HTRequest * request);
2.20 frystyk 288: </PRE>
2.36 eric 289: <H3>
2.37 frystyk 290: Duplicate an existing Object
2.36 eric 291: </H3>
292: <P>
293: Creates a new HTNet object as a duplicate of the same request. Returns YES
294: if OK, else NO.
2.20 frystyk 295: <PRE>
2.30 frystyk 296: extern HTNet * HTNet_dup (HTNet * src);
2.17 frystyk 297: </PRE>
2.37 frystyk 298: <H3>
299: Delete an Object
300: </H3>
301: <P>
302: Deletes the HTNet object from the list of active requests and calls any
303: registered call back functions IF not the status is HT_IGNORE. This is used
304: if we have internal requests that the app doesn't know about. We also see
305: if we have pending requests that can be started up now when we have a socket
306: free. The callback functions are called in the reverse order of which they
307: were registered (last one first);
308: <PRE>
309: extern BOOL HTNet_delete (HTNet * me, int status);
310: </PRE>
311: <H3>
312: Delete ALL HTNet Objects
313: </H3>
314: <P>
315: Deletes all HTNet object that might either be active or pending We DO NOT
316: call the call back functions - A crude way of saying goodbye!
317: <PRE>
318: extern BOOL HTNet_deleteAll (void);
319: </PRE>
2.36 eric 320: <H2>
2.38 frystyk 321: Net Class Methods
2.36 eric 322: </H2>
323: <H3>
324: Make an Object Wait
325: </H3>
326: <P>
327: Let a net object wait for a persistent socket. It will be launched from the
328: HTNet_delete() function when the socket gets free.
2.19 frystyk 329: <PRE>
330: extern BOOL HTNet_wait (HTNet *net);
331: </PRE>
2.36 eric 332: <H3>
333: Priority Management
334: </H3>
335: <P>
336: Each HTNet object is created with a priority which it inherits from the
337: <A HREF="HTReq.html">Request manager</A>. However, in some stuations it is
338: useful to be to change the current priority after the request has been started.
339: These two functions allow you to do this. The effect will show up the first
340: time (which might be imidiately) the socket blocks and control returns to
341: the event loop. Also have a look at how you can do this before the request
342: is issued in the <A HREF="HTReq.html">request manager</A>.
2.23 frystyk 343: <PRE>
344: extern HTPriority HTNet_priority (HTNet * net);
345: extern BOOL HTNet_setPriority (HTNet * net, HTPriority priority);
346: </PRE>
2.36 eric 347: <H3>
348: Persistent Connections
349: </H3>
350: <P>
351: You can set a Net object to handle persistent connections for example using
352: HTTP, NNTP, or FTP. You can control whether a Net object supports persistent
353: connections or not using this function.
2.33 frystyk 354: <PRE>
355: extern BOOL HTNet_persistent (HTNet * net);
356: </PRE>
2.36 eric 357: <P>
358: You can set or disable a Net object supporting persistent connections using
359: this function:
2.33 frystyk 360: <PRE>
361: extern BOOL HTNet_setPersistent (HTNet * net, BOOL persistent);
362: </PRE>
2.36 eric 363: <H3>
364: Kill a Request
365: </H3>
366: <P>
367: Kill the request by calling the call back function with a request for closing
368: the connection. Does not remove the object. This is done by HTNet_delete()
369: function which is called by the load routine. Returns OK if success, NO on
370: error
2.1 frystyk 371: <PRE>
2.17 frystyk 372: extern BOOL HTNet_kill (HTNet * me);
2.1 frystyk 373: </PRE>
2.36 eric 374: <H3>
375: Kill ALL requests
376: </H3>
377: <P>
378: Kills all registered (active+pending) requests by calling the call back function
379: with a request for closing the connection. We do not remove the HTNet object
380: as it is done by HTNet_delete(). Returns OK if success, NO on error
2.1 frystyk 381: <PRE>
2.17 frystyk 382: extern BOOL HTNet_killAll (void);
2.28 frystyk 383: </PRE>
2.36 eric 384: <H3>
385: Create Input and Output Streams
386: </H3>
387: <P>
388: You create the input stream and bind it to the channel using the following
389: methods. Please read the description in the
390: <A HREF="HTIOStream.html">HTIOStream module</A> on the parameters
391: <EM>target</EM>, <EM>param</EM>, and <EM>mode</EM>. Both methods return YES
392: if OK, else NO.
2.34 frystyk 393: <PRE>
394: extern HTInputStream * HTNet_getInput (HTNet * net, HTStream * target,
395: void * param, int mode);
396:
397: extern HTOutputStream * HTNet_getOutput (HTNet * net, void * param, int mode);
398: </PRE>
2.37 frystyk 399: <H3>
400: Net Context Descriptor
401: </H3>
2.36 eric 402: <P>
2.37 frystyk 403: Just like the <A HREF="../../../../WWW/Library/src/HTReq.html#context">request
404: object</A>, a net object can be assigned a context which keeps track of context
405: dependent information. The Library does not use this information nor does
406: it depend on it but it allows the application to customize a net object to
407: specific uses.
408: <PRE>extern BOOL HTNet_setContext (HTNet * net, void * context);
409: extern void * HTNet_context (HTNet * net);
410: </PRE>
2.36 eric 411: <H3>
412: Socket Descriptor
413: </H3>
2.28 frystyk 414: <PRE>
415: extern BOOL HTNet_setSocket (HTNet * net, SOCKET sockfd);
416: extern SOCKET HTNet_socket (HTNet * net);
2.17 frystyk 417: </PRE>
2.36 eric 418: <H3>
2.39 frystyk 419: The Request Object
420: </H3>
421: <P>
422: The <A HREF="HTReq.html">Request object</A> is normally set up
423: automatically but can be changed at a later time.
424: <PRE>
425: extern BOOL HTNet_setRequest (HTNet * net, HTRequest * request);
426: extern HTRequest * HTNet_request (HTNet * net);
427: </PRE>
428: <H3>
2.36 eric 429: The Transport Object
430: </H3>
431: <P>
2.34 frystyk 432: The <A HREF="HTTransport.html">transport object</A> is normally set up
433: automatically but can be changed at a later time.
2.17 frystyk 434: <PRE>
2.34 frystyk 435: extern BOOL HTNet_setTransport (HTNet * net, HTTransport * tp);
436: extern HTTransport * HTNet_transport (HTNet * net);
437: </PRE>
2.36 eric 438: <H3>
439: The Channel Object
440: </H3>
2.34 frystyk 441: <PRE>
442: extern BOOL HTNet_setChannel (HTNet * net, HTChannel * channel);
443: extern HTChannel * HTNet_channel (HTNet * net);
444: </PRE>
2.36 eric 445: <H3>
446: The Host Object
447: </H3>
2.34 frystyk 448: <PRE>
449: extern BOOL HTNet_setHost (HTNet * net, HTHost * host);
450: extern HTHost * HTNet_host (HTNet * net);
451: </PRE>
2.36 eric 452: <H3>
453: The DNS Object
454: </H3>
2.41 frystyk 455:
456: The DNS object keeps track of the DNS entries that we have already
457: checked out.
2.34 frystyk 458: <PRE>
459: extern BOOL HTNet_setDns (HTNet * net, HTdns * dns);
460: extern HTdns * HTNet_dns (HTNet * net);
461: </PRE>
2.41 frystyk 462:
463: If we are talking to a multi-homed host then we may
464: connect to any of the homes. In that case we store the current home in
465: the Net object so that we can query about it later.
466:
467: <PRE>
468: extern int HTNet_home (HTNet * net);
469: </PRE>
470:
2.34 frystyk 471: <PRE>
2.17 frystyk 472: #endif /* HTNET_H */
2.1 frystyk 473: </PRE>
2.36 eric 474: <P>
475: <HR>
2.34 frystyk 476: <ADDRESS>
2.42 ! frystyk 477: @(#) $Id: HTNet.html,v 2.41 1996/08/05 17:22:41 frystyk Exp $
2.34 frystyk 478: </ADDRESS>
2.36 eric 479: </BODY></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