Annotation of libwww/Library/src/HTHost.html, revision 2.10
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);
230: </PRE>
2.5 frystyk 231: <H2>
232: Queuing Requests
233: </H2>
234: <P>
235: Requests are queued in the Host object until we have resources to start them.
236: The request is in the form of a Net object as we may have multiple socket
237: requests per <A HREF="HTReq.html">Request object</A>. This is for example
238: the case with <A HREF="WWWFTp.html">FTP</A> which uses two connections.
239: <PRE>extern int HTHost_addNet (HTHost * host, HTNet * net);
2.8 frystyk 240: extern BOOL HTHost_free (HTHost * host, int status);
2.5 frystyk 241: extern BOOL HTHost_deleteNet (HTHost * host, HTNet * net);
242: extern HTList * HTHost_net (HTHost * host);
243: </PRE>
244: <H3>
245: Is the Host Idle
246: </H3>
247: <P>
248: Before we can start a new connection to the host we must be sure that the
249: host is idle. That is, if it can accept a new connection. We have several
250: modes describing how and when a host is idle. This is a function of the
251: <A HREF="HTTrans.html">Transport Object</A>
252: <PRE>extern BOOL HTHost_isIdle (HTHost * host);
253: </PRE>
2.3 frystyk 254: <H3>
2.5 frystyk 255: Handling Pending Requests
2.3 frystyk 256: </H3>
257: <P>
2.5 frystyk 258: There are two ways we can end up with pending reqyests:
259: <OL>
260: <LI>
261: If we are out of sockets then register new host objects as pending.
262: <LI>
263: If we are pending on a connection then register new net objects as pending
264: </OL>
265: <P>
266: This set of functions handles pending host objects and can start new requests
267: as resources get available. The first function checks the host object for
268: any pending <A HREF="HTNet.html">Net objects</A> and return the first of
269: these Net objects.
2.3 frystyk 270: <PRE>
2.5 frystyk 271: extern HTNet * HTHost_nextPendingNet (HTHost * host);
272: </PRE>
273: <P>
274: The second checks the list of pending host objects waiting for a socket and
275: returns the first of these Host objects.
276: <PRE>
277: extern HTHost * HTHost_nextPendingHost (void);
278: </PRE>
279: <P>
280: Start the next pending request if any. First we look for pending requests
281: for the same host and then we check for any other pending hosts. If nothing
282: pending then register a catch close event handler to have something catching
283: the socket if the remote server closes the connection, for example due to
284: timeout.
2.8 frystyk 285: <PRE>
286: extern BOOL HTHost_launchPending (HTHost * host);
287:
288: extern int HTHost_connect (HTHost * host, HTNet * net, char * url,
289: HTProtocolId port);
290: </PRE>
291: <P>
292: HTHost clients can use the host for all IO and take advantage of host
293: multiplexing and pipelining.
294: <H3>
295: Event Management
296: </H3>
297: <PRE>
298: extern int HTHost_register(HTHost * host, HTNet * net, HTEventType type);
299: extern int HTHost_unregister(HTHost * host, HTNet * net, HTEventType type);
300: extern int HTHost_tickleFirstNet(HTHost * host, HTEventType type);
301: extern BOOL HTHost_setRemainingRead(HTHost * host, size_t remainaing);
302: extern SockA * HTHost_getSockAddr(HTHost * host);
303: </PRE>
304:
305: <H3>
306: Event Timeouts
307: </H3>
308:
309: Events can be assigned a timeout which causes the event to be
310: triggered if the timeout happens before other action is available on
311: the socket. You can assign a global timeout for all host object using
312: the following methods
313:
314: <PRE>
315: extern int HTHost_eventTimeout (void);
316: extern void HTHost_setEventTimeout (int millis);
317: </PRE>
318:
319: <H3>
320: Multi homed Host Management
321: </H3>
322: <PRE>
323: extern BOOL HTHost_setHome (HTHost * host, int home);
324: extern int HTHost_home (HTHost * host);
325: </PRE>
326: <H3>
327: The Channel Associated with this Host
328: </H3>
329: <PRE>
330: extern BOOL HTHost_setChannel (HTHost * host, HTChannel * channel);
331: extern HTChannel * HTHost_channel (HTHost * host);
332: </PRE>
333:
334: <H3>
335: Get the Next Net object for Reading and Writing
336: </H3>
337:
338: <PRE>
339: extern HTNet * HTHost_firstNet (HTHost * host);
340: extern HTNet * HTHost_getReadNet (HTHost * host);
341: extern HTNet * HTHost_getWriteNet (HTHost * host);
2.9 frystyk 342: extern int HTHost_writeDelay(HTHost * host, ms_t lastFlushTime, int buffSize);
2.8 frystyk 343: extern int HTHost_forceFlush(HTHost * host);
344: </PRE>
345:
346: <H3>
347: Get input and output Streams for this Host
348: </H3>
349: <PRE>
350: extern HTInputStream * HTHost_getInput (HTHost * host, HTTransport * transport,
351: void * param, int mode);
352:
353: extern HTOutputStream * HTHost_getOutput (HTHost * host, HTTransport * tp,
354: void * param, int mode);
355: </PRE>
356: <H3>
357: Read Management
358: </H3>
359: <PRE>
360: extern int HTHost_read(HTHost * host, HTNet * net);
361: extern BOOL HTHost_setConsumed(HTHost * host, size_t bytes);
2.3 frystyk 362: </PRE>
2.1 frystyk 363: <PRE>
364: #endif /* HTHOST_H */
365: </PRE>
2.3 frystyk 366: <P>
367: <HR>
2.1 frystyk 368: <ADDRESS>
2.10 ! eric 369: @(#) $Id: HTHost.html,v 2.9 1996/12/02 20:19:46 frystyk Exp $
2.1 frystyk 370: </ADDRESS>
2.3 frystyk 371: </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