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