Annotation of libwww/Library/src/HTTCP.html, revision 2.19
2.17 frystyk 1: <HTML>
2: <HEAD>
3: <TITLE>/Net/dxcern/userd/timbl/hypertext/WWW/Library/src/HTTCP.html</TITLE>
4: </HEAD>
2.2 timbl 5: <BODY>
2.17 frystyk 6:
2.13 frystyk 7: <H1>Generic Network Communication</H1>
8:
2.17 frystyk 9: <PRE>
10: /*
11: ** (c) COPYRIGHT CERN 1994.
12: ** Please first read the full copyright statement in the file COPYRIGH.
13: */
14: </PRE>
15:
2.13 frystyk 16: This module has the common code for handling TCP/IP and DECnet connections
2.17 frystyk 17: etc. The main topics of functions in this module are:
2.15 frystyk 18:
19: <UL>
20: <LI><A HREF="#ConEst">Connection establishment</A>
21: <LI><A HREF="#hostcache">Cache of host names</A>
22: <LI><A HREF="#DNS">Host and mail addresses</A>
23: <LI><A HREF="#Signals">Signal Handling</A>
24: </UL>
2.17 frystyk 25:
26: This module is implemented by <A HREF="HTTCP.c">HTTCP.c</A>, and it is
27: a part of the <A
28: HREF="http://info.cern.ch/hypertext/WWW/Library/User/Guide/Guide.html">
29: Library of Common Code</A>.
2.13 frystyk 30:
2.8 frystyk 31: <PRE>
32: #ifndef HTTCP_H
2.2 timbl 33: #define HTTCP_H
34:
35: #include "HTUtils.h"
2.8 frystyk 36: #include "HTAccess.h"
2.1 timbl 37:
38: #ifdef SHORT_NAMES
39: #define HTInetStatus HTInStat
40: #define HTInetString HTInStri
41: #define HTParseInet HTPaInet
42: #endif
2.8 frystyk 43: </PRE>
44:
45: <H2>Connection Management</H2>
46:
2.15 frystyk 47: All connections are established through the following functions.
2.8 frystyk 48:
2.15 frystyk 49: <A NAME="ConEst"><H3>Active Connection Establishment</H3></A>
2.8 frystyk 50:
2.15 frystyk 51: This makes an active connect to the specified host. The <A
52: HREF="HTAccess.html#HTNetInfo">HTNetInfo structure</A> is parsed in
53: order to handle errors. Default port might be overwritten by any port
54: indication in the <A
55: HREF="http://info.cern.ch/hypertext/WWW/Addressing/URL/Overview.html">URL</A>
56: specified as <host>:<port> If it is a multihomed host then
57: HTDoConnect measures the time to do the connection and updates the
58: calculated weights in the cache of visited hosts.
2.8 frystyk 59:
60: <PRE>
2.16 frystyk 61: extern int HTDoConnect PARAMS(( HTNetInfo *net,
2.8 frystyk 62: char *url,
63: u_short default_port,
2.14 frystyk 64: u_long *addr,
65: BOOL use_cur));
2.8 frystyk 66: </PRE>
67:
68: <H3>Passive Connection Establishment</H3>
69:
70: This function makes a non-blocking accept on a port and polls every second
2.13 frystyk 71: until MAX_ACCEPT_POLL is reached.
2.1 timbl 72:
2.8 frystyk 73: <PRE>
2.16 frystyk 74: extern int HTDoAccept PARAMS((HTNetInfo *net));
2.8 frystyk 75: </PRE>
2.1 timbl 76:
2.15 frystyk 77: <A NAME="hostcache"><H2>Caching Hosts Names</H2></A>
2.8 frystyk 78:
2.13 frystyk 79: This part of the HTTCP module maintains a cache of all visited hosts so that
80: subsequent connects to the same host doesn't imply a new request to the DNS
81: every time. <P>
82:
83: Multihomed hosts are treated specially in that the time spend on every connect
84: is measured and kept in the cache. On the next request to the same host, the
85: IP-address with the lowest average connect time is chosen. If one IP-address
86: fails completely, e.g. <EM>connection refused</EM> then it disabled and
87: HTDoConnect tries one of the other IP-addresses to the same host.<P>
88:
89: If the connect fails in the case of at single-homed host then the entry is
90: removed from the cache and HTDoConnect tries again asking the DNS.
2.10 frystyk 91:
2.13 frystyk 92: <H3>Recalculating the Time-Weights on Multihomed Hosts</H3>
93:
94: On every connect to a multihomed host, the average connect time is updated
95: exponentially for all the entries.
2.8 frystyk 96:
97: <PRE>
2.16 frystyk 98: extern void HTTCPAddrWeights PARAMS((char * host, time_t deltatime));
2.8 frystyk 99: </PRE>
100:
2.9 frystyk 101: <H3>Control Variables</H3>
102:
2.13 frystyk 103: This parameter determines the maximum number of hosts in the cache. The
104: default number is 500.
2.9 frystyk 105:
106: <PRE>
107: extern unsigned int HTConCacheSize;
108: </PRE>
2.8 frystyk 109:
110: <H2>Errors and status indications</H2>
111:
112: Theese functions return an explanation if an error has occured.
113:
114: <H3>Errno Message</H3>
2.7 luotonen 115:
2.8 frystyk 116: Return error message corresponding to current errno, just like strerror().
2.7 luotonen 117:
2.8 frystyk 118: <PRE>
2.16 frystyk 119: extern CONST char * HTErrnoString NOPARAMS;
2.8 frystyk 120: </PRE>
2.1 timbl 121:
2.8 frystyk 122: <H3>Description of what Caused the Error</H3>
2.1 timbl 123:
2.8 frystyk 124: The parameter `where' gives a description of what caused the error, often
125: the name of a system call. <P>
2.7 luotonen 126:
2.8 frystyk 127: This function should only rarely be called directly. Instead the common error
128: function HTErrorAdd() should be used as then the error is parsed all the way
129: to the user. The function returns a negative status in the unix way.
2.1 timbl 130:
2.8 frystyk 131: <PRE>
2.16 frystyk 132: extern int HTInetStatus PARAMS((char * where));
2.8 frystyk 133: </PRE>
2.1 timbl 134:
2.13 frystyk 135: <H3>Parse a Cardinal Value</H3>
136:
2.8 frystyk 137: <PRE>
2.1 timbl 138: /* Parse a cardinal value parse_cardinal()
139: ** ----------------------
140: **
141: ** On entry:
142: ** *pp points to first character to be interpreted, terminated by
143: ** non 0..9 character.
144: ** *pstatus points to status already valid,
145: ** maxvalue gives the largest allowable value.
146: **
147: ** On exit:
148: ** *pp points to first unread character,
149: ** *pstatus points to status updated iff bad
150: */
2.2 timbl 151:
2.16 frystyk 152: extern unsigned int HTCardinal PARAMS((int * pstatus,
2.7 luotonen 153: char ** pp,
154: unsigned int max_value));
2.8 frystyk 155: </PRE>
156:
2.15 frystyk 157: <A NAME="DNS"><H2>Internet Name Server Functions</H2></A>
2.8 frystyk 158:
159: The following functions are available to get information about a
160: specified host.
161:
162: <H3>Produce a string for an internet address</H3>
163:
164: This function is equivalent to the BSD system call <B>inet_ntoa</B> in that it
165: converts a numeric 32-bit IP-address to a dotted-notation decimal string. The
166: pointer returned points to static memory which must be copied if it is to be
167: kept.
168:
169: <PRE>
2.16 frystyk 170: extern CONST char * HTInetString PARAMS((struct sockaddr_in * sin));
2.8 frystyk 171: </PRE>
172:
173: <H3>Parse an internet node address and port</H3>
174:
175: This function finds the address of a specified host and fills out the sockaddr
176: structure. str points to a string with a node name or number, with optional
177: trailing colon and port number. sin points to the binary internet or decnet
178: address field. <P>
179:
180: On exit *sin is filled in. If no port is specified in str, that field is left
2.14 frystyk 181: unchanged in *sin. On success, the number of homes on the host is returned.
182: <PRE>
2.16 frystyk 183: extern int HTParseInet PARAMS(( struct sockaddr_in * sin,
2.14 frystyk 184: CONST char * str,
185: BOOL use_cur));
2.8 frystyk 186: </PRE>
187:
188: <H3>Name of a Machine on the Other Side of a Socket</H3>
2.2 timbl 189:
2.8 frystyk 190: This function should have been called HTGetHostByAddr but for historical
2.12 frystyk 191: reasons this is not the case. <P>
192:
193: <EM><NOTE>Note:</NOTE>This function used to be called HTGetHostName but
194: this is now used to find you own host name, see <A HREF="HTTCP.html#HTGetHostName">HTGetHostName()</A></EM>
2.1 timbl 195:
2.8 frystyk 196: <PRE>
2.16 frystyk 197: extern char * HTGetHostBySock PARAMS((int soc));
2.8 frystyk 198: </PRE>
199:
200: <H3>Host address retuned for specified host name</H3>
201:
202: This function gets the address of the host and puts it in to the socket
203: structure. It maintains its own cache of connections so that the communication
2.14 frystyk 204: to the Domain Name Server is minimized. If OK and single homed host then
205: it returns 0 but if it is a multi-homed host then 1 is returned.
2.8 frystyk 206:
207: <PRE>
2.16 frystyk 208: extern int HTGetHostByName PARAMS((char *host, SockA *sin, BOOL use_cur));
2.8 frystyk 209: </PRE>
2.7 luotonen 210:
2.1 timbl 211:
2.12 frystyk 212: <A NAME="HTGetHostName"><H3>Get Name of This Machine</H3></A>
2.6 luotonen 213:
2.14 frystyk 214: This function returns a CONET char pointer to a static location containing
215: the name of this host or NULL if not available.
2.7 luotonen 216:
2.8 frystyk 217: <PRE>
2.16 frystyk 218: extern CONST char * HTGetHostName NOPARAMS;
2.12 frystyk 219: </PRE>
220:
221:
222: <H3>Set Name of This Machine</H3>
223:
224: This function overwrites any other value of current host name. This might
225: be set by the user to change the value in the ID value parsed to a news host
2.14 frystyk 226: when posting. The change doesn't influence the <A HREF="HTTCP.html#Mailaddress">Mail Address</A> as they are stored in two different locations. If, however,
227: the change is done before the first call to HTGetMailAddress() then this
228: function will use the new host and domain name.
229:
230: <PRE>
2.16 frystyk 231: extern void HTSetHostName PARAMS((char * host));
2.14 frystyk 232: </PRE>
233:
234:
235: <H3>Get Domain Name of This Machine</H3>
236:
237: This function rerturns the domain name part of the host name as returned by
238: HTGetHostName() function. Changing the domain name requires a call to
239: HTSetHostname().
2.12 frystyk 240:
241: <PRE>
2.16 frystyk 242: extern CONST char *HTGetDomainName NOPARAMS;
2.8 frystyk 243: </PRE>
2.2 timbl 244:
2.12 frystyk 245:
2.13 frystyk 246: <A NAME="Mailaddress"><H3>Get User Mail Address</H3></A>
2.12 frystyk 247:
2.13 frystyk 248: This functions returns a char pointer to a static location containing the
249: mail address of the current user. The static location is different from the
250: one of the current host name so different values can be assigned. The default
251: value is <USER>@hostname where hostname is as returned by HTGetHostName().
2.12 frystyk 252:
253: <PRE>
2.16 frystyk 254: extern CONST char * HTGetMailAddress NOPARAMS;
2.12 frystyk 255: </PRE>
256:
257:
258: <H3>Set User Mail Address</H3>
259:
260: This function overwrites any other value of current mail address. This might
261: be set by the user to change the value in the <A HREF="http://info.cern.ch/hypertext/WWW/Protocols/HTTP/HTRQ_Headers.html#from">From field</A> in the <A HREF="http://info.cern.ch/hypertext/WWW/Protocols/HTTP/HTTP2.html">HTTP Protocol</A>.
262:
263: <PRE>
2.16 frystyk 264: extern void HTSetMailAddress PARAMS((char * address));
2.12 frystyk 265: </PRE>
266:
2.15 frystyk 267: <H2>Signal Handling</H2>
268:
269: This is only necessary to compile on a few platforms and only if the
270: application does not have its own signal handling.
2.12 frystyk 271:
2.8 frystyk 272: <PRE>
2.18 frystyk 273: #ifdef WWWLIB_SIG
2.19 ! frystyk 274: extern void HTSetSignal NOPARAMS;
2.15 frystyk 275: #endif
276:
2.2 timbl 277: #endif /* HTTCP_H */
2.8 frystyk 278: </PRE>
2.15 frystyk 279:
2.8 frystyk 280: End of file
281: </BODY>
282: </HTML>
2.12 frystyk 283:
284:
285:
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTTCP.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src