Annotation of libwww/Library/src/HTTCP.html, revision 2.37
2.17 frystyk 1: <HTML>
2: <HEAD>
2.37 ! frystyk 3: <TITLE>W3C Reference Library libwww NETWORK COMMUNICATION</TITLE>
2.36 frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 26-Feb-1996 -->
2.17 frystyk 5: </HEAD>
2.2 timbl 6: <BODY>
2.17 frystyk 7:
2.13 frystyk 8: <H1>Generic Network Communication</H1>
9:
2.17 frystyk 10: <PRE>
11: /*
2.25 frystyk 12: ** (c) COPYRIGHT MIT 1995.
2.17 frystyk 13: ** Please first read the full copyright statement in the file COPYRIGH.
14: */
15: </PRE>
16:
2.13 frystyk 17: This module has the common code for handling TCP/IP and DECnet connections
2.17 frystyk 18: etc. The main topics of functions in this module are:
2.15 frystyk 19:
20: <UL>
21: <LI><A HREF="#ConEst">Connection establishment</A>
22: <LI><A HREF="#hostcache">Cache of host names</A>
2.22 frystyk 23: <LI><A HREF="#errormsg">Errno Messages</A>
2.15 frystyk 24: <LI><A HREF="#DNS">Host and mail addresses</A>
25: <LI><A HREF="#Signals">Signal Handling</A>
26: </UL>
2.17 frystyk 27:
28: This module is implemented by <A HREF="HTTCP.c">HTTCP.c</A>, and it is
2.33 frystyk 29: a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C
30: Reference Library</A>.
2.13 frystyk 31:
2.8 frystyk 32: <PRE>
33: #ifndef HTTCP_H
2.2 timbl 34: #define HTTCP_H
2.30 frystyk 35: #include "HTReq.h"
36: #include "HTNet.h"
2.8 frystyk 37: </PRE>
38:
2.22 frystyk 39: <A NAME="ConEst"><H2>Connection Management</H2></A>
2.8 frystyk 40:
2.15 frystyk 41: All connections are established through the following functions.
2.8 frystyk 42:
2.22 frystyk 43: <H3>Active Connection Establishment</H3>
2.8 frystyk 44:
2.15 frystyk 45: This makes an active connect to the specified host. The <A
2.30 frystyk 46: HREF="HTReq.html#HTNet">HTNet structure</A> is parsed in
2.15 frystyk 47: order to handle errors. Default port might be overwritten by any port
48: indication in the <A
2.29 frystyk 49: HREF="http://www.w3.org/pub/WWW/Addressing/URL/Overview.html">URL</A>
2.15 frystyk 50: specified as <host>:<port> If it is a multihomed host then
51: HTDoConnect measures the time to do the connection and updates the
52: calculated weights in the cache of visited hosts.
2.8 frystyk 53:
54: <PRE>
2.31 frystyk 55: extern int HTDoConnect (HTNet * net, char * url, u_short default_port);
2.8 frystyk 56: </PRE>
57:
58: <H3>Passive Connection Establishment</H3>
59:
2.35 frystyk 60: This function makes a non-blocking accept on a port. The net must
61: contain a valid socket to accept on. If accept is OK then the socket
62: descripter in the Net object is swapped to the new one.
2.1 timbl 63:
2.8 frystyk 64: <PRE>
2.35 frystyk 65: extern int HTDoAccept (HTNet * net);
2.32 frystyk 66: </PRE>
67:
68: <H3>Listen on a Socket</H3>
69:
2.34 frystyk 70: Listens on the specified port. 0 means that we don't care and a
71: temporary one will be assigned. If <CODE>master</CODE>==INVSOC then we
72: listen on all local interfaces (using a wildcard). If !INVSOC then use
73: this as the local interface. <CODE>backlog</CODE> is the number of
74: connections that can be queued on the socket - you can use
75: <CODE>HT_BACKLOG</CODE> for a platform dependent value (typically 5 on
76: BSD and 32 on SVR4). Returns HT_ERROR or HT_OK.
2.32 frystyk 77:
78: <PRE>
2.34 frystyk 79: extern int HTDoListen (HTNet * net, u_short port, SOCKET master, int backlog);
2.8 frystyk 80: </PRE>
2.1 timbl 81:
2.22 frystyk 82: <A NAME="errormsg"><H2>System Description of Error Message</H2></A>
2.7 luotonen 83:
2.22 frystyk 84: Return error message corresponding to errno number given. We need to
85: pass the error number as a parameter as we on some platforms get
86: different codes from sockets and local file access.
2.1 timbl 87:
2.8 frystyk 88: <PRE>
2.36 frystyk 89: extern const char * HTErrnoString (int errnum);
2.33 frystyk 90: extern int HTInetStatus (int errnum, char * where);
2.8 frystyk 91: </PRE>
2.1 timbl 92:
2.13 frystyk 93: <H3>Parse a Cardinal Value</H3>
94:
2.8 frystyk 95: <PRE>
2.1 timbl 96: /* Parse a cardinal value parse_cardinal()
97: ** ----------------------
98: **
99: ** On entry:
100: ** *pp points to first character to be interpreted, terminated by
101: ** non 0..9 character.
102: ** *pstatus points to status already valid,
103: ** maxvalue gives the largest allowable value.
104: **
105: ** On exit:
106: ** *pp points to first unread character,
107: ** *pstatus points to status updated iff bad
108: */
2.2 timbl 109:
2.33 frystyk 110: extern unsigned int HTCardinal (int * pstatus,
111: char ** pp,
112: unsigned int max_value);
2.8 frystyk 113: </PRE>
114:
2.15 frystyk 115: <A NAME="DNS"><H2>Internet Name Server Functions</H2></A>
2.8 frystyk 116:
117: The following functions are available to get information about a
118: specified host.
119:
120: <H3>Produce a string for an internet address</H3>
121:
122: This function is equivalent to the BSD system call <B>inet_ntoa</B> in that it
123: converts a numeric 32-bit IP-address to a dotted-notation decimal string. The
124: pointer returned points to static memory which must be copied if it is to be
125: kept.
126:
127: <PRE>
2.36 frystyk 128: extern const char * HTInetString (struct sockaddr_in * sin);
2.8 frystyk 129: </PRE>
2.1 timbl 130:
2.12 frystyk 131: <A NAME="HTGetHostName"><H3>Get Name of This Machine</H3></A>
2.6 luotonen 132:
2.14 frystyk 133: This function returns a CONET char pointer to a static location containing
134: the name of this host or NULL if not available.
2.7 luotonen 135:
2.8 frystyk 136: <PRE>
2.36 frystyk 137: extern const char * HTGetHostName (void);
2.12 frystyk 138: </PRE>
139:
140:
141: <H3>Set Name of This Machine</H3>
142:
143: This function overwrites any other value of current host name. This might
144: be set by the user to change the value in the ID value parsed to a news host
2.14 frystyk 145: 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,
146: the change is done before the first call to HTGetMailAddress() then this
147: function will use the new host and domain name.
148:
149: <PRE>
2.33 frystyk 150: extern void HTSetHostName (char * host);
2.14 frystyk 151: </PRE>
152:
2.20 frystyk 153: <H3>Cleanup Memory</H3>
154:
2.30 frystyk 155: Called from <A HREF="HTReq.html#Library">HTLibTerminate</A>
2.20 frystyk 156:
157: <PRE>
2.32 frystyk 158: extern void HTFreeHostName (void);
2.20 frystyk 159: </PRE>
2.14 frystyk 160:
161: <H3>Get Domain Name of This Machine</H3>
162:
163: This function rerturns the domain name part of the host name as returned by
164: HTGetHostName() function. Changing the domain name requires a call to
165: HTSetHostname().
2.12 frystyk 166:
167: <PRE>
2.36 frystyk 168: extern const char *HTGetDomainName (void);
2.8 frystyk 169: </PRE>
2.2 timbl 170:
2.12 frystyk 171:
2.13 frystyk 172: <A NAME="Mailaddress"><H3>Get User Mail Address</H3></A>
2.12 frystyk 173:
2.13 frystyk 174: This functions returns a char pointer to a static location containing the
175: mail address of the current user. The static location is different from the
176: one of the current host name so different values can be assigned. The default
177: value is <USER>@hostname where hostname is as returned by HTGetHostName().
2.12 frystyk 178:
179: <PRE>
2.36 frystyk 180: #ifndef HT_DEFAULT_LOGIN
181: #define HT_DEFAULT_LOGIN "libwww"
182: #endif
183:
184: extern const char * HTGetMailAddress (void);
2.12 frystyk 185: </PRE>
186:
187:
188: <H3>Set User Mail Address</H3>
189:
190: This function overwrites any other value of current mail address. This might
2.29 frystyk 191: be set by the user to change the value in the <A HREF="http://www.w3.org/pub/WWW/Protocols/HTTP/HTRQ_Headers.html#from">From field</A> in the <A HREF="http://www.w3.org/pub/WWW/Protocols/HTTP/HTTP2.html">HTTP Protocol</A>.
2.12 frystyk 192:
193: <PRE>
2.33 frystyk 194: extern void HTSetMailAddress (char * address);
2.20 frystyk 195: </PRE>
196:
197: <H3>Free Memory</H3>
198:
2.30 frystyk 199: Called by <A HREF="HTReq.html#Library">HTLibTerminate</A>
2.20 frystyk 200:
201: <PRE>
2.32 frystyk 202: extern void HTFreeMailAddress (void);
2.12 frystyk 203: </PRE>
204:
2.15 frystyk 205: <H2>Signal Handling</H2>
206:
207: This is only necessary to compile on a few platforms and only if the
2.24 frystyk 208: application does not have its own signal handling. It is required on
209: Solaris 2.3 (and other SVR4 platforms?) due to a bug in the TCP
210: kernel. When a <CODE>connect()</CODE> is tried to a illegal port,
211: solaris gives a SIGPIPE signal instead of returning <EM>Connection
212: refused</EM>.
2.12 frystyk 213:
2.8 frystyk 214: <PRE>
2.18 frystyk 215: #ifdef WWWLIB_SIG
2.32 frystyk 216: extern void HTSetSignal (void);
2.15 frystyk 217: #endif
218:
2.2 timbl 219: #endif /* HTTCP_H */
2.8 frystyk 220: </PRE>
2.15 frystyk 221:
2.8 frystyk 222: End of file
223: </BODY>
224: </HTML>
2.12 frystyk 225:
226:
227:
Webmaster