Annotation of libwww/Library/src/HTDNS.html, revision 2.1
2.1 ! frystyk 1: <HTML>
! 2: <HEAD>
! 3: <TITLE>Domain Name Service Manager</TITLE>
! 4: <!-- Changed by: Henrik Frystyk Nielsen, 16-Sep-1995 -->
! 5: </HEAD>
! 6: <BODY>
! 7:
! 8: <H1>Domain Name Service Manager</H1>
! 9:
! 10: <PRE>
! 11: /*
! 12: ** (c) COPYRIGHT MIT 1995.
! 13: ** Please first read the full copyright statement in the file COPYRIGH.
! 14: */
! 15: </PRE>
! 16:
! 17: This module has the common code for handling DNS access. It maintains
! 18: a cache of all visited hosts so that subsequent connects to the same
! 19: host doesn't imply a new request to the DNS every time. <P>
! 20:
! 21: Multihomed hosts are treated specially in that the time spend on every
! 22: connect is measured and kept in the cache. On the next request to the
! 23: same host, the IP-address with the lowest average connect time is
! 24: chosen. If one IP-address fails completely, e.g. <EM>connection
! 25: refused</EM> then it disabled and HTDoConnect tries one of the other
! 26: IP-addresses to the same host.<P>
! 27:
! 28: If the connect fails in the case of at single-homed host then the
! 29: entry is removed from the cache and HTDoConnect tries again asking the
! 30: DNS. <P>
! 31:
! 32: This module is implemented by <A HREF="HTDNS.c">HTDNS.c</A>, and it is
! 33: a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C
! 34: Reference Library</A>.
! 35:
! 36: <PRE>
! 37: #ifndef HTDNS_H
! 38: #define HTDNS_H
! 39: #include "tcp.h"
! 40: </PRE>
! 41:
! 42: <H2>The DNS Object</H2>
! 43:
! 44: The DNS object contains information obtained from the DNS system but
! 45: in addition it stores known information about the remote server, for
! 46: example the type (HTTP/1.0, HTTP/1.1, FT etc.) along with information
! 47: on how the connections can be used (if it supports persistent TCP
! 48: connections, interleaved access etc.)
! 49:
! 50: <PRE>
! 51: typedef struct _HTdns HTdns;
! 52: </PRE>
! 53:
! 54: <H2>Cache Timeouts</H2>
! 55:
! 56: When to remove an entry in the cache. The default value is 48h.
! 57:
! 58: <PRE>
! 59: extern void HTDNS_setTimeout (time_t timeout);
! 60: extern time_t HTDNS_timeout (time_t timeout);
! 61: </PRE>
! 62:
! 63: <H2>Object Methods</H2>
! 64:
! 65: <H3>Persistent Sockets</H3>
! 66:
! 67: <PRE>
! 68: extern SOCKFD HTDNS_socket (HTdns *dns);
! 69: extern void HTDNS_setSocket (HTdns *dns, SOCKFD socket);
! 70: extern void HTDNS_clearActive (HTdns *dns);
! 71: </PRE>
! 72:
! 73: <H3>Persistent Connection Timeouts</H3>
! 74:
! 75: When should we drop a socket. The default value is 1h
! 76:
! 77: <PRE>
! 78: extern time_t HTDNS_sockTimeout (time_t timeout);
! 79: extern void HTDNS_setSockTimeout (time_t timeout);
! 80: </PRE>
! 81:
! 82: <H3>Persistent Connection Expiration</H3>
! 83:
! 84: Absolute value of when this socket will expire. Default value can be
! 85: set with the function HTDNS_setSockTimeout and is normally 1 h.
! 86:
! 87: <PRE>
! 88: extern void HTDNS_setSockExpires (HTdns * dns, time_t expires);
! 89: extern time_t HTDNS_sockExpires (HTdns * dns);
! 90: </PRE>
! 91:
! 92: <H3>Set the Server Class and Type</H3>
! 93:
! 94: Define the <EM>server class</EM> of the server at the other end. A
! 95: class is a generic description of the protocol which is exactly like
! 96: the access method in a URL, for example "http" etc. The <EM>server
! 97: version</EM> is a finer distinction (sub-class) between various
! 98: versions of the server class, for example HTTP/0.9, HTTP/1.1 etc. The
! 99: server version is a bit flag that the protocol module can define on
! 100: its own. That way we don't have to change this module when registering
! 101: a new protocol module. The <EM>server type</EM> is a description of
! 102: whether we can keep the connection persistsent or not.
! 103:
! 104: <PRE>
! 105: typedef enum _HTTCPType {
! 106: HT_TCP_SINGLE = 0, /* Plain old TCP one timer */
! 107: HT_TCP_MULTI, /* Multiple requests pr socket */
! 108: HT_TCP_INTERLEAVE /* Can we interleave requests? */
! 109: } HTTCPType;
! 110:
! 111: extern char *HTDNS_serverClass (HTdns *dns);
! 112: extern void HTDNS_setServerClass (HTdns *dns, char *class);
! 113:
! 114: extern int HTDNS_serverVersion (HTdns *dns);
! 115: extern void HTDNS_setServerVersion (HTdns *dns, int version, HTTCPType type);
! 116: </PRE>
! 117:
! 118: <H3>Recalculating the Time-Weights on Multihomed Hosts</H3>
! 119:
! 120: On every connect to a multihomed host, the average connect time is updated
! 121: exponentially for all the entries.
! 122:
! 123: <PRE>
! 124: extern BOOL HTDNS_updateWeigths (HTdns *dns, int cur, time_t deltatime);
! 125: </PRE>
! 126:
! 127: <H3>Delete a host element from Cache</H3>
! 128:
! 129: This function deletes a single cache entry.
! 130:
! 131: <PRE>
! 132: extern BOOL HTDNS_delete (CONST char * host);
! 133: </PRE>
! 134:
! 135: <H3>Delete ALL host elements from Cache</H3>
! 136:
! 137: This function is called from <A HREF="HTAccess.html#Library">
! 138: HTLibTerminate</A>. It can be called at any point in time if the DNS
! 139: cache is going to be flushed.
! 140:
! 141: <PRE>
! 142: extern BOOL HTDNS_deleteAll (void);
! 143: </PRE>
! 144:
! 145: <H2>Resolver Functions</H2>
! 146:
! 147: These are the functions that resolve a host name
! 148:
! 149: <H3>Get Host By Socket</H3>
! 150:
! 151: This function should have been called HTGetHostByAddr but for
! 152: historical reasons this is not the case. <P>
! 153:
! 154: <PRE>
! 155: extern char * HTGetHostBySock PARAMS((int soc));
! 156: </PRE>
! 157:
! 158: <H3>Get Host By Name</H3>
! 159:
! 160: This function gets the address of the host and puts it in to the
! 161: socket structure. It maintains its own cache of connections so that
! 162: the communication to the Domain Name Server is minimized. Returns the
! 163: number of homes or -1 if error.
! 164:
! 165: <PRE>
! 166: extern int HTGetHostByName (struct _HTNet *net, char *host);
! 167: </PRE>
! 168:
! 169: <PRE>
! 170: #endif
! 171: </PRE>
! 172:
! 173: End of declaration file
! 174: </BODY>
! 175: </HTML>
Webmaster