Annotation of libwww/Library/src/HTNet.html, revision 2.17
2.1 frystyk 1: <HTML>
2: <HEAD>
2.17 ! frystyk 3: <TITLE>Asyncronous Socket Management</TITLE>
! 4: <!-- Changed by: Henrik Frystyk Nielsen, 12-Sep-1995 -->
2.1 frystyk 5: </HEAD>
6: <BODY>
2.2 frystyk 7:
2.17 ! frystyk 8: <H1>Asyncronous Socket Management</H1>
2.1 frystyk 9:
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>
16:
2.1 frystyk 17: This module contains the routines for handling the set of active
2.2 frystyk 18: sockets currently in use by the multithreaded clients. It is an
19: internal module to the Library, the application interface is
2.15 frystyk 20: implemented in the <A HREF="HTEvntrg.html">Event Module</A>. Look for
2.2 frystyk 21: more information in the <A
2.17 ! frystyk 22: HREF="http://www.w3.org/pub/WWW/Library/User/Architecture/">
2.2 frystyk 23: Multithread Specifications</A>. <P>
2.1 frystyk 24:
2.17 ! frystyk 25: This module is implemented by <A HREF="HTNet.c">HTNet.c</A>, and it is
! 26: a part of the <A HREF="http://www.w3.org/pub/WWW/Library/">W3C
! 27: Reference Library</A>.
2.1 frystyk 28:
29: <PRE>
2.17 ! frystyk 30: #ifndef HTNET_H
! 31: #define HTNET_H
! 32: #include "HTReq.h"
! 33: #include "HTEvntrg.h"
! 34: #include "HTSocket.h"
2.1 frystyk 35: </PRE>
36:
2.17 ! frystyk 37: <H2>The HTNet Object</H2>
2.1 frystyk 38:
2.17 ! frystyk 39: The <CODE>HTNet</CODE> object is the core of the request queue
! 40: management. This object contains information about the socket
! 41: descriptor, the input read buffer etc. required to identify and
! 42: service a request. <P>
2.1 frystyk 43:
44: <PRE>
2.17 ! frystyk 45: typedef struct _HTNet {
! 46: SOCKFD sockfd; /* Socket descripter */
! 47: SockA sock_addr; /* SockA is defined in tcp.h */
! 48: HTInputSocket * isoc; /* Input buffer */
! 49: HTStream * target; /* Target stream */
! 50: int addressCount; /* Attempts if multi-homed host */
! 51: time_t connecttime; /* Used on multihomed hosts */
! 52: long bytes_read; /* Bytes read from network */
! 53: BOOL preemtive; /* Eff result from Request and Protocol */
! 54: BOOL persistent; /* Do persistent connection? */
! 55: HTPriority priority; /* Priority of this request (event) */
! 56: HTEventCallBack * cbf; /* Library load routine */
! 57: HTRequest * request; /* Link back to request structure */
! 58: void * context; /* Protocol Specific context */
! 59: } HTNet;
! 60:
! 61: #define HTNet_bytesRead(me) ((me) ? (me)->bytes_read : -1)
2.1 frystyk 62: </PRE>
63:
2.17 ! frystyk 64: <H2>Request Termination Call Back Functions</H2>
! 65:
! 66: The termination callback functions is a set of functions that can be
! 67: registered by the application to be called when a request has
! 68: terminated. There can be more than one callback function which are
! 69: called on turn and each callback function can be associated with a
! 70: status code of the request. For example one callback function can be
! 71: registered for HT_LOADED, another for HT_ERROR etc.
! 72:
! 73: <H3>Register a Request Callback</H3>
2.2 frystyk 74:
2.17 ! frystyk 75: Register a call back function that is to be called on every
! 76: termination of a request. Several call back functions can be
! 77: registered in which case all of them are called in the reverse order
! 78: of which they were registered (last one first). The status signifies
! 79: which call back function to call depending of the result of the
! 80: request. This can be
2.1 frystyk 81:
2.17 ! frystyk 82: <DL>
! 83: <DT>HT_ERROR
! 84: <DD>An error occured
! 85: <DT>HT_LOADED
! 86: <DD>The document was loaded
! 87: <DT>HT_NO_DATA
! 88: <DD>OK, but no data
! 89: <DT>HT_RETRY
! 90: <DD>Retry request after at a later time
! 91: <DT>HT_ALL
! 92: <DD>All of above
! 93: </DL>
2.1 frystyk 94:
95: <PRE>
2.17 ! frystyk 96: typedef int HTNetCallBack (HTRequest * request, int status);
! 97:
! 98: extern BOOL HTNet_register (HTNetCallBack *cbf, int status);
2.9 frystyk 99: </PRE>
100:
2.17 ! frystyk 101: <H3>Unregister</H3>
2.9 frystyk 102:
2.17 ! frystyk 103: Unregister call back functions
2.9 frystyk 104:
105: <PRE>
2.17 ! frystyk 106: extern BOOL HTNet_unregister (HTNetCallBack *cbf);
! 107: extern BOOL HTNet_unregisterAll (void);
2.1 frystyk 108: </PRE>
109:
2.17 ! frystyk 110: <H2>Call the Call Back Functions</H2>
2.10 frystyk 111:
2.17 ! frystyk 112: Call all the call back functions registered in the list IF not the
! 113: status is HT_IGNORE. The callback functions are called in the reverse
! 114: order of which they were registered (last one first). Returns YES if
! 115: OK, else NO.
2.10 frystyk 116:
117: <PRE>
2.17 ! frystyk 118: extern BOOL HTNet_callback (HTRequest * me, int status);
2.10 frystyk 119: </PRE>
120:
2.17 ! frystyk 121: <H2>Request Queue</H2>
! 122:
! 123: The request queue ensures that no more than a fixed number of TCP
! 124: connections are open at the same time. If more requests are handed to
! 125: the Library, they are put into the pending queue and initiated when
! 126: sockets become free.
! 127:
! 128: <H3>Number of Simultanous open TCP connections</H3>
2.1 frystyk 129:
2.17 ! frystyk 130: Set the max number of simultanous sockets. The default value is
! 131: HT_MAX_SOCKETS which is 6.
2.1 frystyk 132:
133: <PRE>
2.17 ! frystyk 134: extern BOOL HTNet_setMaxSocket (int newmax);
! 135: extern int HTNet_maxSocket (void);
2.1 frystyk 136: </PRE>
137:
2.17 ! frystyk 138: <H2>List Active Queue</H2>
2.1 frystyk 139:
2.17 ! frystyk 140: Returns the list of active requests that are currently having an open
! 141: connection. Returns list of HTNet objects or NULL if error
2.1 frystyk 142:
143: <PRE>
2.17 ! frystyk 144: extern HTList *HTNet_activeQueue (void);
2.1 frystyk 145: </PRE>
146:
2.17 ! frystyk 147:
! 148: <H2>List Pending Queue</H2>
! 149:
! 150: Returns the list of pending requests that are waiting to become
! 151: active. Returns list of HTNet objects or NULL if error
! 152:
2.1 frystyk 153: <PRE>
2.17 ! frystyk 154: extern HTList *HTNet_pendingQueue (void);
2.1 frystyk 155: </PRE>
156:
2.17 ! frystyk 157: <H2>HTNet Object Creation and deletion methods</H2>
! 158:
! 159: These methods are used from within the Request Manager and are not
! 160: normally to be used outside the Library kernel.
! 161:
! 162: <H3>Create an Object</H3>
! 163:
! 164: Create a new HTNet object as a new request to be handled. If we have
! 165: more than HTMaxActive connections already then put this into the
! 166: pending queue, else start the request by calling the call back
! 167: function registered with this access method. Returns YES if OK, else
! 168: NO
! 169:
! 170: <PRE>
! 171: extern BOOL HTNet_new (HTRequest * request, HTPriority priority);
! 172: </PRE>
! 173:
! 174: <H3>Delete an Object</H3>
! 175:
! 176: Deletes the HTNet object from the list of active requests and calls
! 177: any registered call back functions IF not the status is HT_IGNORE.
! 178: This is used if we have internal requests that the app doesn't know
! 179: about. We also see if we have pending requests that can be started up
! 180: now when we have a socket free. The callback functions are called in
! 181: the reverse order of which they were registered (last one first)
2.1 frystyk 182:
183: <PRE>
2.17 ! frystyk 184: extern BOOL HTNet_delete (HTNet * me, int status);
2.1 frystyk 185: </PRE>
186:
2.17 ! frystyk 187: <H3>Delete ALL HTNet Objects</H3>
2.1 frystyk 188:
2.17 ! frystyk 189: Deletes all HTNet object that might either be active or pending We DO
! 190: NOT call the call back functions and we don't care about open socket
! 191: descriptors. A crude way of saying goodbye!
2.1 frystyk 192:
193: <PRE>
2.17 ! frystyk 194: extern BOOL HTNet_deleteAll (void);
2.1 frystyk 195: </PRE>
196:
2.17 ! frystyk 197: <H2>Killing requests</H2>
! 198:
! 199: For those who can't help it ;-)
! 200:
! 201: <H3>Kill a Request</H3>
2.1 frystyk 202:
2.17 ! frystyk 203: Kill the request by calling the call back function with a request for
! 204: closing the connection. Does not remove the object. This is done by
! 205: HTNet_delete() function which is called by the load routine. Returns
! 206: OK if success, NO on error
2.1 frystyk 207:
208: <PRE>
2.17 ! frystyk 209: extern BOOL HTNet_kill (HTNet * me);
2.1 frystyk 210: </PRE>
211:
2.17 ! frystyk 212: <H3>Kill ALL requests</H3>
2.1 frystyk 213:
2.17 ! frystyk 214: Kills all registered (active+pending) requests by calling the call
! 215: back function with a request for closing the connection. We do not
! 216: remove the HTNet object as it is done by HTNet_delete(). Returns OK
! 217: if success, NO on error
2.1 frystyk 218:
219: <PRE>
2.17 ! frystyk 220: extern BOOL HTNet_killAll (void);
! 221: </PRE>
2.1 frystyk 222:
2.17 ! frystyk 223: <PRE>
! 224: #endif /* HTNET_H */
2.1 frystyk 225: </PRE>
226:
2.17 ! frystyk 227: End of declaration module
2.1 frystyk 228: </BODY>
229: </HTML>
230:
231:
Webmaster