Annotation of libwww/Library/src/HTNet.html, revision 2.54
2.1 frystyk 1: <HTML>
2: <HEAD>
2.50 frystyk 3: <TITLE>W3C Sample Code Library libwww HTNet Class</TITLE>
2.1 frystyk 4: </HEAD>
5: <BODY>
2.43 frystyk 6: <H1>
7: The Net Class
2.36 eric 8: </H1>
2.5 frystyk 9: <PRE>
10: /*
2.8 frystyk 11: ** (c) COPYRIGHT MIT 1995.
2.5 frystyk 12: ** Please first read the full copyright statement in the file COPYRIGH.
13: */
14: </PRE>
2.36 eric 15: <P>
2.38 frystyk 16: The Net class manages information related to a "thread" in libwww. As libwww
17: threads are not really threads but a notion of using interleaved, non-blocking
18: I/O for accessing data objects from the network (or local file system), they
19: can be used on any platform with or without support for native threads. In
20: the case where you have an application using real threads the Net class is
21: simply a object maintaining links to all other objects involved in serving
22: the request. If you are using the libwww pseudo threads then the Net object
23: contains enough information to stop and start a request based on which BSD
24: sockets are ready. In practise this is of course transparent to the application
25: - this is just to explain the difference.
26: <P>
27: When a <A HREF="HTReq.html">Request object</A> is passed to the Library ,
28: the core creates a new HTNet object pr <A HREF="HTChannl.html">channel</A>
29: used by the request. In many cases a request only uses a single
30: <A HREF="HTChannl.html">channel object </A>but for example FTP requests use
31: at least two - one for the control connection and one for the data connection.
32: <P>
33: You can find more information about the libwww pseudo thread model in the
34: <A HREF="../User/Architecture/"> Multithread Specifications</A>.
2.36 eric 35: <P>
36: This module is implemented by <A HREF="HTNet.c">HTNet.c</A>, and it is a
2.53 frystyk 37: part of the <A HREF="http://www.w3.org/Library/">W3C Sample Code Library</A>.
2.1 frystyk 38: <PRE>
2.17 frystyk 39: #ifndef HTNET_H
40: #define HTNET_H
2.1 frystyk 41: </PRE>
2.36 eric 42: <P>
43: The <CODE>HTNet</CODE> object is the core of the request queue management.
44: This object contains information about the socket descriptor, the input read
45: buffer etc. required to identify and service a request.
2.1 frystyk 46: <PRE>
2.18 frystyk 47: typedef struct _HTNet HTNet;
2.34 frystyk 48:
2.36 eric 49: #include "HTEvent.h"
2.34 frystyk 50: #include "HTReq.h"
2.44 frystyk 51: #include "HTResponse.h"
2.34 frystyk 52: #include "HTTrans.h"
53: #include "HTHost.h"
2.46 frystyk 54: #include "HTProt.h"
2.34 frystyk 55: #include "HTChannl.h"
56: #include "HTDNS.h"
2.1 frystyk 57: </PRE>
2.36 eric 58: <H2>
2.44 frystyk 59: <A NAME="callout">Generic BEFORE and AFTER Filter Management</A>
2.36 eric 60: </H2>
61: <P>
2.43 frystyk 62: Filter functions can be registered to be called <EM>before</EM> and
2.44 frystyk 63: <EM>after</EM> a request has either been started or has terminated. The
64: conditions for <I>BEFORE</I> and <I>AFTER</I> filters are not the same so
65: we maintain them independently. Filters can be registered globally or locally.
66: The global filters are registered directly by the Net Object (this module)
67: and the local filters are registered by the
68: <A HREF="HTReq.html">HTRequest</A> Object. However, both local and
69: global filters use the same regisration mechanism which we provide here.
70: <H3>
71: Filter Ordering
72: </H3>
73: <P>
74: Filters can be registered by anyone and as they are an often used mechanism
75: for introducing extensions in libwww, they are videly used to handle
76: authentication, redirection, etc. Many filters can be registered at once
77: and not all of the filters may know about the other filters. Therefore, it
78: is difficult to specify an absolute ordering by which the filters should
79: be called. Instead you can decide a relative order by which the filters should
80: be called. The order works pretty much like the Unix priority mechanism running
81: from <CODE>HT_FILTER_FIRST</CODE> to <CODE>HT_FILTER_LAST</CODE> having
82: <CODE>HT_FILTER_MIDDLE</CODE> being the "normal" case.
83: <PRE>
2.45 frystyk 84: typedef enum _HTFilterOrder {
85: HT_FILTER_FIRST = 0x0, /* 0 */
86: HT_FILTER_EARLY = 0x3FFF, /* 16383 */
87: HT_FILTER_MIDDLE = 0x7FFF, /* 32767 */
88: HT_FILTER_LATE = 0xBFFE, /* 49150 */
89: HT_FILTER_LAST = 0xFFFF /* 65535 */
90: } HTFilterOrder;
2.44 frystyk 91: </PRE>
92: <P>
93: In case multiple filters are registered with the same order then they are
94: called in the <I>inverse</I> order they were registered.
95: <H3>
96: Filter URL Templates
97: </H3>
98: <P>
99: Both <I>BEFORE</I> and <I>AFTER</I> filters can be registered with a <I>URL
100: template</I> in which case they are only called when the <I>Request URL</I>
101: matches the template. A template is simply a string which is matched against
102: the <I>Request URL</I>. The string can be terminated by a single
103: "<CODE>*</CODE>" in which case all strings matching the template up til the
104: "*" is considered a match. A template can be as short as the access scheme
105: which enmables a filter for a specific access method only, for example
106: "<CODE>http//<star></CODE>".
107: <H3>
108: BEFORE Filters
109: </H3>
110: <P>
111: A <I>BEFORE</I> filter is called whenever we issue a request and they have
112: been selected by the execution procedure. <I>BEFORE</I> filters are registered
113: with a <I>context</I> and a <I>filter order</I> by which they are to be called
114: and a <I>URL template</I> which may be NULL. In this case, the filter is
115: called on every request. The mode can be used by anybody to pass an extra
2.45 frystyk 116: parameter to a filter. This is not really OO thinking - but hey - this is
117: C ;-)
2.44 frystyk 118: <PRE>typedef int HTNetBefore (HTRequest * request, void * param, int mode);
119: </PRE>
120: <P>
121: You can add a <I>BEFORE</I> filter in the list provided by the caller. Several
122: filters can be registered in which case they are called with the filter ordering
123: in mind.
124: <PRE>
125: extern BOOL HTNetCall_addBefore (HTList * list, HTNetBefore * before,
126: const char * tmplate, void * param,
2.45 frystyk 127: HTFilterOrder order);
2.44 frystyk 128: </PRE>
129: <P>
130: You can also unregister all instances of a BEFORE filter from a list using
131: the following function
132: <PRE>
133: extern BOOL HTNetCall_deleteBefore (HTList * list, HTNetBefore * before);
134: </PRE>
135: <P>
136: You get rid of all BEFORE filters usign this function
137: <PRE>
138: extern BOOL HTNetCall_deleteBeforeAll (HTList * list);
139: </PRE>
140: <P>
141: The BEFORE filters are expected and called if appropriate every time we issue
142: a new request. Libwww calls the BEFORE filters in the order specified at
143: registration time. If a filter returns other than HT_OK then stop and return
144: immediately. Otherwise return what the last filter returns.
145: <PRE>
146: extern int HTNetCall_executeBefore (HTList * list, HTRequest * request);
147: </PRE>
148: <H3>
149: AFTER Filters
150: </H3>
151: <P>
152: An <I>AFTER</I> filter is called whenever we have terminated a request. That
153: is, on the way out from the <A HREF="HTProt.html">protocol module</A> and
154: back to the application. <I>AFTER</I> filters are registered with a
155: <I>context</I>, a <I>status</I>, a <I>filter order</I> by which they are
156: to be called and a <I>URL template</I> which may be NULL. The status of the
157: request may determine which filter to call. The set of possible values are
158: given below. An <I>AFTER</I> filter can be registered to handle one or more
159: of the codes.
2.17 frystyk 160: <DL>
2.36 eric 161: <DT>
162: HT_ERROR
163: <DD>
164: An error occured
165: <DT>
166: HT_LOADED
167: <DD>
168: The document was loaded
169: <DT>
170: HT_NO_DATA
171: <DD>
172: OK, but no data
173: <DT>
2.43 frystyk 174: HT_NO_ACCESS
175: <DD>
176: The request could not be succeeded due to lack of credentials
177: <DT>
178: HT_NO_PROXY_ACCESS
179: <DD>
180: The request could not be succeeded due to lack of credentials for accessing
181: an intermediate proxy
182: <DT>
2.36 eric 183: HT_RETRY
184: <DD>
185: Retry request after at a later time
186: <DT>
2.40 frystyk 187: HT_PERM_REDIRECT
2.36 eric 188: <DD>
2.40 frystyk 189: The request has been permanently redirected and we send back the new URL
190: <DT>
191: HT_TEMP_REDIRECT
192: <DD>
193: The request has been temporaryly redirected and we send back the new URL
2.36 eric 194: <DT>
195: HT_ALL
196: <DD>
197: All of above
2.17 frystyk 198: </DL>
2.36 eric 199: <P>
2.44 frystyk 200: A Protocol module can also in certain cases return a <CODE>HT_IGNORE </CODE>in
201: which case no filters are called
202: <PRE>
203: typedef int HTNetAfter (HTRequest * request, HTResponse * response,
204: void * param, int status);
205: </PRE>
206: <P>
207: You can register a AFTER filter in the list provided by the caller. Several
208: filters can be registered in which case they are called with the filter ordering
209: in mind.
2.1 frystyk 210: <PRE>
2.44 frystyk 211: extern BOOL HTNetCall_addAfter (HTList * list, HTNetAfter * after,
212: const char * tmplate, void * param,
2.45 frystyk 213: int status, HTFilterOrder order);
2.9 frystyk 214: </PRE>
2.36 eric 215: <P>
2.45 frystyk 216: You can either unregister all filters registered for a given status using
217: this function or the filter for all status codes.
2.9 frystyk 218: <PRE>
2.44 frystyk 219: extern BOOL HTNetCall_deleteAfter (HTList * list, HTNetAfter * after);
220: extern BOOL HTNetCall_deleteAfterStatus (HTList * list, int status);
2.1 frystyk 221: </PRE>
2.36 eric 222: <P>
2.44 frystyk 223: You can also delete all AFTER filters in list
2.24 frystyk 224: <PRE>
2.44 frystyk 225: extern BOOL HTNetCall_deleteAfterAll (HTList * list);
2.24 frystyk 226: </PRE>
2.36 eric 227: <P>
2.44 frystyk 228: This function calls all the AFTER filters in the order specified at registration
229: time and if it has the right status code and it's not <CODE>HT_IGNORE</CODE>.
230: We also check for any template and whether it matches or not. If a filter
231: returns other than HT_OK then stop and return immediately. Otherwise return
232: what the last filter returns.
2.24 frystyk 233: <PRE>
2.44 frystyk 234: extern int HTNetCall_executeAfter (HTList * list, HTRequest * request,
235: int status);
2.24 frystyk 236: </PRE>
2.44 frystyk 237: <H2>
2.45 frystyk 238: <A NAME="Global">Global BEFORE and AFTER Filter Management</A>
2.44 frystyk 239: </H2>
240: <P>
241: Global filters are inspected on every request (they do not have to be called
242: - only if the conditions match). You can also register filters locally in
243: the Request object.
244: <H4>
245: Global BEFORE Filters
246: </H4>
2.36 eric 247: <P>
2.44 frystyk 248: These are the methods to handle global <I>BEFORE</I> Filters.
2.24 frystyk 249: <PRE>
2.44 frystyk 250: extern BOOL HTNet_setBefore (HTList * list);
251:
252: extern HTList * HTNet_before (void);
2.42 frystyk 253:
2.44 frystyk 254: extern BOOL HTNet_addBefore (HTNetBefore * before, const char * tmplate,
2.45 frystyk 255: void * param, HTFilterOrder order);
2.42 frystyk 256:
2.44 frystyk 257: extern BOOL HTNet_deleteBefore (HTNetBefore * before);
2.24 frystyk 258: </PRE>
2.36 eric 259: <P>
2.44 frystyk 260: You can call both the local and the global BEFORE filters (if any)
261: <PRE>
262: extern int HTNet_executeBeforeAll (HTRequest * request);
263: </PRE>
264: <H4>
265: Global AFTER Filters
266: </H4>
267: <P>
268: These are the methods to handle global <I>AFTER</I> Filters.
2.10 frystyk 269: <PRE>
2.44 frystyk 270: extern BOOL HTNet_setAfter (HTList * list);
271:
272: extern HTList * HTNet_after (void);
273:
274: extern BOOL HTNet_addAfter (HTNetAfter * after, const char * tmplate,
2.45 frystyk 275: void * param, int status,
276: HTFilterOrder order);
2.42 frystyk 277:
2.44 frystyk 278: extern BOOL HTNet_deleteAfter (HTNetAfter * after);
2.42 frystyk 279:
2.44 frystyk 280: extern BOOL HTNet_deleteAfterStatus (int status);
281: </PRE>
282: <P>
283: You can call both the local and the global AFTER filters (if any)
284: <PRE>
285: extern int HTNet_executeAfterAll (HTRequest * request, int status);
2.10 frystyk 286: </PRE>
2.36 eric 287: <H2>
2.54 ! frystyk 288: <A NAME="Resources">Socket Resource Management</A>
2.36 eric 289: </H2>
290: <P>
291: The request queue ensures that no more than a fixed number of TCP connections
292: are open at the same time. If more requests are handed to the Library, they
293: are put into the pending queue and initiated when sockets become free.
294: <H3>
295: Number of Simultanous open TCP connections
296: </H3>
297: <P>
298: Set the max number of simultanous sockets. The default value is HT_MAX_SOCKETS
299: which is 6. The number of persistent connections depend on this value as
300: a deadlock can occur if all available sockets a persistent (see the
301: <A HREF="HTDNS.html">DNS Manager</A> for more information on setting the
302: number of persistent connections). The number of persistent connections can
303: never be more than the max number of sockets-2, so letting newmax=2 prevents
304: persistent sockets.
2.1 frystyk 305: <PRE>
2.17 frystyk 306: extern BOOL HTNet_setMaxSocket (int newmax);
307: extern int HTNet_maxSocket (void);
2.1 frystyk 308: </PRE>
2.36 eric 309: <H3>
2.43 frystyk 310: Socket Counters
311: </H3>
312: <PRE>
313: extern void HTNet_increaseSocket (void);
314: extern void HTNet_decreaseSocket (void);
315:
316: extern int HTNet_availableSockets (void);
317: </PRE>
318: <H3>
319: Persistent Socket Counters
320: </H3>
321: <PRE>
322: extern void HTNet_increasePersistentSocket (void);
323: extern void HTNet_decreasePersistentSocket (void);
324:
325: extern int HTNet_availablePersistentSockets (void);
326: </PRE>
327: <H3>
328: Any Ongoing Connections?
329: </H3>
330: <P>
331: Returns whether there are active requests. Idle persistent sockets do not
332: count as active.
333: <PRE>
334: extern BOOL HTNet_isIdle (void);
335: </PRE>
336: <H3>
2.36 eric 337: List Active Queue
338: </H3>
339: <P>
340: Returns the list of active requests that are currently having an open connection.
341: Returns list of HTNet objects or NULL if error.
2.1 frystyk 342: <PRE>
2.17 frystyk 343: extern HTList *HTNet_activeQueue (void);
2.22 frystyk 344: extern BOOL HTNet_idle (void);
2.29 frystyk 345: </PRE>
2.36 eric 346: <H3>
347: Are we Active?
348: </H3>
349: <P>
350: We have some small functions that tell whether there are registered requests
351: in the Net manager. There are tree queues: The <EM>active</EM>, the
352: <EM>pending</EM>, and the <EM>persistent</EM>. The <EM>active</EM> queue
353: is the set of requests that are actively sending or receiving data. The
354: <EM>pending</EM> is the requests that we have registered but which are waiting
355: for a free socket. The <EM>Persistent</EM> queue are requets that are waiting
356: to use the same socket in order to save network resoures (if the server
357: understands persistent connections).
358: <H4>
2.46 frystyk 359: Active Requests?
2.36 eric 360: </H4>
361: <P>
2.29 frystyk 362: Returns whether there are requests in the <EM>active</EM> queue or not
363: <PRE>
364: extern BOOL HTNet_idle (void);
365: </PRE>
2.36 eric 366: <H4>
367: Registered Requests?
368: </H4>
369: <P>
370: Returns whether there are requests registered in any of the lists or not
2.29 frystyk 371: <PRE>
372: extern BOOL HTNet_isEmpty (void);
2.46 frystyk 373: extern int HTNet_count (void);
2.1 frystyk 374: </PRE>
2.36 eric 375: <H3>
376: List Pending Queue
377: </H3>
378: <P>
379: Returns the list of pending requests that are waiting to become active. Returns
380: list of HTNet objects or NULL if error
2.1 frystyk 381: <PRE>
2.17 frystyk 382: extern HTList *HTNet_pendingQueue (void);
2.1 frystyk 383: </PRE>
2.36 eric 384: <H2>
2.37 frystyk 385: Creation and Deletion Methods
2.36 eric 386: </H2>
387: <P>
2.37 frystyk 388: The Net object is intended to live as long as the request is still active.
389: In that regard it is very similar to the <A HREF="HTReq.html">Request Object
390: </A>. However, the main difference is that a Net object represents a "thread"
391: in the Library and a request may have multiple "threads" - an example is
392: a FTP request which has a thread to handle the control connection and one
393: to handle the data connections.
394: <H3>
395: Create a new Object
396: </H3>
397: <P>
398: If we have more than HTMaxActive connections already then put this into the
399: pending queue, else start the request by calling the call back function
400: registered with this access method. Returns YES if OK, else NO
2.27 frystyk 401: <PRE>
2.28 frystyk 402: extern BOOL HTNet_newClient (HTRequest * request);
2.27 frystyk 403: </PRE>
2.36 eric 404: <P>
405: You can create a new HTNet object as a new request to be handled. If we have
406: more than HTMaxActive connections already then return NO. Returns YES if
407: OK, else NO
2.17 frystyk 408: <PRE>
2.39 frystyk 409: extern BOOL HTNet_newServer (HTRequest * request, HTNet * net, char *access);
2.26 frystyk 410: </PRE>
2.36 eric 411: <P>
2.27 frystyk 412: And you can create a plain new HTNet object using the following method:
2.26 frystyk 413: <PRE>
2.46 frystyk 414: extern HTNet * HTNet_new (HTRequest * request);
2.20 frystyk 415: </PRE>
2.36 eric 416: <H3>
2.37 frystyk 417: Duplicate an existing Object
2.36 eric 418: </H3>
419: <P>
420: Creates a new HTNet object as a duplicate of the same request. Returns YES
421: if OK, else NO.
2.20 frystyk 422: <PRE>
2.30 frystyk 423: extern HTNet * HTNet_dup (HTNet * src);
2.17 frystyk 424: </PRE>
2.37 frystyk 425: <H3>
2.43 frystyk 426: Launch a Net Object
427: </H3>
428: <P>
429: Start a Net obejct by calling the protocol module.
430: <PRE>extern BOOL HTNet_start (HTNet * net);
431: </PRE>
2.46 frystyk 432: <H3>
2.51 frystyk 433: Call a Net Event Handler
2.46 frystyk 434: </H3>
2.51 frystyk 435: <P>
436: This functions lets the caller play event manager as it can calls any event
437: handler with the event type and context passed to the function
2.46 frystyk 438: <PRE>
439: extern BOOL HTNet_execute (HTNet * net, HTEventType type);
2.49 frystyk 440:
441: extern HTEvent * HTNet_event (HTNet * net);
442: extern BOOL HTNet_setEventParam (HTNet * net, void * eventParam);
443: extern void * HTNet_eventParam (HTNet * net);
444: extern BOOL HTNet_setEventCallback(HTNet * net, HTEventCallback * cbf);
445: extern HTEventCallback * HTNet_eventCallback(HTNet * net);
2.46 frystyk 446: </PRE>
2.43 frystyk 447: <H3>
2.37 frystyk 448: Delete an Object
449: </H3>
450: <P>
451: Deletes the HTNet object from the list of active requests and calls any
452: registered call back functions IF not the status is HT_IGNORE. This is used
453: if we have internal requests that the app doesn't know about. We also see
454: if we have pending requests that can be started up now when we have a socket
2.43 frystyk 455: free. The filters are called in the reverse order of which they were registered
456: (last one first);
2.37 frystyk 457: <PRE>
458: extern BOOL HTNet_delete (HTNet * me, int status);
459: </PRE>
460: <H3>
461: Delete ALL HTNet Objects
462: </H3>
463: <P>
464: Deletes all HTNet object that might either be active or pending We DO NOT
465: call the call back functions - A crude way of saying goodbye!
466: <PRE>
467: extern BOOL HTNet_deleteAll (void);
468: </PRE>
2.36 eric 469: <H2>
2.38 frystyk 470: Net Class Methods
2.36 eric 471: </H2>
472: <H3>
473: Make an Object Wait
474: </H3>
475: <P>
476: Let a net object wait for a persistent socket. It will be launched from the
477: HTNet_delete() function when the socket gets free.
2.19 frystyk 478: <PRE>
479: extern BOOL HTNet_wait (HTNet *net);
480: </PRE>
2.36 eric 481: <H3>
482: Priority Management
483: </H3>
484: <P>
485: Each HTNet object is created with a priority which it inherits from the
486: <A HREF="HTReq.html">Request manager</A>. However, in some stuations it is
487: useful to be to change the current priority after the request has been started.
488: These two functions allow you to do this. The effect will show up the first
489: time (which might be imidiately) the socket blocks and control returns to
490: the event loop. Also have a look at how you can do this before the request
491: is issued in the <A HREF="HTReq.html">request manager</A>.
2.23 frystyk 492: <PRE>
493: extern HTPriority HTNet_priority (HTNet * net);
494: extern BOOL HTNet_setPriority (HTNet * net, HTPriority priority);
495: </PRE>
2.36 eric 496: <H3>
497: Persistent Connections
498: </H3>
499: <P>
500: You can set a Net object to handle persistent connections for example using
501: HTTP, NNTP, or FTP. You can control whether a Net object supports persistent
502: connections or not using this function.
2.33 frystyk 503: <PRE>
504: extern BOOL HTNet_persistent (HTNet * net);
505: </PRE>
2.36 eric 506: <P>
507: You can set or disable a Net object supporting persistent connections using
508: this function:
2.33 frystyk 509: <PRE>
2.43 frystyk 510: extern BOOL HTNet_setPersistent (HTNet * net,
511: BOOL persistent,
512: HTTransportMode mode);
2.33 frystyk 513: </PRE>
2.36 eric 514: <H3>
2.54 ! frystyk 515: Kill one or more Requests
2.36 eric 516: </H3>
2.54 ! frystyk 517: <H4>
! 518: Kill this request and all requests in the Pipeline
! 519: </H4>
2.36 eric 520: <P>
2.54 ! frystyk 521: When pipelining, it is not possible to kill a single request as we then loose
! 522: track of where we are in the pipe. It is therefore necessary to kill the
! 523: whole pipeline.
! 524: <PRE>
! 525: extern BOOL HTNet_killPipe (HTNet * net);
! 526: </PRE>
! 527: <H4>
! 528: Kill a single Request
! 529: </H4>
! 530: <P>
! 531: This is not often used anymore, consider using the pipeline version above.
2.36 eric 532: Kill the request by calling the call back function with a request for closing
533: the connection. Does not remove the object. This is done by HTNet_delete()
534: function which is called by the load routine. Returns OK if success, NO on
2.54 ! frystyk 535: error.
2.1 frystyk 536: <PRE>
2.17 frystyk 537: extern BOOL HTNet_kill (HTNet * me);
2.1 frystyk 538: </PRE>
2.54 ! frystyk 539: <H4>
! 540: Kill ALL Requests
! 541: </H4>
2.36 eric 542: <P>
2.54 ! frystyk 543: Kills <B>all</B> registered (active as well as pending) requests by calling
! 544: the call back function with a request for closing the connection. We do not
! 545: remove the HTNet object as it is done by HTNet_delete(). Returns OK if success,
! 546: NO on error
2.1 frystyk 547: <PRE>
2.17 frystyk 548: extern BOOL HTNet_killAll (void);
2.28 frystyk 549: </PRE>
2.36 eric 550: <H3>
551: Create Input and Output Streams
552: </H3>
553: <P>
554: You create the input stream and bind it to the channel using the following
555: methods. Please read the description in the
556: <A HREF="HTIOStream.html">HTIOStream module</A> on the parameters
557: <EM>target</EM>, <EM>param</EM>, and <EM>mode</EM>. Both methods return YES
558: if OK, else NO.
2.34 frystyk 559: <PRE>
2.46 frystyk 560: #if 0
2.34 frystyk 561: extern HTInputStream * HTNet_getInput (HTNet * net, HTStream * target,
562: void * param, int mode);
2.46 frystyk 563: #endif
564: extern HTOutputStream * HTNet_getOutput (HTNet * me, void * param, int mode);
2.34 frystyk 565: </PRE>
2.37 frystyk 566: <H3>
567: Net Context Descriptor
568: </H3>
2.36 eric 569: <P>
2.37 frystyk 570: Just like the <A HREF="../../../../WWW/Library/src/HTReq.html#context">request
571: object</A>, a net object can be assigned a context which keeps track of context
572: dependent information. The Library does not use this information nor does
573: it depend on it but it allows the application to customize a net object to
574: specific uses.
575: <PRE>extern BOOL HTNet_setContext (HTNet * net, void * context);
576: extern void * HTNet_context (HTNet * net);
577: </PRE>
2.36 eric 578: <H3>
579: Socket Descriptor
580: </H3>
2.28 frystyk 581: <PRE>
582: extern BOOL HTNet_setSocket (HTNet * net, SOCKET sockfd);
583: extern SOCKET HTNet_socket (HTNet * net);
2.17 frystyk 584: </PRE>
2.36 eric 585: <H3>
2.48 frystyk 586: Preemptive or Non-preemptive Access
587: </H3>
588: <P>
589: A access scheme is defined with a default for using either preemptive (blocking
590: I/O) or non-premitve (non-blocking I/O). This is basically a result of the
591: implementation of the protocol module itself. However, if non-blocking I/O
592: is the default then some times it is nice to be able to set the mode to blocking
593: instead. For example when loading the first document (the home page) then
594: blocking can be used instead of non-blocking.
595: <PRE>
596: extern BOOL HTNet_preemptive (HTNet * net);
597: </PRE>
598: <H3>
2.39 frystyk 599: The Request Object
600: </H3>
601: <P>
2.43 frystyk 602: The <A HREF="HTReq.html">Request object</A> is normally set up automatically
603: but can be changed at a later time.
2.39 frystyk 604: <PRE>
605: extern BOOL HTNet_setRequest (HTNet * net, HTRequest * request);
606: extern HTRequest * HTNet_request (HTNet * net);
607: </PRE>
2.46 frystyk 608: <H3>
2.51 frystyk 609: The Protocol Object
2.46 frystyk 610: </H3>
611: <PRE>
612: extern BOOL HTNet_setProtocol (HTNet * net, HTProtocol * protocol);
613: extern HTProtocol * HTNet_protocol (HTNet * net);
614: </PRE>
2.39 frystyk 615: <H3>
2.36 eric 616: The Transport Object
617: </H3>
618: <P>
2.51 frystyk 619: The <A HREF="HTTrans.html">transport object</A> is normally set up automatically
620: but can be changed at a later time.
2.17 frystyk 621: <PRE>
2.34 frystyk 622: extern BOOL HTNet_setTransport (HTNet * net, HTTransport * tp);
623: extern HTTransport * HTNet_transport (HTNet * net);
624: </PRE>
2.36 eric 625: <H3>
626: The Channel Object
627: </H3>
2.34 frystyk 628: <PRE>
629: extern BOOL HTNet_setChannel (HTNet * net, HTChannel * channel);
630: extern HTChannel * HTNet_channel (HTNet * net);
631: </PRE>
2.36 eric 632: <H3>
633: The Host Object
634: </H3>
2.34 frystyk 635: <PRE>
636: extern BOOL HTNet_setHost (HTNet * net, HTHost * host);
637: extern HTHost * HTNet_host (HTNet * net);
638: </PRE>
2.36 eric 639: <H3>
640: The DNS Object
641: </H3>
2.43 frystyk 642: <P>
643: The DNS object keeps track of the DNS entries that we have already checked
644: out.
2.34 frystyk 645: <PRE>
646: extern BOOL HTNet_setDns (HTNet * net, HTdns * dns);
647: extern HTdns * HTNet_dns (HTNet * net);
648: </PRE>
2.46 frystyk 649: <H3>
2.51 frystyk 650: Target for Input Read Stream
2.46 frystyk 651: </H3>
652: <PRE>
653: extern HTStream * HTNet_readStream(HTNet * net);
654: extern BOOL HTNet_setReadStream (HTNet * net, HTStream * stream);
655: </PRE>
2.53 frystyk 656: <H3>
657: Should we count Raw bytes?
658: </H3>
659: <P>
660: This functions can be used to determine whether bytes count should be managed
661: at the low level read stream or at a higher level. If the data transfer equals
662: the lifetime of a single document like for example in FTP or HTTP/1.0 then
663: this may be a reasonable thing to do.
664: <PRE>extern BOOL HTNet_setRawBytesCount (HTNet * net, BOOL mode);
665: extern BOOL HTNet_rawBytesCount (HTNet * net);
666: </PRE>
2.34 frystyk 667: <PRE>
2.17 frystyk 668: #endif /* HTNET_H */
2.1 frystyk 669: </PRE>
2.36 eric 670: <P>
671: <HR>
2.34 frystyk 672: <ADDRESS>
2.54 ! frystyk 673: @(#) $Id: HTNet.html,v 2.53 1998/09/24 19:48:51 frystyk Exp $
2.34 frystyk 674: </ADDRESS>
2.36 eric 675: </BODY></HTML>
Webmaster