Annotation of libwww/Library/src/HTDNS.html, revision 2.9
2.1 frystyk 1: <HTML>
2: <HEAD>
3: <TITLE>Domain Name Service Manager</TITLE>
2.7 frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 15-Nov-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
2.9 ! frystyk 39: #include "sysdep.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>
2.8 frystyk 69: extern SOCKET HTDNS_socket (HTdns *dns);
70: extern BOOL HTDNS_setSocket (HTdns *dns, SOCKET socket);
2.5 frystyk 71: extern void HTDNS_clearActive (HTdns *dns);
72: extern int HTDNS_socketCount (void);
2.1 frystyk 73: </PRE>
74:
75: <H3>Persistent Connection Timeouts</H3>
76:
77: When should we drop a socket. The default value is 1h
78:
79: <PRE>
80: extern time_t HTDNS_sockTimeout (time_t timeout);
81: extern void HTDNS_setSockTimeout (time_t timeout);
82: </PRE>
83:
84: <H3>Persistent Connection Expiration</H3>
85:
86: Absolute value of when this socket will expire. Default value can be
87: set with the function HTDNS_setSockTimeout and is normally 1 h.
88:
89: <PRE>
2.6 frystyk 90: extern HTEventCallback HTDNS_closeSocket;
2.2 frystyk 91:
2.1 frystyk 92: extern void HTDNS_setSockExpires (HTdns * dns, time_t expires);
93: extern time_t HTDNS_sockExpires (HTdns * dns);
94: </PRE>
95:
96: <H3>Set the Server Class and Type</H3>
97:
98: Define the <EM>server class</EM> of the server at the other end. A
99: class is a generic description of the protocol which is exactly like
100: the access method in a URL, for example "http" etc. The <EM>server
101: version</EM> is a finer distinction (sub-class) between various
102: versions of the server class, for example HTTP/0.9, HTTP/1.1 etc. The
103: server version is a bit flag that the protocol module can define on
104: its own. That way we don't have to change this module when registering
105: a new protocol module. The <EM>server type</EM> is a description of
2.4 frystyk 106: whether we can keep the connection persistent or not.
2.1 frystyk 107:
108: <PRE>
2.4 frystyk 109: extern char * HTDNS_serverClass (HTdns * dns);
110: extern void HTDNS_setServerClass (HTdns * dns, char * s_class);
111:
112: extern int HTDNS_serverVersion (HTdns * dns);
113: extern void HTDNS_setServerVersion (HTdns * dns, int version);
114:
2.1 frystyk 115: typedef enum _HTTCPType {
2.4 frystyk 116: HT_TCP_PLAIN = 0x0, /* One request at a time */
117: HT_TCP_BATCH = 0x1, /* Use batch requests */
118: HT_TCP_INTERLEAVE = 0x2 /* Can we interleave requests? */
2.1 frystyk 119: } HTTCPType;
120:
2.4 frystyk 121: extern HTTCPType HTDNS_connection (HTdns * dns);
122: extern void HTDNS_setConnection (HTdns * dns, HTTCPType type);
2.1 frystyk 123: </PRE>
124:
125: <H3>Recalculating the Time-Weights on Multihomed Hosts</H3>
126:
127: On every connect to a multihomed host, the average connect time is updated
128: exponentially for all the entries.
129:
130: <PRE>
131: extern BOOL HTDNS_updateWeigths (HTdns *dns, int cur, time_t deltatime);
132: </PRE>
133:
134: <H3>Delete a host element from Cache</H3>
135:
136: This function deletes a single cache entry.
137:
138: <PRE>
2.9 ! frystyk 139: extern BOOL HTDNS_delete (const char * host);
2.1 frystyk 140: </PRE>
141:
142: <H3>Delete ALL host elements from Cache</H3>
143:
144: This function is called from <A HREF="HTAccess.html#Library">
145: HTLibTerminate</A>. It can be called at any point in time if the DNS
146: cache is going to be flushed.
147:
148: <PRE>
149: extern BOOL HTDNS_deleteAll (void);
150: </PRE>
151:
152: <H2>Resolver Functions</H2>
153:
154: These are the functions that resolve a host name
155:
156: <H3>Get Host By Socket</H3>
157:
158: This function should have been called HTGetHostByAddr but for
159: historical reasons this is not the case. <P>
160:
161: <PRE>
2.7 frystyk 162: extern char * HTGetHostBySock (int soc);
2.1 frystyk 163: </PRE>
164:
165: <H3>Get Host By Name</H3>
166:
167: This function gets the address of the host and puts it in to the
168: socket structure. It maintains its own cache of connections so that
169: the communication to the Domain Name Server is minimized. Returns the
170: number of homes or -1 if error.
171:
172: <PRE>
173: extern int HTGetHostByName (struct _HTNet *net, char *host);
174: </PRE>
175:
176: <PRE>
177: #endif
178: </PRE>
179:
180: End of declaration file
181: </BODY>
182: </HTML>
Webmaster