Annotation of libwww/Library/src/HTHost.html, revision 2.4
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
45: us to be much more detailed in geneating requests. Search the host info cache
46: for a host object or create a new one and add it. Examples of host names
47: are
48: <P>
2.1 frystyk 49: <UL>
2.3 frystyk 50: <LI>
51: www.w3.org
52: <LI>
53: www.foo.com:8000
2.1 frystyk 54: </UL>
2.3 frystyk 55: <H3>
56: Add a Host Object
57: </H3>
2.1 frystyk 58: <PRE>
59: extern HTHost * HTHost_new (char * host);
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.
67: <H2>
68: Host Class Methods
69: </H2>
70: <P>
2.1 frystyk 71: This is what we know about the remote host
2.3 frystyk 72: <H3>
2.4 ! frystyk 73: Remote Host Prococol Class and Version
2.3 frystyk 74: </H3>
75: <P>
76: Define the <EM>host class</EM> of the host at the other end. A class is a
77: generic description of the protocol which is exactly like the access method
78: in a URL, for example "http" etc. The <EM>host version</EM> is a finer
79: distinction (sub-class) between various versions of the host class, for example
80: HTTP/0.9, HTTP/1.1 etc. The host version is a bit flag that the protocol
81: module can define on its own. That way we don't have to change this module
82: when registering a new protocol module. The <EM>host type</EM> is a description
83: of whether we can keep the connection persistent or not.
2.1 frystyk 84: <PRE>
85: extern char * HTHost_class (HTHost * host);
86: extern void HTHost_setClass (HTHost * host, char * s_class);
87:
88: extern int HTHost_version (HTHost * host);
89: extern void HTHost_setVersion (HTHost * host, int version);
90: </PRE>
2.3 frystyk 91: <H3>
2.4 ! frystyk 92: Remote host Options and Services
! 93: </H3>
! 94: <P>
! 95: We keep track of the capabilities of the remote host. In many caces the
! 96: information that we get is specific to servers but this doesn't <I>have</I>
! 97: to be the case.
! 98: <H4>
! 99: Public Methods
! 100: </H4>
! 101: <P>
! 102: A server can inform a client about the supported methods using the
! 103: <CODE>Public</CODE> header.
! 104: <PRE>extern HTMethod HTHost_publicMethods (HTHost * me);
! 105: extern void HTHost_setPublicMethods (HTHost * me, HTMethod methodset);
! 106: extern void HTHost_appendPublicMethods (HTHost * me, HTMethod methodset);
! 107: </PRE>
! 108: <H4>
! 109: Server Name of Remote Host
! 110: </H4>
! 111: <P>
! 112: A server can send its server application name and version in a HTTP response.
! 113: We pick up this information and add it to the Host object
! 114: <PRE>extern char * HTHost_server (HTHost * host);
! 115: extern BOOL HTHost_setServer (HTHost * host, const char * server);
! 116: </PRE>
! 117: <H4>
! 118: User Agent Name of Remote Host
! 119: </H4>
! 120: <P>
! 121: A client can send the name of the client application in a HTTP request. We
! 122: pick up this infomration and add it to the Host Object
! 123: <PRE>extern char * HTHost_userAgent (HTHost * host);
! 124: extern BOOL HTHost_setUserAgent (HTHost * host, const char * userAgent);
! 125: </PRE>
! 126: <H3>
2.3 frystyk 127: Register a Persistent Channel
128: </H3>
129: <P>
130: We don't want more than MaxSockets-2 connections to be persistent in order
131: to avoid deadlock.
2.1 frystyk 132: <PRE>
133: extern BOOL HTHost_setChannel (HTHost * host, HTChannel * channel);
134: extern BOOL HTHost_clearChannel (HTHost * host);
135:
136: extern HTChannel * HTHost_channel (HTHost * host);
137: </PRE>
2.3 frystyk 138: <H3>
139: Is this host Persistent?
140: </H3>
141: <P>
2.1 frystyk 142: Check whether we have a persistent channel or not
143: <PRE>
144: extern BOOL HTHost_isPersistent (HTHost * host);
145: </PRE>
2.3 frystyk 146: <H3>
147: Timing Persistent Channels
148: </H3>
149: <P>
150: Normally we wait for the peer process to close persistent connections but
151: in order not to use up our own resources, we have a timeout on our own. The
152: default value is 1 hour, but you can modify the value using the following
153: methods:
2.1 frystyk 154: <PRE>
155: extern time_t HTHost_persistTimeout (time_t timeout);
156: extern void HTHost_setPersistTimeout (time_t timeout);
157: </PRE>
2.3 frystyk 158: <P>
159: Each persistent connection has an absolute value of when this connection
160: most likely will expire. If the peer process does not inform us, we use our
161: own timeout.
2.1 frystyk 162: <PRE>
163: extern void HTHost_setPersistExpires (HTHost * host, time_t expires);
164: extern time_t HTHost_persistExpires (HTHost * host);
165: </PRE>
2.3 frystyk 166: <H3>
167: Catching a Close Event
168: </H3>
169: <P>
170: This function is registered when the socket is idle so that we get a notification
171: if the socket closes at the other end. At this point we can't use the request
172: object as it might have been freed a long time ago.
173: <PRE>
174: extern int HTHost_catchClose (SOCKET soc, HTRequest * request, SockOps ops);
175: </PRE>
2.1 frystyk 176: <PRE>
177: #endif /* HTHOST_H */
178: </PRE>
2.3 frystyk 179: <P>
180: <HR>
2.1 frystyk 181: <ADDRESS>
2.4 ! frystyk 182: @(#) $Id: HTHost.html,v 2.3 1996/05/20 15:06:48 frystyk Exp $
2.1 frystyk 183: </ADDRESS>
2.3 frystyk 184: </BODY></HTML>
Webmaster