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