Annotation of libwww/Library/src/HTDNS.html, revision 2.21
2.1 frystyk 1: <HTML>
2: <HEAD>
2.13 frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 2-Apr-1996 -->
2.17 frystyk 4: <TITLE>W3C Sample Code Library libwww DNS Class</TITLE>
2.1 frystyk 5: </HEAD>
6: <BODY>
2.13 frystyk 7: <H1>
8: Domain Name Service Class
9: </H1>
2.1 frystyk 10: <PRE>
11: /*
12: ** (c) COPYRIGHT MIT 1995.
13: ** Please first read the full copyright statement in the file COPYRIGH.
14: */
15: </PRE>
2.13 frystyk 16: <P>
17: The DNS Class defines generic access to the DNS system. It maintains
18: a cache of all visited hosts so that subsequent connects to the same host
19: doesn't imply a new request to the DNS every time. Multihomed hosts are treated
20: specially in that the time spend on every connect is measured and kept in
21: the cache. On the next request to the same host, the IP-address with the
22: lowest average connect time is chosen. If one IP-address fails completely,
23: e.g. <EM>connection refused</EM> then it disabled and HTDoConnect tries one
24: of the other IP-addresses to the same host.
25: <P>
26: Every entry in the cache has its own time to live (TTL) and hence the cache
27: manages its own automatic garbage collection. Currently the TTL is <B>not</B>
28: bound to the DNS records which should be changed. You can set the DNS object
29: TTL
30: <P>
31: This module is implemented by <A HREF="HTDNS.c">HTDNS.c</A>, and it is a
2.19 frystyk 32: part of the <A HREF="http://www.w3.org/Library/"> W3C Sample Code Library</A>.
2.1 frystyk 33: <PRE>
34: #ifndef HTDNS_H
35: #define HTDNS_H
2.13 frystyk 36:
2.21 ! vbancrof 37: #ifdef __cplusplus
! 38: extern "C" {
! 39: #endif
2.1 frystyk 40: </PRE>
2.13 frystyk 41: <PRE>typedef struct _HTdns HTdns;
2.1 frystyk 42: </PRE>
2.13 frystyk 43: <H2>
44: DNS Cache Expiration Time
45: </H2>
46: <P>
2.19 frystyk 47: When to remove an entry in the DNS cache. We maintain our own DNS cache as
48: we keep track of the connect time, pick the fastet host on multi-homed hosts
49: etc. However we <STRONG>DO NOT HONOR DNS TTL Records</STRONG> which is the
50: reason for why the expiration must be faily short (the default value is 30
51: mins), so that it doesn't collide with the DNS mechanism for timing out DNS
52: records befoew swapping IP addresses around.
2.1 frystyk 53: <PRE>
54: extern void HTDNS_setTimeout (time_t timeout);
55: extern time_t HTDNS_timeout (time_t timeout);
56: </PRE>
2.13 frystyk 57: <H2>
58: Creation and Deletion Methods
59: </H2>
60: <H3>
61: Add a DNS Object
62: </H3>
63: <P>
64: Add an element to the cache of visited hosts. The <CODE>homes</CODE> variable
65: indicates the number of IP addresses found when looking up the name. A host
66: name must <B>NOT</B> contain a port number.
67: <PRE>
68: extern HTdns * HTDNS_add (HTList * list, struct hostent * element,
69: char * host, int * homes);
70: </PRE>
71: <H3>
72: Delete a DNS object
73: </H3>
74: <P>
75: This function flushes the DNS object from the cache and frees up memory
2.1 frystyk 76: <PRE>
2.9 frystyk 77: extern BOOL HTDNS_delete (const char * host);
2.1 frystyk 78: </PRE>
2.13 frystyk 79: <H3>
80: Delete ALL DNS objects
81: </H3>
82: <P>
2.19 frystyk 83: This function is called from <A HREF="HTLib.html"> HTLibTerminate</A>. It
84: can be called at any point in time if the DNS cache is going to be flushed.
2.1 frystyk 85: <PRE>
86: extern BOOL HTDNS_deleteAll (void);
87: </PRE>
2.13 frystyk 88: <H2>
89: DNS Class Methods
90: </H2>
91: <H3>
92: Recalculating the Time Weights on Multihomed Host
93: </H3>
94: <P>
95: On every connect to a multihomed host, the average connect time is updated
96: exponentially for all the entries.
97: <PRE>
2.16 frystyk 98: extern BOOL HTDNS_updateWeigths (HTdns *dns, int cur, ms_t deltatime);
2.13 frystyk 99: </PRE>
100: <H2>
2.20 duerst 101: IDN (Internationalized Domain Names) Functions
102: </H2>
103: <H3>
104: Calculate ACE (punycode) from UTF-8 encoded IDN
105: </H3>
106: <P>
107: Converts to ACE (Ascii-compatible encoding, punycode) from an
108: Internationalized Domain name. %hh-escaping in domain name is
109: accepted for backwards compatibility. Returns 0 if successful.
110: </P>
111: <PRE>
112: extern int HTACEfromUTF8 (char *hostUTF8, char *punycode, size_t punyLength);
113: </PRE>
114: <H2>
2.13 frystyk 115: Resolver Functions
116: </H2>
117: <P>
118: These are the functions that resolve a host name
119: <H3>
120: Get Host By Socket
121: </H3>
122: <P>
123: This function should have been called HTGetHostByAddr but for historical
124: reasons this is not the case.
2.1 frystyk 125: <PRE>
2.7 frystyk 126: extern char * HTGetHostBySock (int soc);
2.1 frystyk 127: </PRE>
2.13 frystyk 128: <H3>
129: Get Host By Name
130: </H3>
131: <P>
132: This function gets the address of the host and puts it in to the socket
133: structure. It maintains its own cache of connections so that the communication
134: to the Domain Name Server is minimized. Returns the number of homes or -1
135: if error.
2.1 frystyk 136: <PRE>
2.15 frystyk 137: extern int HTGetHostByName (HTHost * host, char *hostname, HTRequest * request);
2.1 frystyk 138: </PRE>
139: <PRE>
2.21 ! vbancrof 140: #ifdef __cplusplus
! 141: }
2.1 frystyk 142: #endif
2.21 ! vbancrof 143:
! 144: #endif /* HTDNS_H */
2.1 frystyk 145: </PRE>
2.13 frystyk 146: <P>
147: <HR>
2.12 frystyk 148: <ADDRESS>
2.21 ! vbancrof 149: @(#) $Id: HTDNS.html,v 2.20 2005/01/04 15:50:57 duerst Exp $
2.12 frystyk 150: </ADDRESS>
2.13 frystyk 151: </BODY></HTML>
Webmaster