Annotation of libwww/Library/src/HTHost.html, revision 2.1
2.1 ! frystyk 1: <HTML>
! 2: <HEAD>
! 3: <TITLE>W3C Reference Library libwww Remote host information</TITLE>
! 4: <!-- Changed by: Henrik Frystyk Nielsen, 5-Apr-1996 -->
! 5: </HEAD>
! 6: <BODY>
! 7:
! 8: <H1>Remote Host Information</H1>
! 9:
! 10: <PRE>
! 11: /*
! 12: ** (c) COPYRIGHT MIT 1995.
! 13: ** Please first read the full copyright statement in the file COPYRIGH.
! 14: */
! 15: </PRE>
! 16:
! 17: This object manages the information that we know about a remote host.
! 18: This can for example be what type of host it is, and what version it
! 19: is using. Notive that a host can be both a server or a client. All
! 20: information in this module can be shared regardless of whether it is
! 21: to be used in a server application or a client application.<P>
! 22:
! 23: This module is implemented by <A HREF="HTHost.c">HTHost.c</A>, and it
! 24: is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C
! 25: Reference Library</A>.
! 26:
! 27: <PRE>
! 28: #ifndef HTHOST_H
! 29: #define HTHOST_H
! 30:
! 31: typedef struct _HTHost HTHost;
! 32:
! 33: #include "HTChannl.h"
! 34: #include "HTReq.h"
! 35: #include "HTEvntrg.h"
! 36: </PRE>
! 37:
! 38: <H2>The Host Object</H2>
! 39:
! 40: The Host object contains information about the remote host, for
! 41: example the type (HTTP/1.0, HTTP/1.1, FTP etc.) along with information
! 42: on how the connections can be used (if it supports persistent
! 43: connections, interleaved access etc.)
! 44:
! 45: <H2>Create a Host Object</H2>
! 46:
! 47: We keep a cache of information that we know about a remote host. This
! 48: allows us to be much more detailed in geneating requests. Search the
! 49: host info cache for a host object or create a new one and add
! 50: it. Examples of host names are
! 51:
! 52: <UL>
! 53: <LI>www.w3.org
! 54: <LI>www.foo.com:8000
! 55: </UL>
! 56:
! 57: <PRE>
! 58: extern HTHost * HTHost_new (char * host);
! 59: </PRE>
! 60:
! 61: <H2>Remote Host Information</H2>
! 62:
! 63: This is what we know about the remote host
! 64:
! 65: <H3>Set the Host Class and Version</H3>
! 66:
! 67: Define the <EM>host class</EM> of the host at the other end. A
! 68: class is a generic description of the protocol which is exactly like
! 69: the access method in a URL, for example "http" etc. The <EM>host
! 70: version</EM> is a finer distinction (sub-class) between various
! 71: versions of the host class, for example HTTP/0.9, HTTP/1.1 etc. The
! 72: host version is a bit flag that the protocol module can define on
! 73: its own. That way we don't have to change this module when registering
! 74: a new protocol module. The <EM>host type</EM> is a description of
! 75: whether we can keep the connection persistent or not.
! 76:
! 77: <PRE>
! 78: extern char * HTHost_class (HTHost * host);
! 79: extern void HTHost_setClass (HTHost * host, char * s_class);
! 80:
! 81: extern int HTHost_version (HTHost * host);
! 82: extern void HTHost_setVersion (HTHost * host, int version);
! 83: </PRE>
! 84:
! 85: <H2>Persistent Channels</H2>
! 86:
! 87: The HTHost object is also responsible for handline persistent connections
! 88:
! 89: <H3>Register a Persistent Channel</H3>
! 90:
! 91: We don't want more than MaxSockets-2 connections to be persistent in order to avoid deadlock.
! 92:
! 93: <PRE>
! 94: extern BOOL HTHost_setChannel (HTHost * host, HTChannel * channel);
! 95: extern BOOL HTHost_clearChannel (HTHost * host);
! 96:
! 97: extern HTChannel * HTHost_channel (HTHost * host);
! 98: </PRE>
! 99:
! 100: <H3>Is this host Persistent?</H3>
! 101:
! 102: Check whether we have a persistent channel or not
! 103:
! 104: <PRE>
! 105: extern BOOL HTHost_isPersistent (HTHost * host);
! 106: </PRE>
! 107:
! 108: <H3>Catching a Close Event</H3>
! 109:
! 110: This function is registered when the socket is idle so that we get a
! 111: notification if the socket closes at the other end. At this point we
! 112: can't use the request object as it might have been freed a long time
! 113: ago.
! 114:
! 115: <PRE>
! 116: extern int HTHost_catchClose (SOCKET soc, HTRequest * request, SockOps ops);
! 117: </PRE>
! 118:
! 119: <H3>Timing Persistent Channels</H3>
! 120:
! 121: Normally we wait for the peer process to close persistent connections
! 122: but in order not to use up our own resources, we have a timeout on our
! 123: own. The default value is 1 hour, but you can modify the value using
! 124: the following methods:
! 125:
! 126: <PRE>
! 127: extern time_t HTHost_persistTimeout (time_t timeout);
! 128: extern void HTHost_setPersistTimeout (time_t timeout);
! 129: </PRE>
! 130:
! 131: Each persistent connection has an absolute value of when this
! 132: connection most likely will expire. If the peer process does not
! 133: inform us, we use our own timeout.
! 134:
! 135: <PRE>
! 136: extern void HTHost_setPersistExpires (HTHost * host, time_t expires);
! 137: extern time_t HTHost_persistExpires (HTHost * host);
! 138: </PRE>
! 139:
! 140: <PRE>
! 141: #endif /* HTHOST_H */
! 142: </PRE>
! 143:
! 144: <HR>
! 145: <ADDRESS>
! 146: @(#) $Id: Date Author State $
! 147: </ADDRESS>
! 148: </BODY>
! 149: </HTML>
Webmaster