Annotation of libwww/Library/src/HTHost.html, revision 2.7.2.2
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;
31:
32: #include "HTChannl.h"
33: #include "HTReq.h"
2.2 frystyk 34: #include "HTEvent.h"
2.1 frystyk 35: </PRE>
2.3 frystyk 36: <P>
37: The Host class contains information about the remote host, for example the
38: type (HTTP/1.0, HTTP/1.1, FTP etc.) along with information on how the connections
39: can be used (if it supports persistent connections, interleaved access etc.)
40: <H2>
41: Creation and Deletion Methods
42: </H2>
43: <P>
44: We keep a cache of information that we know about a remote host. This allows
2.5 frystyk 45: us to be much more detailed in generating requests. Search the host info
46: cache for a host object or create a new one and add it. Examples of host
47: names are
2.1 frystyk 48: <UL>
2.3 frystyk 49: <LI>
50: www.w3.org
51: <LI>
52: www.foo.com:8000
2.1 frystyk 53: </UL>
2.3 frystyk 54: <H3>
55: Add a Host Object
56: </H3>
2.1 frystyk 57: <PRE>
58: extern HTHost * HTHost_new (char * host);
2.7.2.1 eric 59: extern HTHost * HTHost_newWParse(HTRequest * request, char * url, u_short default_port);
2.1 frystyk 60: </PRE>
2.3 frystyk 61: <H3>
62: Delete a Host Object
63: </H3>
64: <P>
65: The Host Class contains an automatic garbage collection of Host objects so
66: that we don't keep information around that is stale.
2.6 frystyk 67: <H3>
68: Find a Host Object
69: </H3>
70: <P>
71: Searches the cache of known hosts to see if we already have information about
72: this host. If not then we return NULL.
73: <PRE>extern HTHost * HTHost_find (char * host);
74: </PRE>
2.3 frystyk 75: <H2>
76: Host Class Methods
77: </H2>
78: <P>
2.1 frystyk 79: This is what we know about the remote host
2.3 frystyk 80: <H3>
2.5 frystyk 81: Remote Host Name
82: </H3>
83: <P>
84: Get the name of the remote host. This is set automatically when a new Host
85: object and can be asked for at any point in time. You can not change the
86: host name but must create a new Host object instead.
87: <PRE>
88: extern char * HTHost_name (HTHost * host);
89: </PRE>
90: <H3>
91: Remote Host Protocol Class and Version
2.3 frystyk 92: </H3>
93: <P>
94: Define the <EM>host class</EM> of the host at the other end. A class is a
95: generic description of the protocol which is exactly like the access method
96: in a URL, for example "http" etc. The <EM>host version</EM> is a finer
97: distinction (sub-class) between various versions of the host class, for example
98: HTTP/0.9, HTTP/1.1 etc. The host version is a bit flag that the protocol
99: module can define on its own. That way we don't have to change this module
100: when registering a new protocol module. The <EM>host type</EM> is a description
101: of whether we can keep the connection persistent or not.
2.1 frystyk 102: <PRE>
103: extern char * HTHost_class (HTHost * host);
104: extern void HTHost_setClass (HTHost * host, char * s_class);
105:
106: extern int HTHost_version (HTHost * host);
107: extern void HTHost_setVersion (HTHost * host, int version);
108: </PRE>
2.3 frystyk 109: <H3>
2.4 frystyk 110: Remote host Options and Services
111: </H3>
112: <P>
2.5 frystyk 113: We keep track of the capabilities of the remote host. In many cases the
2.4 frystyk 114: information that we get is specific to servers but this doesn't <I>have</I>
115: to be the case.
116: <H4>
2.5 frystyk 117: Public Methods accessible on This Host
2.4 frystyk 118: </H4>
119: <P>
120: A server can inform a client about the supported methods using the
121: <CODE>Public</CODE> header.
122: <PRE>extern HTMethod HTHost_publicMethods (HTHost * me);
123: extern void HTHost_setPublicMethods (HTHost * me, HTMethod methodset);
124: extern void HTHost_appendPublicMethods (HTHost * me, HTMethod methodset);
125: </PRE>
126: <H4>
127: Server Name of Remote Host
128: </H4>
129: <P>
130: A server can send its server application name and version in a HTTP response.
131: We pick up this information and add it to the Host object
132: <PRE>extern char * HTHost_server (HTHost * host);
133: extern BOOL HTHost_setServer (HTHost * host, const char * server);
134: </PRE>
135: <H4>
136: User Agent Name of Remote Host
137: </H4>
138: <P>
139: A client can send the name of the client application in a HTTP request. We
2.5 frystyk 140: pick up this information and add it to the Host Object
2.4 frystyk 141: <PRE>extern char * HTHost_userAgent (HTHost * host);
142: extern BOOL HTHost_setUserAgent (HTHost * host, const char * userAgent);
143: </PRE>
2.7 frystyk 144: <H4>
145: Range Units Accepted by this Host
146: </H4>
147: <P>
148: Since all HTTP entities are represented in HTTP messages as sequences of
149: bytes, the concept of a byte range is meaningful for any HTTP entity. (However,
150: not all clients and servers need to support byte-range operations.) Byte
151: range specifications in HTTP apply to the sequence of bytes in the entity-body
152: (not necessarily the same as the message-body). A byte range operation may
153: specify a single range of bytes, or a set of ranges within a single entity.
154: <P>
155: You can also check whether a specific range unit is OK. We always say
156: <CODE>YES</CODE> except if we have a specific statement from the server that
157: it doesn't understand byte ranges - that is - it has sent "none" in a
158: "Accept-Range" response header
159: <PRE>
160: extern char * HTHost_rangeUnits (HTHost * host);
161: extern BOOL HTHost_setRangeUnits (HTHost * host, const char * units);
162: extern BOOL HTHost_isRangeUnitAcceptable (HTHost * host, const char * unit);
163: </PRE>
2.4 frystyk 164: <H3>
2.3 frystyk 165: Register a Persistent Channel
166: </H3>
167: <P>
168: We don't want more than MaxSockets-2 connections to be persistent in order
169: to avoid deadlock.
2.1 frystyk 170: <PRE>
2.7.2.1 eric 171: extern BOOL HTHost_setPersistent (HTHost * host, BOOL persistent,
172: HTTransportMode mode);
2.5 frystyk 173: extern BOOL HTHost_clearChannel (HTHost * host, int status);
2.1 frystyk 174:
175: extern HTChannel * HTHost_channel (HTHost * host);
176: </PRE>
2.3 frystyk 177: <H3>
178: Is this host Persistent?
179: </H3>
180: <P>
2.1 frystyk 181: Check whether we have a persistent channel or not
182: <PRE>
183: extern BOOL HTHost_isPersistent (HTHost * host);
184: </PRE>
2.3 frystyk 185: <H3>
2.5 frystyk 186: Is the Host Idle
187: </H3>
188: <P>
189: Before we can start a new connection to the host we must be sure that the
190: host is idle. That is, if it can accept a new connection. We have several
191: modes describing how and when a host is idle. This is a function of the Transport
192: Object
193: <PRE>
194: extern BOOL HTHost_isIdle (HTHost * host);
195: </PRE>
196: <H3>
197: Handling the Transport Mode
198: </H3>
199: <P>
200: Handle the connection mode. The mode may change mode in the middle of a
201: connection If the new mode is lower than the old mode then adjust the pipeline
202: accordingly. That is, if we are going into single mode then move all entries
203: in the pipeline and move the rest to the pending queue. They will get launched
204: at a later point in time.
205: <PRE>extern HTTransportMode HTHost_mode (HTHost * host, BOOL * active);
206: extern BOOL HTHost_setMode (HTHost * host, HTTransportMode mode);
207: </PRE>
208: <H3>
2.3 frystyk 209: Timing Persistent Channels
210: </H3>
211: <P>
212: Normally we wait for the peer process to close persistent connections but
213: in order not to use up our own resources, we have a timeout on our own. The
214: default value is 1 hour, but you can modify the value using the following
215: methods:
2.1 frystyk 216: <PRE>
217: extern time_t HTHost_persistTimeout (time_t timeout);
218: extern void HTHost_setPersistTimeout (time_t timeout);
219: </PRE>
2.3 frystyk 220: <P>
221: Each persistent connection has an absolute value of when this connection
222: most likely will expire. If the peer process does not inform us, we use our
223: own timeout.
2.1 frystyk 224: <PRE>
225: extern void HTHost_setPersistExpires (HTHost * host, time_t expires);
226: extern time_t HTHost_persistExpires (HTHost * host);
227: </PRE>
2.5 frystyk 228: <H2>
229: Queuing Requests
230: </H2>
231: <P>
232: Requests are queued in the Host object until we have resources to start them.
233: The request is in the form of a Net object as we may have multiple socket
234: requests per <A HREF="HTReq.html">Request object</A>. This is for example
235: the case with <A HREF="WWWFTp.html">FTP</A> which uses two connections.
236: <PRE>extern int HTHost_addNet (HTHost * host, HTNet * net);
2.7.2.1 eric 237: extern BOOL HTHost_free (HTHost * host, int status);
2.5 frystyk 238: extern BOOL HTHost_deleteNet (HTHost * host, HTNet * net);
239: extern HTList * HTHost_net (HTHost * host);
240: </PRE>
241: <H3>
242: Is the Host Idle
243: </H3>
244: <P>
245: Before we can start a new connection to the host we must be sure that the
246: host is idle. That is, if it can accept a new connection. We have several
247: modes describing how and when a host is idle. This is a function of the
248: <A HREF="HTTrans.html">Transport Object</A>
249: <PRE>extern BOOL HTHost_isIdle (HTHost * host);
250: </PRE>
2.3 frystyk 251: <H3>
2.5 frystyk 252: Handling Pending Requests
2.3 frystyk 253: </H3>
254: <P>
2.5 frystyk 255: There are two ways we can end up with pending reqyests:
256: <OL>
257: <LI>
258: If we are out of sockets then register new host objects as pending.
259: <LI>
260: If we are pending on a connection then register new net objects as pending
261: </OL>
262: <P>
263: This set of functions handles pending host objects and can start new requests
264: as resources get available. The first function checks the host object for
265: any pending <A HREF="HTNet.html">Net objects</A> and return the first of
266: these Net objects.
2.3 frystyk 267: <PRE>
2.5 frystyk 268: extern HTNet * HTHost_nextPendingNet (HTHost * host);
269: </PRE>
270: <P>
271: The second checks the list of pending host objects waiting for a socket and
272: returns the first of these Host objects.
273: <PRE>
274: extern HTHost * HTHost_nextPendingHost (void);
275: </PRE>
276: <P>
277: Start the next pending request if any. First we look for pending requests
278: for the same host and then we check for any other pending hosts. If nothing
279: pending then register a catch close event handler to have something catching
280: the socket if the remote server closes the connection, for example due to
281: timeout.
2.7.2.1 eric 282: <PRE>
283: extern BOOL HTHost_launchPending (HTHost * host);
284: #if 0
285: extern int HTHost_connect(HTHost * host, HTAnchor * anchor, HTRequest * request,
286: int retry, int preemptive, HTEvents events[HTEvent_TYPES]);
287: #endif
288: extern HTNet * HTHost_firstNet(HTHost * host);
289: </PRE>
290: HTHost clients can use the host for all IO and take advantage of host multiplexing
291: and pipelining.
292: <PRE>
2.7.2.2 ! eric 293: extern int HTHost_register(HTHost * host, HTNet * net, HTEventType type);
! 294: extern int HTHost_unregister(HTHost * host, HTNet * net, HTEventType type);
! 295: extern int HTHost_tickleFirstNet(HTHost * host, HTEventType type);
2.7.2.1 eric 296: extern BOOL HTHost_setRemainingRead(HTHost * host, size_t remainaing);
297: extern SockA * HTHost_getSockAddr(HTHost * host);
298: extern BOOL HTHost_setHome (HTHost * host, int home);
299: extern int HTHost_home (HTHost * host);
300: extern BOOL HTHost_setChannel (HTHost * host, HTChannel * channel);
301: extern HTNet * HTHost_getReadNet(HTHost * host);
302: extern HTInputStream * HTHost_getInput (HTHost * host, HTTransport * transport,
303: void * param, int mode);
304: extern int HTHost_read(HTHost * host);
305: extern BOOL HTHost_setConsumed(HTHost * host, size_t bytes);
2.3 frystyk 306: </PRE>
2.1 frystyk 307: <PRE>
308: #endif /* HTHOST_H */
309: </PRE>
2.3 frystyk 310: <P>
311: <HR>
2.1 frystyk 312: <ADDRESS>
2.7.2.2 ! eric 313: @(#) $Id: HTHost.html,v 2.7.2.1 1996/10/29 21:27:39 eric Exp $
2.1 frystyk 314: </ADDRESS>
2.3 frystyk 315: </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