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