Annotation of libwww/Library/src/HTHost.html, revision 2.11
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>
79: Host Class Methods
80: </H2>
81: <P>
2.1 frystyk 82: This is what we know about the remote host
2.3 frystyk 83: <H3>
2.5 frystyk 84: Remote Host Name
85: </H3>
86: <P>
87: Get the name of the remote host. This is set automatically when a new Host
88: object and can be asked for at any point in time. You can not change the
89: host name but must create a new Host object instead.
90: <PRE>
91: extern char * HTHost_name (HTHost * host);
92: </PRE>
93: <H3>
94: Remote Host Protocol Class and Version
2.3 frystyk 95: </H3>
96: <P>
97: Define the <EM>host class</EM> of the host at the other end. A class is a
98: generic description of the protocol which is exactly like the access method
99: in a URL, for example "http" etc. The <EM>host version</EM> is a finer
100: distinction (sub-class) between various versions of the host class, for example
101: HTTP/0.9, HTTP/1.1 etc. The host version is a bit flag that the protocol
102: module can define on its own. That way we don't have to change this module
103: when registering a new protocol module. The <EM>host type</EM> is a description
104: of whether we can keep the connection persistent or not.
2.1 frystyk 105: <PRE>
106: extern char * HTHost_class (HTHost * host);
107: extern void HTHost_setClass (HTHost * host, char * s_class);
108:
109: extern int HTHost_version (HTHost * host);
110: extern void HTHost_setVersion (HTHost * host, int version);
111: </PRE>
2.3 frystyk 112: <H3>
2.4 frystyk 113: Remote host Options and Services
114: </H3>
115: <P>
2.5 frystyk 116: We keep track of the capabilities of the remote host. In many cases the
2.4 frystyk 117: information that we get is specific to servers but this doesn't <I>have</I>
118: to be the case.
119: <H4>
2.5 frystyk 120: Public Methods accessible on This Host
2.4 frystyk 121: </H4>
122: <P>
123: A server can inform a client about the supported methods using the
124: <CODE>Public</CODE> header.
125: <PRE>extern HTMethod HTHost_publicMethods (HTHost * me);
126: extern void HTHost_setPublicMethods (HTHost * me, HTMethod methodset);
127: extern void HTHost_appendPublicMethods (HTHost * me, HTMethod methodset);
128: </PRE>
129: <H4>
130: Server Name of Remote Host
131: </H4>
132: <P>
133: A server can send its server application name and version in a HTTP response.
134: We pick up this information and add it to the Host object
135: <PRE>extern char * HTHost_server (HTHost * host);
136: extern BOOL HTHost_setServer (HTHost * host, const char * server);
137: </PRE>
138: <H4>
139: User Agent Name of Remote Host
140: </H4>
141: <P>
142: A client can send the name of the client application in a HTTP request. We
2.5 frystyk 143: pick up this information and add it to the Host Object
2.4 frystyk 144: <PRE>extern char * HTHost_userAgent (HTHost * host);
145: extern BOOL HTHost_setUserAgent (HTHost * host, const char * userAgent);
146: </PRE>
2.7 frystyk 147: <H4>
148: Range Units Accepted by this Host
149: </H4>
150: <P>
151: Since all HTTP entities are represented in HTTP messages as sequences of
152: bytes, the concept of a byte range is meaningful for any HTTP entity. (However,
153: not all clients and servers need to support byte-range operations.) Byte
154: range specifications in HTTP apply to the sequence of bytes in the entity-body
155: (not necessarily the same as the message-body). A byte range operation may
156: specify a single range of bytes, or a set of ranges within a single entity.
157: <P>
158: You can also check whether a specific range unit is OK. We always say
159: <CODE>YES</CODE> except if we have a specific statement from the server that
160: it doesn't understand byte ranges - that is - it has sent "none" in a
161: "Accept-Range" response header
162: <PRE>
163: extern char * HTHost_rangeUnits (HTHost * host);
164: extern BOOL HTHost_setRangeUnits (HTHost * host, const char * units);
165: extern BOOL HTHost_isRangeUnitAcceptable (HTHost * host, const char * unit);
166: </PRE>
2.4 frystyk 167: <H3>
2.3 frystyk 168: Register a Persistent Channel
169: </H3>
170: <P>
171: We don't want more than MaxSockets-2 connections to be persistent in order
172: to avoid deadlock.
2.1 frystyk 173: <PRE>
2.8 frystyk 174: extern BOOL HTHost_setPersistent (HTHost * host, BOOL persistent,
175: HTTransportMode mode);
2.5 frystyk 176: extern BOOL HTHost_clearChannel (HTHost * host, int status);
2.1 frystyk 177:
178: extern HTChannel * HTHost_channel (HTHost * host);
179: </PRE>
2.3 frystyk 180: <H3>
181: Is this host Persistent?
182: </H3>
183: <P>
2.1 frystyk 184: Check whether we have a persistent channel or not
185: <PRE>
186: extern BOOL HTHost_isPersistent (HTHost * host);
187: </PRE>
2.3 frystyk 188: <H3>
2.8 frystyk 189: Is the Host Idle?
2.5 frystyk 190: </H3>
191: <P>
192: Before we can start a new connection to the host we must be sure that the
193: host is idle. That is, if it can accept a new connection. We have several
194: modes describing how and when a host is idle. This is a function of the Transport
195: Object
196: <PRE>
197: extern BOOL HTHost_isIdle (HTHost * host);
198: </PRE>
199: <H3>
200: Handling the Transport Mode
201: </H3>
202: <P>
203: Handle the connection mode. The mode may change mode in the middle of a
204: connection If the new mode is lower than the old mode then adjust the pipeline
205: accordingly. That is, if we are going into single mode then move all entries
206: in the pipeline and move the rest to the pending queue. They will get launched
207: at a later point in time.
208: <PRE>extern HTTransportMode HTHost_mode (HTHost * host, BOOL * active);
209: extern BOOL HTHost_setMode (HTHost * host, HTTransportMode mode);
210: </PRE>
211: <H3>
2.3 frystyk 212: Timing Persistent Channels
213: </H3>
214: <P>
215: Normally we wait for the peer process to close persistent connections but
216: in order not to use up our own resources, we have a timeout on our own. The
217: default value is 1 hour, but you can modify the value using the following
218: methods:
2.1 frystyk 219: <PRE>
220: extern time_t HTHost_persistTimeout (time_t timeout);
221: extern void HTHost_setPersistTimeout (time_t timeout);
222: </PRE>
2.3 frystyk 223: <P>
224: Each persistent connection has an absolute value of when this connection
225: most likely will expire. If the peer process does not inform us, we use our
226: own timeout.
2.1 frystyk 227: <PRE>
228: extern void HTHost_setPersistExpires (HTHost * host, time_t expires);
229: extern time_t HTHost_persistExpires (HTHost * host);
2.11 ! eric 230: extern void HTHost_setReqsPerConnection (HTHost * host, int reqs);
! 231: extern int HTHost_reqsPerConnection (HTHost * host);
! 232: extern void HTHost_setReqsMade (HTHost * host, int reqs);
! 233: extern int HTHost_reqsMade (HTHost * host);
2.1 frystyk 234: </PRE>
2.5 frystyk 235: <H2>
236: Queuing Requests
237: </H2>
238: <P>
239: Requests are queued in the Host object until we have resources to start them.
240: The request is in the form of a Net object as we may have multiple socket
241: requests per <A HREF="HTReq.html">Request object</A>. This is for example
242: the case with <A HREF="WWWFTp.html">FTP</A> which uses two connections.
243: <PRE>extern int HTHost_addNet (HTHost * host, HTNet * net);
2.8 frystyk 244: extern BOOL HTHost_free (HTHost * host, int status);
2.5 frystyk 245: extern BOOL HTHost_deleteNet (HTHost * host, HTNet * net);
246: extern HTList * HTHost_net (HTHost * host);
247: </PRE>
248: <H3>
249: Is the Host Idle
250: </H3>
251: <P>
252: Before we can start a new connection to the host we must be sure that the
253: host is idle. That is, if it can accept a new connection. We have several
254: modes describing how and when a host is idle. This is a function of the
255: <A HREF="HTTrans.html">Transport Object</A>
256: <PRE>extern BOOL HTHost_isIdle (HTHost * host);
257: </PRE>
2.3 frystyk 258: <H3>
2.5 frystyk 259: Handling Pending Requests
2.3 frystyk 260: </H3>
261: <P>
2.5 frystyk 262: There are two ways we can end up with pending reqyests:
263: <OL>
264: <LI>
265: If we are out of sockets then register new host objects as pending.
266: <LI>
267: If we are pending on a connection then register new net objects as pending
268: </OL>
269: <P>
270: This set of functions handles pending host objects and can start new requests
271: as resources get available. The first function checks the host object for
272: any pending <A HREF="HTNet.html">Net objects</A> and return the first of
273: these Net objects.
2.3 frystyk 274: <PRE>
2.5 frystyk 275: extern HTNet * HTHost_nextPendingNet (HTHost * host);
276: </PRE>
277: <P>
278: The second checks the list of pending host objects waiting for a socket and
279: returns the first of these Host objects.
280: <PRE>
281: extern HTHost * HTHost_nextPendingHost (void);
282: </PRE>
283: <P>
284: Start the next pending request if any. First we look for pending requests
285: for the same host and then we check for any other pending hosts. If nothing
286: pending then register a catch close event handler to have something catching
287: the socket if the remote server closes the connection, for example due to
288: timeout.
2.8 frystyk 289: <PRE>
290: extern BOOL HTHost_launchPending (HTHost * host);
291:
292: extern int HTHost_connect (HTHost * host, HTNet * net, char * url,
293: HTProtocolId port);
294: </PRE>
295: <P>
296: HTHost clients can use the host for all IO and take advantage of host
297: multiplexing and pipelining.
298: <H3>
299: Event Management
300: </H3>
301: <PRE>
302: extern int HTHost_register(HTHost * host, HTNet * net, HTEventType type);
303: extern int HTHost_unregister(HTHost * host, HTNet * net, HTEventType type);
304: extern int HTHost_tickleFirstNet(HTHost * host, HTEventType type);
305: extern BOOL HTHost_setRemainingRead(HTHost * host, size_t remainaing);
306: extern SockA * HTHost_getSockAddr(HTHost * host);
307: </PRE>
308:
309: <H3>
310: Event Timeouts
311: </H3>
312:
313: Events can be assigned a timeout which causes the event to be
314: triggered if the timeout happens before other action is available on
315: the socket. You can assign a global timeout for all host object using
316: the following methods
317:
318: <PRE>
319: extern int HTHost_eventTimeout (void);
320: extern void HTHost_setEventTimeout (int millis);
321: </PRE>
322:
323: <H3>
324: Multi homed Host Management
325: </H3>
326: <PRE>
327: extern BOOL HTHost_setHome (HTHost * host, int home);
328: extern int HTHost_home (HTHost * host);
329: </PRE>
330: <H3>
331: The Channel Associated with this Host
332: </H3>
333: <PRE>
334: extern BOOL HTHost_setChannel (HTHost * host, HTChannel * channel);
335: extern HTChannel * HTHost_channel (HTHost * host);
336: </PRE>
337:
338: <H3>
339: Get the Next Net object for Reading and Writing
340: </H3>
341:
342: <PRE>
343: extern HTNet * HTHost_firstNet (HTHost * host);
344: extern HTNet * HTHost_getReadNet (HTHost * host);
345: extern HTNet * HTHost_getWriteNet (HTHost * host);
2.9 frystyk 346: extern int HTHost_writeDelay(HTHost * host, ms_t lastFlushTime, int buffSize);
2.8 frystyk 347: extern int HTHost_forceFlush(HTHost * host);
348: </PRE>
349:
350: <H3>
351: Get input and output Streams for this Host
352: </H3>
353: <PRE>
354: extern HTInputStream * HTHost_getInput (HTHost * host, HTTransport * transport,
355: void * param, int mode);
356:
357: extern HTOutputStream * HTHost_getOutput (HTHost * host, HTTransport * tp,
358: void * param, int mode);
359: </PRE>
360: <H3>
361: Read Management
362: </H3>
363: <PRE>
364: extern int HTHost_read(HTHost * host, HTNet * net);
365: extern BOOL HTHost_setConsumed(HTHost * host, size_t bytes);
2.3 frystyk 366: </PRE>
2.1 frystyk 367: <PRE>
368: #endif /* HTHOST_H */
369: </PRE>
2.3 frystyk 370: <P>
371: <HR>
2.1 frystyk 372: <ADDRESS>
2.11 ! eric 373: @(#) $Id: HTHost.html,v 2.10 1996/12/03 05:46:12 eric Exp $
2.1 frystyk 374: </ADDRESS>
2.3 frystyk 375: </BODY></HTML>
Webmaster