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