Annotation of libwww/Library/src/HTNet.html, revision 2.41
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.24 frystyk 166: extern BOOL HTNet_setBefore (HTList * list);
167: extern HTList * HTNet_before (void);
168: extern int HTNet_callBefore (HTRequest *request, int status);
169: </PRE>
2.36 eric 170: <H3>
2.37 frystyk 171: Handling AFTER Callbacks
2.36 eric 172: </H3>
173: <P>
174: Global set of callback functions AFTER the request is issued. The list can
175: be NULL
2.10 frystyk 176: <PRE>
2.35 frystyk 177: extern BOOL HTNetCall_addAfter (HTNetCallback *cbf, void * param, int status);
2.24 frystyk 178: extern BOOL HTNet_setAfter (HTList * list);
179: extern HTList * HTNet_after (void);
180: extern int HTNet_callAfter (HTRequest *request, int status);
2.10 frystyk 181: </PRE>
2.36 eric 182: <H2>
2.38 frystyk 183: Request Queueing and Resource Management
2.36 eric 184: </H2>
185: <P>
186: The request queue ensures that no more than a fixed number of TCP connections
187: are open at the same time. If more requests are handed to the Library, they
188: are put into the pending queue and initiated when sockets become free.
189: <H3>
190: Number of Simultanous open TCP connections
191: </H3>
192: <P>
193: Set the max number of simultanous sockets. The default value is HT_MAX_SOCKETS
194: which is 6. The number of persistent connections depend on this value as
195: a deadlock can occur if all available sockets a persistent (see the
196: <A HREF="HTDNS.html">DNS Manager</A> for more information on setting the
197: number of persistent connections). The number of persistent connections can
198: never be more than the max number of sockets-2, so letting newmax=2 prevents
199: persistent sockets.
2.1 frystyk 200: <PRE>
2.17 frystyk 201: extern BOOL HTNet_setMaxSocket (int newmax);
202: extern int HTNet_maxSocket (void);
2.1 frystyk 203: </PRE>
2.36 eric 204: <H3>
205: List Active Queue
206: </H3>
207: <P>
208: Returns the list of active requests that are currently having an open connection.
209: Returns list of HTNet objects or NULL if error.
2.1 frystyk 210: <PRE>
2.17 frystyk 211: extern HTList *HTNet_activeQueue (void);
2.22 frystyk 212: extern BOOL HTNet_idle (void);
2.29 frystyk 213: </PRE>
2.36 eric 214: <H3>
215: Are we Active?
216: </H3>
217: <P>
218: We have some small functions that tell whether there are registered requests
219: in the Net manager. There are tree queues: The <EM>active</EM>, the
220: <EM>pending</EM>, and the <EM>persistent</EM>. The <EM>active</EM> queue
221: is the set of requests that are actively sending or receiving data. The
222: <EM>pending</EM> is the requests that we have registered but which are waiting
223: for a free socket. The <EM>Persistent</EM> queue are requets that are waiting
224: to use the same socket in order to save network resoures (if the server
225: understands persistent connections).
226: <H4>
227: Active Reqeusts?
228: </H4>
229: <P>
2.29 frystyk 230: Returns whether there are requests in the <EM>active</EM> queue or not
231: <PRE>
232: extern BOOL HTNet_idle (void);
233: </PRE>
2.36 eric 234: <H4>
235: Registered Requests?
236: </H4>
237: <P>
238: Returns whether there are requests registered in any of the lists or not
2.29 frystyk 239: <PRE>
240: extern BOOL HTNet_isEmpty (void);
2.1 frystyk 241: </PRE>
2.36 eric 242: <H3>
243: List Pending Queue
244: </H3>
245: <P>
246: Returns the list of pending requests that are waiting to become active. Returns
247: list of HTNet objects or NULL if error
2.1 frystyk 248: <PRE>
2.17 frystyk 249: extern HTList *HTNet_pendingQueue (void);
2.1 frystyk 250: </PRE>
2.36 eric 251: <H2>
2.37 frystyk 252: Creation and Deletion Methods
2.36 eric 253: </H2>
254: <P>
2.37 frystyk 255: The Net object is intended to live as long as the request is still active.
256: In that regard it is very similar to the <A HREF="HTReq.html">Request Object
257: </A>. However, the main difference is that a Net object represents a "thread"
258: in the Library and a request may have multiple "threads" - an example is
259: a FTP request which has a thread to handle the control connection and one
260: to handle the data connections.
261: <H3>
262: Create a new Object
263: </H3>
264: <P>
265: If we have more than HTMaxActive connections already then put this into the
266: pending queue, else start the request by calling the call back function
267: registered with this access method. Returns YES if OK, else NO
2.27 frystyk 268: <PRE>
2.28 frystyk 269: extern BOOL HTNet_newClient (HTRequest * request);
2.27 frystyk 270: </PRE>
2.36 eric 271: <P>
272: You can create a new HTNet object as a new request to be handled. If we have
273: more than HTMaxActive connections already then return NO. Returns YES if
274: OK, else NO
2.17 frystyk 275: <PRE>
2.39 frystyk 276: extern BOOL HTNet_newServer (HTRequest * request, HTNet * net, char *access);
2.26 frystyk 277: </PRE>
2.36 eric 278: <P>
2.27 frystyk 279: And you can create a plain new HTNet object using the following method:
2.26 frystyk 280: <PRE>
2.39 frystyk 281: extern HTNet * HTNet_new (SOCKET sockfd, HTRequest * request);
2.20 frystyk 282: </PRE>
2.36 eric 283: <H3>
2.37 frystyk 284: Duplicate an existing Object
2.36 eric 285: </H3>
286: <P>
287: Creates a new HTNet object as a duplicate of the same request. Returns YES
288: if OK, else NO.
2.20 frystyk 289: <PRE>
2.30 frystyk 290: extern HTNet * HTNet_dup (HTNet * src);
2.17 frystyk 291: </PRE>
2.37 frystyk 292: <H3>
293: Delete an Object
294: </H3>
295: <P>
296: Deletes the HTNet object from the list of active requests and calls any
297: registered call back functions IF not the status is HT_IGNORE. This is used
298: if we have internal requests that the app doesn't know about. We also see
299: if we have pending requests that can be started up now when we have a socket
300: free. The callback functions are called in the reverse order of which they
301: were registered (last one first);
302: <PRE>
303: extern BOOL HTNet_delete (HTNet * me, int status);
304: </PRE>
305: <H3>
306: Delete ALL HTNet Objects
307: </H3>
308: <P>
309: Deletes all HTNet object that might either be active or pending We DO NOT
310: call the call back functions - A crude way of saying goodbye!
311: <PRE>
312: extern BOOL HTNet_deleteAll (void);
313: </PRE>
2.36 eric 314: <H2>
2.38 frystyk 315: Net Class Methods
2.36 eric 316: </H2>
317: <H3>
318: Make an Object Wait
319: </H3>
320: <P>
321: Let a net object wait for a persistent socket. It will be launched from the
322: HTNet_delete() function when the socket gets free.
2.19 frystyk 323: <PRE>
324: extern BOOL HTNet_wait (HTNet *net);
325: </PRE>
2.36 eric 326: <H3>
327: Priority Management
328: </H3>
329: <P>
330: Each HTNet object is created with a priority which it inherits from the
331: <A HREF="HTReq.html">Request manager</A>. However, in some stuations it is
332: useful to be to change the current priority after the request has been started.
333: These two functions allow you to do this. The effect will show up the first
334: time (which might be imidiately) the socket blocks and control returns to
335: the event loop. Also have a look at how you can do this before the request
336: is issued in the <A HREF="HTReq.html">request manager</A>.
2.23 frystyk 337: <PRE>
338: extern HTPriority HTNet_priority (HTNet * net);
339: extern BOOL HTNet_setPriority (HTNet * net, HTPriority priority);
340: </PRE>
2.36 eric 341: <H3>
342: Persistent Connections
343: </H3>
344: <P>
345: You can set a Net object to handle persistent connections for example using
346: HTTP, NNTP, or FTP. You can control whether a Net object supports persistent
347: connections or not using this function.
2.33 frystyk 348: <PRE>
349: extern BOOL HTNet_persistent (HTNet * net);
350: </PRE>
2.36 eric 351: <P>
352: You can set or disable a Net object supporting persistent connections using
353: this function:
2.33 frystyk 354: <PRE>
355: extern BOOL HTNet_setPersistent (HTNet * net, BOOL persistent);
356: </PRE>
2.36 eric 357: <H3>
358: Kill a Request
359: </H3>
360: <P>
361: Kill the request by calling the call back function with a request for closing
362: the connection. Does not remove the object. This is done by HTNet_delete()
363: function which is called by the load routine. Returns OK if success, NO on
364: error
2.1 frystyk 365: <PRE>
2.17 frystyk 366: extern BOOL HTNet_kill (HTNet * me);
2.1 frystyk 367: </PRE>
2.36 eric 368: <H3>
369: Kill ALL requests
370: </H3>
371: <P>
372: Kills all registered (active+pending) requests by calling the call back function
373: with a request for closing the connection. We do not remove the HTNet object
374: as it is done by HTNet_delete(). Returns OK if success, NO on error
2.1 frystyk 375: <PRE>
2.17 frystyk 376: extern BOOL HTNet_killAll (void);
2.28 frystyk 377: </PRE>
2.36 eric 378: <H3>
379: Create Input and Output Streams
380: </H3>
381: <P>
382: You create the input stream and bind it to the channel using the following
383: methods. Please read the description in the
384: <A HREF="HTIOStream.html">HTIOStream module</A> on the parameters
385: <EM>target</EM>, <EM>param</EM>, and <EM>mode</EM>. Both methods return YES
386: if OK, else NO.
2.34 frystyk 387: <PRE>
388: extern HTInputStream * HTNet_getInput (HTNet * net, HTStream * target,
389: void * param, int mode);
390:
391: extern HTOutputStream * HTNet_getOutput (HTNet * net, void * param, int mode);
392: </PRE>
2.37 frystyk 393: <H3>
394: Net Context Descriptor
395: </H3>
2.36 eric 396: <P>
2.37 frystyk 397: Just like the <A HREF="../../../../WWW/Library/src/HTReq.html#context">request
398: object</A>, a net object can be assigned a context which keeps track of context
399: dependent information. The Library does not use this information nor does
400: it depend on it but it allows the application to customize a net object to
401: specific uses.
402: <PRE>extern BOOL HTNet_setContext (HTNet * net, void * context);
403: extern void * HTNet_context (HTNet * net);
404: </PRE>
2.36 eric 405: <H3>
406: Socket Descriptor
407: </H3>
2.28 frystyk 408: <PRE>
409: extern BOOL HTNet_setSocket (HTNet * net, SOCKET sockfd);
410: extern SOCKET HTNet_socket (HTNet * net);
2.17 frystyk 411: </PRE>
2.36 eric 412: <H3>
2.39 frystyk 413: The Request Object
414: </H3>
415: <P>
416: The <A HREF="HTReq.html">Request object</A> is normally set up
417: automatically but can be changed at a later time.
418: <PRE>
419: extern BOOL HTNet_setRequest (HTNet * net, HTRequest * request);
420: extern HTRequest * HTNet_request (HTNet * net);
421: </PRE>
422: <H3>
2.36 eric 423: The Transport Object
424: </H3>
425: <P>
2.34 frystyk 426: The <A HREF="HTTransport.html">transport object</A> is normally set up
427: automatically but can be changed at a later time.
2.17 frystyk 428: <PRE>
2.34 frystyk 429: extern BOOL HTNet_setTransport (HTNet * net, HTTransport * tp);
430: extern HTTransport * HTNet_transport (HTNet * net);
431: </PRE>
2.36 eric 432: <H3>
433: The Channel Object
434: </H3>
2.34 frystyk 435: <PRE>
436: extern BOOL HTNet_setChannel (HTNet * net, HTChannel * channel);
437: extern HTChannel * HTNet_channel (HTNet * net);
438: </PRE>
2.36 eric 439: <H3>
440: The Host Object
441: </H3>
2.34 frystyk 442: <PRE>
443: extern BOOL HTNet_setHost (HTNet * net, HTHost * host);
444: extern HTHost * HTNet_host (HTNet * net);
445: </PRE>
2.36 eric 446: <H3>
447: The DNS Object
448: </H3>
2.41 ! frystyk 449:
! 450: The DNS object keeps track of the DNS entries that we have already
! 451: checked out.
2.34 frystyk 452: <PRE>
453: extern BOOL HTNet_setDns (HTNet * net, HTdns * dns);
454: extern HTdns * HTNet_dns (HTNet * net);
455: </PRE>
2.41 ! frystyk 456:
! 457: If we are talking to a multi-homed host then we may
! 458: connect to any of the homes. In that case we store the current home in
! 459: the Net object so that we can query about it later.
! 460:
! 461: <PRE>
! 462: extern int HTNet_home (HTNet * net);
! 463: </PRE>
! 464:
2.34 frystyk 465: <PRE>
2.17 frystyk 466: #endif /* HTNET_H */
2.1 frystyk 467: </PRE>
2.36 eric 468: <P>
469: <HR>
2.34 frystyk 470: <ADDRESS>
2.41 ! frystyk 471: @(#) $Id: HTNet.html,v 2.41 1996/07/19 07:41:49 frystyk Exp $
2.34 frystyk 472: </ADDRESS>
2.36 eric 473: </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