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