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

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

Webmaster