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