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