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