Annotation of libwww/Library/src/HTNet.html, revision 2.56

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 &nbsp;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.&nbsp;
                     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&nbsp;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//&lt;star&gt;</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.55      frystyk   409: extern BOOL HTNet_newServer (HTRequest * request);
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.56    ! frystyk   414: extern HTNet * HTNet_new (HTHost * host);
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.55      frystyk   424: extern BOOL HTNet_deleteDup (HTNet * dup);
2.17      frystyk   425: </PRE>
2.37      frystyk   426: <H3>
2.43      frystyk   427:   Launch a Net Object
                    428: </H3>
                    429: <P>
                    430: Start a Net obejct by calling the protocol module.
                    431: <PRE>extern BOOL HTNet_start (HTNet * net);
                    432: </PRE>
2.46      frystyk   433: <H3>
2.51      frystyk   434:   Call a Net Event Handler
2.46      frystyk   435: </H3>
2.51      frystyk   436: <P>
                    437: This functions lets the caller play event manager as it can calls any event
                    438: handler with the event type and context passed to the function
2.46      frystyk   439: <PRE>
                    440: extern BOOL HTNet_execute (HTNet * net, HTEventType type);
2.49      frystyk   441: 
                    442: extern HTEvent * HTNet_event (HTNet * net);
                    443: extern BOOL HTNet_setEventParam (HTNet * net, void * eventParam);
                    444: extern void * HTNet_eventParam (HTNet * net);
                    445: extern BOOL HTNet_setEventCallback(HTNet * net, HTEventCallback * cbf);
                    446: extern HTEventCallback * HTNet_eventCallback(HTNet * net);
2.46      frystyk   447: </PRE>
2.43      frystyk   448: <H3>
2.37      frystyk   449:   Delete an Object
                    450: </H3>
                    451: <P>
                    452: Deletes the HTNet object from the list of active requests and calls any
                    453: registered call back functions IF not the status is HT_IGNORE. This is used
                    454: if we have internal requests that the app doesn't know about. We also see
                    455: if we have pending requests that can be started up now when we have a socket
2.43      frystyk   456: free. The filters are called in the reverse order of which they were registered
                    457: (last one first);
2.37      frystyk   458: <PRE>
                    459: extern BOOL HTNet_delete (HTNet * me, int status);
                    460: </PRE>
                    461: <H3>
                    462:   Delete ALL HTNet Objects
                    463: </H3>
                    464: <P>
                    465: Deletes all HTNet object that might either be active or pending We DO NOT
                    466: call the call back functions - A crude way of saying goodbye!
                    467: <PRE>
                    468: extern BOOL HTNet_deleteAll (void);
                    469: </PRE>
2.36      eric      470: <H2>
2.38      frystyk   471:   Net Class Methods
2.36      eric      472: </H2>
                    473: <H3>
                    474:   Make an Object Wait
                    475: </H3>
                    476: <P>
                    477: Let a net object wait for a persistent socket. It will be launched from the
                    478: HTNet_delete() function when the socket gets free.
2.19      frystyk   479: <PRE>
                    480: extern BOOL HTNet_wait (HTNet *net);
                    481: </PRE>
2.36      eric      482: <H3>
                    483:   Priority Management
                    484: </H3>
                    485: <P>
                    486: Each HTNet object is created with a priority which it inherits from the
                    487: <A HREF="HTReq.html">Request manager</A>. However, in some stuations it is
                    488: useful to be to change the current priority after the request has been started.
                    489: These two functions allow you to do this. The effect will show up the first
                    490: time (which might be imidiately) the socket blocks and control returns to
                    491: the event loop. Also have a look at how you can do this before the request
                    492: is issued in the <A HREF="HTReq.html">request manager</A>.
2.23      frystyk   493: <PRE>
                    494: extern HTPriority HTNet_priority (HTNet * net);
                    495: extern BOOL HTNet_setPriority (HTNet * net, HTPriority priority);
                    496: </PRE>
2.36      eric      497: <H3>
                    498:   Persistent Connections
                    499: </H3>
                    500: <P>
                    501: You can set a Net object to handle persistent connections for example using
                    502: HTTP, NNTP, or FTP. You can control whether a Net object supports persistent
                    503: connections or not using this function.
2.33      frystyk   504: <PRE>
                    505: extern BOOL HTNet_persistent (HTNet * net);
                    506: </PRE>
2.36      eric      507: <P>
                    508: You can set or disable a Net object supporting persistent connections using
                    509: this function:
2.33      frystyk   510: <PRE>
2.43      frystyk   511: extern BOOL HTNet_setPersistent (HTNet *           net,
                    512:                                  BOOL              persistent,
                    513:                                  HTTransportMode   mode);
2.33      frystyk   514: </PRE>
2.36      eric      515: <H3>
2.54      frystyk   516:   Kill one or more Requests
2.36      eric      517: </H3>
2.54      frystyk   518: <H4>
                    519:   Kill this request and all requests in the Pipeline
                    520: </H4>
2.36      eric      521: <P>
2.54      frystyk   522: When pipelining, it is not possible to kill a single request as we then loose
                    523: track of where we are in the pipe. It is therefore necessary to kill the
                    524: whole pipeline.
                    525: <PRE>
                    526: extern BOOL HTNet_killPipe (HTNet * net);
                    527: </PRE>
                    528: <H4>
                    529:   Kill a single Request
                    530: </H4>
                    531: <P>
                    532: This is not often used anymore, consider using the pipeline version above.
2.36      eric      533: Kill the request by calling the call back function with a request for closing
                    534: the connection. Does not remove the object. This is done by HTNet_delete()
                    535: function which is called by the load routine. Returns OK if success, NO on
2.54      frystyk   536: error.
2.1       frystyk   537: <PRE>
2.17      frystyk   538: extern BOOL HTNet_kill (HTNet * me);
2.1       frystyk   539: </PRE>
2.54      frystyk   540: <H4>
                    541:   Kill ALL Requests
                    542: </H4>
2.36      eric      543: <P>
2.54      frystyk   544: Kills <B>all</B> registered (active as well as pending) requests by calling
                    545: the call back function with a request for closing the connection. We do not
                    546: remove the HTNet object as it is done by HTNet_delete(). Returns OK if success,
                    547: NO on error
2.1       frystyk   548: <PRE>
2.17      frystyk   549: extern BOOL HTNet_killAll (void);
2.28      frystyk   550: </PRE>
2.36      eric      551: <H3>
                    552:   Create Input and Output Streams
                    553: </H3>
                    554: <P>
                    555: You create the input stream and bind it to the channel using the following
                    556: methods. Please read the description in the
                    557: <A HREF="HTIOStream.html">HTIOStream module</A> on the parameters
                    558: <EM>target</EM>, <EM>param</EM>, and <EM>mode</EM>. Both methods return YES
                    559: if OK, else NO.
2.34      frystyk   560: <PRE>
2.46      frystyk   561: #if 0
2.34      frystyk   562: extern HTInputStream * HTNet_getInput (HTNet * net, HTStream * target,
                    563:                                       void * param, int mode);
2.46      frystyk   564: #endif
                    565: extern HTOutputStream * HTNet_getOutput (HTNet * me, void * param, int mode);
2.34      frystyk   566: </PRE>
2.37      frystyk   567: <H3>
                    568:   Net Context Descriptor
                    569: </H3>
2.36      eric      570: <P>
2.37      frystyk   571: Just like the <A HREF="../../../../WWW/Library/src/HTReq.html#context">request
                    572: object</A>, a net object can be assigned a context which keeps track of context
                    573: dependent information. The Library does not use this information nor does
                    574: it depend on it but it allows the application to customize a net object to
                    575: specific uses.
                    576: <PRE>extern BOOL HTNet_setContext (HTNet * net, void * context);
                    577: extern void * HTNet_context (HTNet * net);
                    578: </PRE>
2.36      eric      579: <H3>
                    580:   Socket Descriptor
                    581: </H3>
2.28      frystyk   582: <PRE>
                    583: extern BOOL HTNet_setSocket (HTNet * net, SOCKET sockfd);
                    584: extern SOCKET HTNet_socket (HTNet * net);
2.17      frystyk   585: </PRE>
2.36      eric      586: <H3>
2.48      frystyk   587:   Preemptive or Non-preemptive Access
                    588: </H3>
                    589: <P>
                    590: A access scheme is defined with a default for using either preemptive (blocking
                    591: I/O) or non-premitve (non-blocking I/O). This is basically a result of the
                    592: implementation of the protocol module itself. However, if non-blocking I/O
                    593: is the default then some times it is nice to be able to set the mode to blocking
                    594: instead. For example when loading the first document (the home page) then
                    595: blocking can be used instead of non-blocking.
                    596: <PRE>
                    597: extern BOOL HTNet_preemptive (HTNet * net);
                    598: </PRE>
                    599: <H3>
2.39      frystyk   600:   The Request Object
                    601: </H3>
                    602: <P>
2.43      frystyk   603: The <A HREF="HTReq.html">Request object</A> is normally set up automatically
                    604: but can be changed at a later time.
2.39      frystyk   605: <PRE>
                    606: extern BOOL HTNet_setRequest (HTNet * net, HTRequest * request);
                    607: extern HTRequest * HTNet_request (HTNet * net);
                    608: </PRE>
2.46      frystyk   609: <H3>
2.51      frystyk   610:   The Protocol Object
2.46      frystyk   611: </H3>
                    612: <PRE>
                    613: extern BOOL HTNet_setProtocol (HTNet * net, HTProtocol * protocol);
                    614: extern HTProtocol * HTNet_protocol (HTNet * net);
                    615: </PRE>
2.39      frystyk   616: <H3>
2.36      eric      617:   The Transport Object
                    618: </H3>
                    619: <P>
2.51      frystyk   620: The <A HREF="HTTrans.html">transport object</A> is normally set up automatically
                    621: but can be changed at a later time.
2.17      frystyk   622: <PRE>
2.34      frystyk   623: extern BOOL HTNet_setTransport (HTNet * net, HTTransport * tp);
                    624: extern HTTransport * HTNet_transport (HTNet * net);
                    625: </PRE>
2.36      eric      626: <H3>
                    627:   The Channel Object
                    628: </H3>
2.34      frystyk   629: <PRE>
                    630: extern BOOL HTNet_setChannel (HTNet * net, HTChannel * channel);
                    631: extern HTChannel * HTNet_channel (HTNet * net);
                    632: </PRE>
2.36      eric      633: <H3>
                    634:   The Host Object
                    635: </H3>
2.34      frystyk   636: <PRE>
                    637: extern BOOL HTNet_setHost (HTNet * net, HTHost * host);
                    638: extern HTHost * HTNet_host (HTNet * net);
                    639: </PRE>
2.36      eric      640: <H3>
                    641:   The DNS Object
                    642: </H3>
2.43      frystyk   643: <P>
                    644: The DNS object keeps track of the DNS entries that we have already checked
                    645: out.
2.34      frystyk   646: <PRE>
                    647: extern BOOL HTNet_setDns (HTNet * net, HTdns * dns);
                    648: extern HTdns * HTNet_dns (HTNet * net);
                    649: </PRE>
2.46      frystyk   650: <H3>
2.51      frystyk   651:   Target for Input Read Stream
2.46      frystyk   652: </H3>
                    653: <PRE>
                    654: extern HTStream * HTNet_readStream(HTNet * net);
                    655: extern BOOL HTNet_setReadStream (HTNet * net, HTStream * stream);
                    656: </PRE>
2.53      frystyk   657: <H3>
                    658:   Should we count Raw bytes?
                    659: </H3>
                    660: <P>
                    661: This functions can be used to determine whether bytes count should be managed
                    662: at the low level read stream or at a higher level. If the data transfer equals
                    663: the lifetime of a single document like for example in FTP or HTTP/1.0 then
                    664: this may be a reasonable thing to do.
                    665: <PRE>extern BOOL HTNet_setRawBytesCount (HTNet * net, BOOL mode);
                    666: extern BOOL HTNet_rawBytesCount (HTNet * net);
                    667: </PRE>
2.34      frystyk   668: <PRE>
2.17      frystyk   669: #endif /* HTNET_H */
2.1       frystyk   670: </PRE>
2.36      eric      671: <P>
                    672:   <HR>
2.34      frystyk   673: <ADDRESS>
2.56    ! frystyk   674:   @(#) $Id: HTNet.html,v 2.55 1998/12/15 05:34:28 frystyk Exp $
2.34      frystyk   675: </ADDRESS>
2.36      eric      676: </BODY></HTML>

Webmaster