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