Annotation of libwww/Library/src/HTHost.html, revision 2.6
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>
143: <H3>
2.3 frystyk 144: Register a Persistent Channel
145: </H3>
146: <P>
147: We don't want more than MaxSockets-2 connections to be persistent in order
148: to avoid deadlock.
2.1 frystyk 149: <PRE>
2.5 frystyk 150: extern BOOL HTHost_setChannel (HTHost * host, HTChannel * channel,
151: HTTransportMode mode);
152: extern BOOL HTHost_clearChannel (HTHost * host, int status);
2.1 frystyk 153:
154: extern HTChannel * HTHost_channel (HTHost * host);
155: </PRE>
2.3 frystyk 156: <H3>
157: Is this host Persistent?
158: </H3>
159: <P>
2.1 frystyk 160: Check whether we have a persistent channel or not
161: <PRE>
162: extern BOOL HTHost_isPersistent (HTHost * host);
163: </PRE>
2.3 frystyk 164: <H3>
2.5 frystyk 165: Is the Host Idle
166: </H3>
167: <P>
168: Before we can start a new connection to the host we must be sure that the
169: host is idle. That is, if it can accept a new connection. We have several
170: modes describing how and when a host is idle. This is a function of the Transport
171: Object
172: <PRE>
173: extern BOOL HTHost_isIdle (HTHost * host);
174: </PRE>
175: <H3>
176: Handling the Transport Mode
177: </H3>
178: <P>
179: Handle the connection mode. The mode may change mode in the middle of a
180: connection If the new mode is lower than the old mode then adjust the pipeline
181: accordingly. That is, if we are going into single mode then move all entries
182: in the pipeline and move the rest to the pending queue. They will get launched
183: at a later point in time.
184: <PRE>extern HTTransportMode HTHost_mode (HTHost * host, BOOL * active);
185: extern BOOL HTHost_setMode (HTHost * host, HTTransportMode mode);
186: </PRE>
187: <H3>
2.3 frystyk 188: Timing Persistent Channels
189: </H3>
190: <P>
191: Normally we wait for the peer process to close persistent connections but
192: in order not to use up our own resources, we have a timeout on our own. The
193: default value is 1 hour, but you can modify the value using the following
194: methods:
2.1 frystyk 195: <PRE>
196: extern time_t HTHost_persistTimeout (time_t timeout);
197: extern void HTHost_setPersistTimeout (time_t timeout);
198: </PRE>
2.3 frystyk 199: <P>
200: Each persistent connection has an absolute value of when this connection
201: most likely will expire. If the peer process does not inform us, we use our
202: own timeout.
2.1 frystyk 203: <PRE>
204: extern void HTHost_setPersistExpires (HTHost * host, time_t expires);
205: extern time_t HTHost_persistExpires (HTHost * host);
206: </PRE>
2.5 frystyk 207: <H2>
208: Queuing Requests
209: </H2>
210: <P>
211: Requests are queued in the Host object until we have resources to start them.
212: The request is in the form of a Net object as we may have multiple socket
213: requests per <A HREF="HTReq.html">Request object</A>. This is for example
214: the case with <A HREF="WWWFTp.html">FTP</A> which uses two connections.
215: <PRE>extern int HTHost_addNet (HTHost * host, HTNet * net);
216: extern BOOL HTHost_deleteNet (HTHost * host, HTNet * net);
217: extern HTList * HTHost_net (HTHost * host);
218: </PRE>
219: <H3>
220: Is the Host Idle
221: </H3>
222: <P>
223: Before we can start a new connection to the host we must be sure that the
224: host is idle. That is, if it can accept a new connection. We have several
225: modes describing how and when a host is idle. This is a function of the
226: <A HREF="HTTrans.html">Transport Object</A>
227: <PRE>extern BOOL HTHost_isIdle (HTHost * host);
228: </PRE>
2.3 frystyk 229: <H3>
2.5 frystyk 230: Handling Pending Requests
2.3 frystyk 231: </H3>
232: <P>
2.5 frystyk 233: There are two ways we can end up with pending reqyests:
234: <OL>
235: <LI>
236: If we are out of sockets then register new host objects as pending.
237: <LI>
238: If we are pending on a connection then register new net objects as pending
239: </OL>
240: <P>
241: This set of functions handles pending host objects and can start new requests
242: as resources get available. The first function checks the host object for
243: any pending <A HREF="HTNet.html">Net objects</A> and return the first of
244: these Net objects.
2.3 frystyk 245: <PRE>
2.5 frystyk 246: extern HTNet * HTHost_nextPendingNet (HTHost * host);
247: </PRE>
248: <P>
249: The second checks the list of pending host objects waiting for a socket and
250: returns the first of these Host objects.
251: <PRE>
252: extern HTHost * HTHost_nextPendingHost (void);
253: </PRE>
254: <P>
255: Start the next pending request if any. First we look for pending requests
256: for the same host and then we check for any other pending hosts. If nothing
257: pending then register a catch close event handler to have something catching
258: the socket if the remote server closes the connection, for example due to
259: timeout.
260: <PRE>extern BOOL HTHost_launchPending (HTHost * host);
2.3 frystyk 261: </PRE>
2.1 frystyk 262: <PRE>
263: #endif /* HTHOST_H */
264: </PRE>
2.3 frystyk 265: <P>
266: <HR>
2.1 frystyk 267: <ADDRESS>
2.6 ! frystyk 268: @(#) $Id: HTHost.html,v 2.5 1996/08/19 18:30:37 frystyk Exp $
2.1 frystyk 269: </ADDRESS>
2.3 frystyk 270: </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