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