Annotation of libwww/Library/src/HTHost.html, revision 2.13
2.1 frystyk 1: <HTML>
2: <HEAD>
2.4 frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 2-Jul-1996 -->
2.3 frystyk 4: <TITLE>W3C Reference Library libwww Host Class</TITLE>
2.1 frystyk 5: </HEAD>
6: <BODY>
2.3 frystyk 7: <H1>
8: The Host 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.3 frystyk 16: <P>
17: The Host class manages what we know about a remote host. This can for example
18: be what type of host it is, and what version it is using. Notice that a host
19: object can be used to describe both a server or a client - all information
20: in the Host object can be shared regardless of whether it is to be used in
21: a server application or a client application.
22: <P>
23: This module is implemented by <A HREF="HTHost.c">HTHost.c</A>, and it is
24: a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C Reference
25: Library</A>.
2.1 frystyk 26: <PRE>
27: #ifndef HTHOST_H
28: #define HTHOST_H
29:
30: typedef struct _HTHost HTHost;
2.8 frystyk 31: #define HOST_HASH_SIZE 67
2.1 frystyk 32:
33: #include "HTChannl.h"
34: #include "HTReq.h"
2.2 frystyk 35: #include "HTEvent.h"
2.8 frystyk 36: #include "HTProt.h"
2.1 frystyk 37: </PRE>
2.3 frystyk 38: <P>
39: The Host class contains information about the remote host, for example the
40: type (HTTP/1.0, HTTP/1.1, FTP etc.) along with information on how the connections
41: can be used (if it supports persistent connections, interleaved access etc.)
42: <H2>
43: Creation and Deletion Methods
44: </H2>
45: <P>
46: We keep a cache of information that we know about a remote host. This allows
2.5 frystyk 47: us to be much more detailed in generating requests. Search the host info
48: cache for a host object or create a new one and add it. Examples of host
49: names are
2.1 frystyk 50: <UL>
2.3 frystyk 51: <LI>
52: www.w3.org
53: <LI>
54: www.foo.com:8000
2.1 frystyk 55: </UL>
2.3 frystyk 56: <H3>
57: Add a Host Object
58: </H3>
2.1 frystyk 59: <PRE>
2.10 eric 60: extern HTHost * HTHost_new (char * host, u_short u_port);
61: extern HTHost * HTHost_newWParse(HTRequest * request, char * url, u_short u_port);
2.8 frystyk 62: extern int HTHost_hash (HTHost * host);
2.1 frystyk 63: </PRE>
2.3 frystyk 64: <H3>
65: Delete a Host Object
66: </H3>
67: <P>
68: The Host Class contains an automatic garbage collection of Host objects so
69: that we don't keep information around that is stale.
2.6 frystyk 70: <H3>
71: Find a Host Object
72: </H3>
73: <P>
74: Searches the cache of known hosts to see if we already have information about
75: this host. If not then we return NULL.
76: <PRE>extern HTHost * HTHost_find (char * host);
77: </PRE>
2.3 frystyk 78: <H2>
2.12 frystyk 79: Remote Host Information
2.3 frystyk 80: </H2>
81: <P>
2.12 frystyk 82: We keep track of the capabilities of the host in the other end so thatwe
83: may adjust our queries to fit it better
2.3 frystyk 84: <H3>
2.5 frystyk 85: Remote Host Name
86: </H3>
87: <P>
88: Get the name of the remote host. This is set automatically when a new Host
89: object and can be asked for at any point in time. You can not change the
90: host name but must create a new Host object instead.
91: <PRE>
92: extern char * HTHost_name (HTHost * host);
93: </PRE>
94: <H3>
95: Remote Host Protocol Class and Version
2.3 frystyk 96: </H3>
97: <P>
98: Define the <EM>host class</EM> of the host at the other end. A class is a
99: generic description of the protocol which is exactly like the access method
100: in a URL, for example "http" etc. The <EM>host version</EM> is a finer
101: distinction (sub-class) between various versions of the host class, for example
102: HTTP/0.9, HTTP/1.1 etc. The host version is a bit flag that the protocol
103: module can define on its own. That way we don't have to change this module
104: when registering a new protocol module. The <EM>host type</EM> is a description
105: of whether we can keep the connection persistent or not.
2.1 frystyk 106: <PRE>
107: extern char * HTHost_class (HTHost * host);
108: extern void HTHost_setClass (HTHost * host, char * s_class);
109:
110: extern int HTHost_version (HTHost * host);
111: extern void HTHost_setVersion (HTHost * host, int version);
112: </PRE>
2.3 frystyk 113: <H3>
2.12 frystyk 114: Public Methods accessible on This Host
2.4 frystyk 115: </H3>
116: <P>
117: A server can inform a client about the supported methods using the
118: <CODE>Public</CODE> header.
119: <PRE>extern HTMethod HTHost_publicMethods (HTHost * me);
120: extern void HTHost_setPublicMethods (HTHost * me, HTMethod methodset);
121: extern void HTHost_appendPublicMethods (HTHost * me, HTMethod methodset);
122: </PRE>
2.12 frystyk 123: <H3>
2.4 frystyk 124: Server Name of Remote Host
2.12 frystyk 125: </H3>
2.4 frystyk 126: <P>
127: A server can send its server application name and version in a HTTP response.
128: We pick up this information and add it to the Host object
129: <PRE>extern char * HTHost_server (HTHost * host);
130: extern BOOL HTHost_setServer (HTHost * host, const char * server);
131: </PRE>
2.12 frystyk 132: <H3>
2.4 frystyk 133: User Agent Name of Remote Host
2.12 frystyk 134: </H3>
2.4 frystyk 135: <P>
136: A client can send the name of the client application in a HTTP request. We
2.5 frystyk 137: pick up this information and add it to the Host Object
2.4 frystyk 138: <PRE>extern char * HTHost_userAgent (HTHost * host);
139: extern BOOL HTHost_setUserAgent (HTHost * host, const char * userAgent);
140: </PRE>
2.12 frystyk 141: <H3>
2.7 frystyk 142: Range Units Accepted by this Host
2.12 frystyk 143: </H3>
2.7 frystyk 144: <P>
145: Since all HTTP entities are represented in HTTP messages as sequences of
146: bytes, the concept of a byte range is meaningful for any HTTP entity. (However,
147: not all clients and servers need to support byte-range operations.) Byte
148: range specifications in HTTP apply to the sequence of bytes in the entity-body
149: (not necessarily the same as the message-body). A byte range operation may
150: specify a single range of bytes, or a set of ranges within a single entity.
151: <P>
152: You can also check whether a specific range unit is OK. We always say
153: <CODE>YES</CODE> except if we have a specific statement from the server that
154: it doesn't understand byte ranges - that is - it has sent "none" in a
155: "Accept-Range" response header
156: <PRE>
157: extern char * HTHost_rangeUnits (HTHost * host);
158: extern BOOL HTHost_setRangeUnits (HTHost * host, const char * units);
159: extern BOOL HTHost_isRangeUnitAcceptable (HTHost * host, const char * unit);
160: </PRE>
2.12 frystyk 161: <H2>
162: Persistent Connections
163: </H2>
2.3 frystyk 164: <P>
165: We don't want more than MaxSockets-2 connections to be persistent in order
166: to avoid deadlock.
2.1 frystyk 167: <PRE>
2.8 frystyk 168: extern BOOL HTHost_setPersistent (HTHost * host, BOOL persistent,
169: HTTransportMode mode);
2.5 frystyk 170: extern BOOL HTHost_clearChannel (HTHost * host, int status);
2.1 frystyk 171:
172: extern HTChannel * HTHost_channel (HTHost * host);
173: </PRE>
2.3 frystyk 174: <H3>
175: Is this host Persistent?
176: </H3>
177: <P>
2.1 frystyk 178: Check whether we have a persistent channel or not
179: <PRE>
180: extern BOOL HTHost_isPersistent (HTHost * host);
181: </PRE>
2.3 frystyk 182: <H3>
183: Timing Persistent Channels
184: </H3>
185: <P>
186: Normally we wait for the peer process to close persistent connections but
187: in order not to use up our own resources, we have a timeout on our own. The
188: default value is 1 hour, but you can modify the value using the following
189: methods:
2.1 frystyk 190: <PRE>
191: extern time_t HTHost_persistTimeout (time_t timeout);
192: extern void HTHost_setPersistTimeout (time_t timeout);
193: </PRE>
2.3 frystyk 194: <P>
195: Each persistent connection has an absolute value of when this connection
196: most likely will expire. If the peer process does not inform us, we use our
197: own timeout.
2.1 frystyk 198: <PRE>
199: extern void HTHost_setPersistExpires (HTHost * host, time_t expires);
200: extern time_t HTHost_persistExpires (HTHost * host);
2.11 eric 201: extern void HTHost_setReqsPerConnection (HTHost * host, int reqs);
202: extern int HTHost_reqsPerConnection (HTHost * host);
203: extern void HTHost_setReqsMade (HTHost * host, int reqs);
204: extern int HTHost_reqsMade (HTHost * host);
2.1 frystyk 205: </PRE>
2.5 frystyk 206: <H2>
2.12 frystyk 207: Transport Mode
208: </H2>
209: <P>
210: Handle the connection mode. The mode may change mode in the middle of a
211: connection If the new mode is lower than the old mode then adjust the pipeline
212: accordingly. That is, if we are going into single mode then move all entries
213: in the pipeline and move the rest to the pending queue. They will get launched
214: at a later point in time.
215: <PRE>extern HTTransportMode HTHost_mode (HTHost * host, BOOL * active);
216: extern BOOL HTHost_setMode (HTHost * host, HTTransportMode mode);
217: </PRE>
218: <H2>
2.5 frystyk 219: Queuing Requests
220: </H2>
221: <P>
222: Requests are queued in the Host object until we have resources to start them.
223: The request is in the form of a Net object as we may have multiple socket
224: requests per <A HREF="HTReq.html">Request object</A>. This is for example
225: the case with <A HREF="WWWFTp.html">FTP</A> which uses two connections.
226: <PRE>extern int HTHost_addNet (HTHost * host, HTNet * net);
2.8 frystyk 227: extern BOOL HTHost_free (HTHost * host, int status);
2.5 frystyk 228: extern BOOL HTHost_deleteNet (HTHost * host, HTNet * net);
229: extern HTList * HTHost_net (HTHost * host);
230: </PRE>
231: <H3>
2.12 frystyk 232: Is the Host Idle?
2.5 frystyk 233: </H3>
234: <P>
235: Before we can start a new connection to the host we must be sure that the
236: host is idle. That is, if it can accept a new connection. We have several
237: modes describing how and when a host is idle. This is a function of the
238: <A HREF="HTTrans.html">Transport Object</A>
239: <PRE>extern BOOL HTHost_isIdle (HTHost * host);
240: </PRE>
2.3 frystyk 241: <H3>
2.5 frystyk 242: Handling Pending Requests
2.3 frystyk 243: </H3>
244: <P>
2.5 frystyk 245: There are two ways we can end up with pending reqyests:
246: <OL>
247: <LI>
248: If we are out of sockets then register new host objects as pending.
249: <LI>
250: If we are pending on a connection then register new net objects as pending
251: </OL>
252: <P>
253: This set of functions handles pending host objects and can start new requests
254: as resources get available. The first function checks the host object for
255: any pending <A HREF="HTNet.html">Net objects</A> and return the first of
256: these Net objects.
2.3 frystyk 257: <PRE>
2.5 frystyk 258: extern HTNet * HTHost_nextPendingNet (HTHost * host);
259: </PRE>
260: <P>
261: The second checks the list of pending host objects waiting for a socket and
262: returns the first of these Host objects.
263: <PRE>
264: extern HTHost * HTHost_nextPendingHost (void);
265: </PRE>
266: <P>
267: Start the next pending request if any. First we look for pending requests
268: for the same host and then we check for any other pending hosts. If nothing
269: pending then register a catch close event handler to have something catching
270: the socket if the remote server closes the connection, for example due to
271: timeout.
2.8 frystyk 272: <PRE>
273: extern BOOL HTHost_launchPending (HTHost * host);
274:
275: extern int HTHost_connect (HTHost * host, HTNet * net, char * url,
276: HTProtocolId port);
277: </PRE>
278: <P>
279: HTHost clients can use the host for all IO and take advantage of host
280: multiplexing and pipelining.
2.12 frystyk 281: <H2>
2.8 frystyk 282: Event Management
2.12 frystyk 283: </H2>
2.8 frystyk 284: <PRE>
285: extern int HTHost_register(HTHost * host, HTNet * net, HTEventType type);
286: extern int HTHost_unregister(HTHost * host, HTNet * net, HTEventType type);
287: extern int HTHost_tickleFirstNet(HTHost * host, HTEventType type);
288: extern BOOL HTHost_setRemainingRead(HTHost * host, size_t remainaing);
289: extern SockA * HTHost_getSockAddr(HTHost * host);
290: </PRE>
291: <H3>
2.12 frystyk 292: Control the Delayed Flush Timer
2.8 frystyk 293: </H3>
2.12 frystyk 294: <P>
295: These methods can control how long we want to wait for a flush on a given
296: host.
2.8 frystyk 297: <PRE>
2.12 frystyk 298: extern BOOL HTHost_setWriteDelay (HTHost * host, ms_t delay);
299: extern ms_t HTHost_writeDelay (HTHost * host);
300: extern int HTHost_findWriteDelay(HTHost * host, ms_t lastFlushTime, int buffSize);
2.8 frystyk 301: </PRE>
2.12 frystyk 302: <P>
303: It is also possible to explicitly require a flush using the following method
2.8 frystyk 304: <PRE>
2.12 frystyk 305: extern int HTHost_forceFlush(HTHost * host);
2.8 frystyk 306: </PRE>
2.12 frystyk 307: <P>
308: You can also set the global value so that all new host objects will inherit
309: this value instead of setting it individually.
310: <PRE>extern BOOL HTHost_setDefaultWriteDelay (ms_t delay);
311: extern ms_t HTHost_defaultWriteDelay (void);
312: </PRE>
2.8 frystyk 313: <H3>
2.12 frystyk 314: Event Timeouts
2.8 frystyk 315: </H3>
2.12 frystyk 316: <P>
317: Events can be assigned a timeout which causes the event to be triggered if
318: the timeout happens before other action is available on the socket. You can
319: assign a global timeout for all host object using the following methods
2.8 frystyk 320: <PRE>
2.12 frystyk 321: extern int HTHost_eventTimeout (void);
322: extern void HTHost_setEventTimeout (int millis);
2.8 frystyk 323: </PRE>
324: <H3>
2.12 frystyk 325: Get the Next Net object for Reading and Writing
2.8 frystyk 326: </H3>
327: <PRE>
328: extern HTNet * HTHost_firstNet (HTHost * host);
329: extern HTNet * HTHost_getReadNet (HTHost * host);
330: extern HTNet * HTHost_getWriteNet (HTHost * host);
331: </PRE>
332: <H3>
2.12 frystyk 333: Automatic Connection Recovery
334: </H3>
335: <P>
336: In case a pipeline is broken then we have to recover it and start again.
337: This is handled automatically by the host object
338: <PRE>extern BOOL HTHost_recoverPipe (HTHost * host);
339: </PRE>
340: <H3>
2.8 frystyk 341: Get input and output Streams for this Host
342: </H3>
343: <PRE>
344: extern HTInputStream * HTHost_getInput (HTHost * host, HTTransport * transport,
345: void * param, int mode);
346:
347: extern HTOutputStream * HTHost_getOutput (HTHost * host, HTTransport * tp,
348: void * param, int mode);
349: </PRE>
350: <H3>
2.12 frystyk 351: The Channel Associated with this Host
352: </H3>
353: <PRE>
354: extern BOOL HTHost_setChannel (HTHost * host, HTChannel * channel);
355: extern HTChannel * HTHost_channel (HTHost * host);
356: </PRE>
357: <H3>
2.8 frystyk 358: Read Management
359: </H3>
360: <PRE>
361: extern int HTHost_read(HTHost * host, HTNet * net);
362: extern BOOL HTHost_setConsumed(HTHost * host, size_t bytes);
2.3 frystyk 363: </PRE>
2.12 frystyk 364: <H2>
365: Multi homed Host Management
366: </H2>
367: <P>
368: We also keep track of if a host has multiple IP addresses. If so then it
369: is called a <I>multi-homed host</I>. This is used for two things: finding
370: the fastest host with this name and as a backup if one or more of the hosts
371: are down.
2.1 frystyk 372: <PRE>
2.12 frystyk 373: extern BOOL HTHost_setHome (HTHost * host, int home);
374: extern int HTHost_home (HTHost * host);
2.13 ! frystyk 375:
! 376: extern BOOL HTHost_setRetry (HTHost * host, int retry);
! 377: extern int HTHost_retry (HTHost * host);
! 378: extern BOOL HTHost_decreaseRetry (HTHost * host);
2.12 frystyk 379: </PRE>
380: <PRE>
2.1 frystyk 381: #endif /* HTHOST_H */
382: </PRE>
2.3 frystyk 383: <P>
384: <HR>
2.1 frystyk 385: <ADDRESS>
2.13 ! frystyk 386: @(#) $Id: HTHost.html,v 2.12 1997/02/01 16:16:25 frystyk Exp $
2.1 frystyk 387: </ADDRESS>
2.3 frystyk 388: </BODY></HTML>
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTHost.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src