Annotation of libwww/Library/src/HTDNS.html, revision 2.4
2.1 frystyk 1: <HTML>
2: <HEAD>
3: <TITLE>Domain Name Service Manager</TITLE>
2.4 ! frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 24-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
2.4 ! frystyk 105: whether we can keep the connection persistent or not.
2.1 frystyk 106:
107: <PRE>
2.4 ! frystyk 108: extern char * HTDNS_serverClass (HTdns * dns);
! 109: extern void HTDNS_setServerClass (HTdns * dns, char * s_class);
! 110:
! 111: extern int HTDNS_serverVersion (HTdns * dns);
! 112: extern void HTDNS_setServerVersion (HTdns * dns, int version);
! 113:
2.1 frystyk 114: typedef enum _HTTCPType {
2.4 ! frystyk 115: HT_TCP_PLAIN = 0x0, /* One request at a time */
! 116: HT_TCP_BATCH = 0x1, /* Use batch requests */
! 117: HT_TCP_INTERLEAVE = 0x2 /* Can we interleave requests? */
2.1 frystyk 118: } HTTCPType;
119:
2.4 ! frystyk 120: extern HTTCPType HTDNS_connection (HTdns * dns);
! 121: extern void HTDNS_setConnection (HTdns * dns, HTTCPType type);
2.1 frystyk 122: </PRE>
123:
124: <H3>Recalculating the Time-Weights on Multihomed Hosts</H3>
125:
126: On every connect to a multihomed host, the average connect time is updated
127: exponentially for all the entries.
128:
129: <PRE>
130: extern BOOL HTDNS_updateWeigths (HTdns *dns, int cur, time_t deltatime);
131: </PRE>
132:
133: <H3>Delete a host element from Cache</H3>
134:
135: This function deletes a single cache entry.
136:
137: <PRE>
138: extern BOOL HTDNS_delete (CONST char * host);
139: </PRE>
140:
141: <H3>Delete ALL host elements from Cache</H3>
142:
143: This function is called from <A HREF="HTAccess.html#Library">
144: HTLibTerminate</A>. It can be called at any point in time if the DNS
145: cache is going to be flushed.
146:
147: <PRE>
148: extern BOOL HTDNS_deleteAll (void);
149: </PRE>
150:
151: <H2>Resolver Functions</H2>
152:
153: These are the functions that resolve a host name
154:
155: <H3>Get Host By Socket</H3>
156:
157: This function should have been called HTGetHostByAddr but for
158: historical reasons this is not the case. <P>
159:
160: <PRE>
161: extern char * HTGetHostBySock PARAMS((int soc));
162: </PRE>
163:
164: <H3>Get Host By Name</H3>
165:
166: This function gets the address of the host and puts it in to the
167: socket structure. It maintains its own cache of connections so that
168: the communication to the Domain Name Server is minimized. Returns the
169: number of homes or -1 if error.
170:
171: <PRE>
172: extern int HTGetHostByName (struct _HTNet *net, char *host);
173: </PRE>
174:
175: <PRE>
176: #endif
177: </PRE>
178:
179: End of declaration file
180: </BODY>
181: </HTML>
Webmaster