Annotation of libwww/Library/src/HTProxy.html, revision 2.15
2.1 frystyk 1: <HTML>
2: <HEAD>
2.11 frystyk 3: <TITLE>W3C Sample Code Library libwww Proxies and Gateways</TITLE>
2.1 frystyk 4: </HEAD>
5: <BODY>
2.10 frystyk 6: <H1>
7: Proxy and gateway Manager
8: </H1>
2.1 frystyk 9: <PRE>
10: /*
11: ** (c) COPYRIGHT MIT 1995.
12: ** Please first read the full copyright statement in the file COPYRIGH.
13: */
14: </PRE>
2.10 frystyk 15: <P>
16: This module keeps a list of proxies and gateways to be contacted on a request
17: in stead of requesting it directly from the origin server. The module replaces
18: the old system of environment variables for gateways and proxies. However
19: for backward compatibility there is a function that reads the environment
20: variables at start up. Note that there is a difference between a proxy and
21: a gateway - the difference is the way the URL is set up in the
22: <EM>RequestLine</EM> of the HTTP request. If the original, full URL looks
23: like <CODE>"http://www.w3.org/test.html"</CODE> then the result will for
24: a proxy is <CODE>"http://www.w3.org/test.html"</CODE> and a gateway
25: <CODE>"/www.w3.org/test.html"</CODE>
26: <P>
27: The module is implemented by <A HREF="HTProxy.c">HTProxy.c</A>, and it is
2.12 frystyk 28: a part of the <A HREF="http://www.w3.org/Library/"> W3C Sample Code
2.10 frystyk 29: Library</A>.
2.15 ! vbancrof 30: <PRE>
! 31: #ifndef HTPROXY_H
2.1 frystyk 32: #define HTPROXY_H
33:
2.15 ! vbancrof 34: #ifdef __cplusplus
! 35: extern "C" {
! 36: #endif
! 37:
2.1 frystyk 38: #include "HTList.h"
39: </PRE>
2.10 frystyk 40: <H2>
2.13 frystyk 41: Registering a Proxy Server
2.10 frystyk 42: </H2>
43: <P>
44: A proxy server is registered with a corresponding access method, for example
45: <EM>http</EM>, <EM>ftp</EM> etc. The `proxy' parameter should be a fully
46: valid name, like <CODE>http://proxy.w3.org:8001</CODE> but domain name is
47: not required. If an entry exists for this access then delete it and use the
48: new one.
2.1 frystyk 49: <PRE>
2.6 frystyk 50: extern BOOL HTProxy_add (const char * access, const char * proxy);
2.13 frystyk 51: </PRE>
52: <H3>
53: Registering a Proxy Using Regular Expressions
54: </H3>
55: <P>
56: Registers a proxy as the server to contact for any URL matching the regular
57: expression. This requires that you have compiled with the
58: <TT>HT_POSIX_REGEX</TT> flag, see the <A HREF="../../INSTALL.html">installation
59: instructions</A>. If you call this function without having compiled with
60: the <TT>HT_POSIX_REGEX</TT> flag then you will essentially get the non-regex
61: version. The name of the proxy should be a fully valid URL, like
62: "<TT>http://proxy.w3.org:8001</TT>". Returns YES if OK, else NO
63: <PRE>
64: extern BOOL HTProxy_addRegex (const char * regex,
65: const char * proxy,
66: int regex_flags);
67: </PRE>
68: <H3>
69: Deleting All Registered Proxies
70: </H3>
71: <PRE>
2.5 frystyk 72: extern BOOL HTProxy_deleteAll (void);
2.1 frystyk 73: </PRE>
2.10 frystyk 74: <P>
75: The remove function removes all registered proxies. This is automatically
76: done in <A HREF="HTLib.html"> HTLibTerminate()</A> <A NAME="noproxy"></A>
77: <H2>
2.13 frystyk 78: Registering a No Proxy Location
2.10 frystyk 79: </H2>
80: <P>
81: The <EM>noproxy</EM> list is a list of host names and domain names where
82: we don't contact a proxy even though a proxy is in fact registered for this
83: particular access method . When registering a <EM>noproxy</EM> item, you
84: can specify a specific port for this access method in which case it isvalid
85: only for requests to this port. If `port' is '0' then it applies to all ports
86: and if `access' is NULL then it applies to to all access methods. Examples
87: of host names are <CODE>w3.org</CODE> and <CODE>www.close.com</CODE>
2.1 frystyk 88: <PRE>
2.6 frystyk 89: extern BOOL HTNoProxy_add (const char * host, const char * access,
2.5 frystyk 90: unsigned port);
2.13 frystyk 91: </PRE>
92: <H3>
93: Registering a NoProxy Location Using Regular Expressions
94: </H3>
95: <P>
96: Registers a regular expression where URIs matching this expression should
97: go directly and not via a proxy. Examples:
98: <CODE>http://<star>\.w3\.org</CODE> and
99: <CODE>http://www\.noproxy\.com/<star></CODE> (I use
100: <TT><star></TT> in order not interfere with C comments) This requires
101: that you have compiled with the <TT>HT_POSIX_REGEX</TT> flag, see the
102: <A HREF="../../INSTALL.html">installation instructions</A>. If you call this
103: function without having compiled with the <TT>HT_POSIX_REGEX</TT> flag then
104: you will essentially get the non-regex version.
105: <PRE>
106: extern BOOL HTNoProxy_addRegex (const char * regex, int regex_flags);
107: </PRE>
108: <H3>
109: Delete all Noproxy Destinations
110: </H3>
111: <PRE>
2.5 frystyk 112: extern BOOL HTNoProxy_deleteAll (void);
2.1 frystyk 113: </PRE>
2.10 frystyk 114: <P>
115: The remove function removes all entries in the list. This is automatically
116: done in <A HREF="HTLib.html"> HTLibTerminate()</A>
2.14 kahan 117: <H3>
118: Inverse the meaning of the NoProxy list
119: </H3>
120: <P>
121: Allows to change the value of a flag so that the NoProxy list is interpreted
122: as if it were an OnlyProxy list.
123: <PRE>
124: extern int HTProxy_NoProxyIsOnlyProxy (void);
125: extern void HTProxy_setNoProxyIsOnlyProxy (int value);
126: </PRE>
2.10 frystyk 127: <H2>
128: Look for a Proxy server
129: </H2>
130: <P>
131: This function evaluates the lists of registered proxies and if one is found
132: for the actual access method and it is not registered in the `noproxy' list,
133: then a URL containing the host to be contacted is returned to the caller.
134: This string must be freed be the caller.
2.1 frystyk 135: <PRE>
2.6 frystyk 136: extern char * HTProxy_find (const char * url);
2.1 frystyk 137: </PRE>
2.10 frystyk 138: <H2>
139: Registering a gateway
140: </H2>
141: <P>
142: A gateway is registered with a corresponding access method, for example
143: <EM>http</EM>, <EM>ftp</EM> etc. The `gate' parameter should be a fully valid
144: name, like <CODE>http://gateway.w3.org:8001</CODE> but domain name is not
145: required. If an entry exists for this access then delete it and use the new
146: one.
2.1 frystyk 147: <PRE>
2.6 frystyk 148: extern BOOL HTGateway_add (const char * access, const char * gate);
2.5 frystyk 149: extern BOOL HTGateway_deleteAll (void);
2.1 frystyk 150: </PRE>
2.10 frystyk 151: <P>
152: The remove function removes all registered proxies. This is automatically
153: done in <A HREF="HTLib.html"> HTLibTerminate()</A>
154: <H2>
155: Look for a Gateway
156: </H2>
157: <P>
158: This function evaluates the lists of registered gateways and if one is found
159: for the actual access method then it is returned and must be freed by the
160: caller.
2.1 frystyk 161: <PRE>
2.6 frystyk 162: extern char * HTGateway_find (const char * url);
2.1 frystyk 163: </PRE>
2.10 frystyk 164: <H2>
165: Backwards Compability with Environment Variables
166: </H2>
167: <P>
168: This function maintains backwards compatibility with the old environment
169: variables and searches for the most common values: http, ftp, news, wais,
170: and gopher
2.1 frystyk 171: <PRE>
2.5 frystyk 172: extern void HTProxy_getEnvVar (void);
2.1 frystyk 173: </PRE>
174: <PRE>
2.15 ! vbancrof 175: #ifdef __cplusplus
! 176: }
! 177: #endif
! 178:
2.1 frystyk 179: #endif /* HTPROXY_H */
180: </PRE>
2.10 frystyk 181: <P>
182: <HR>
2.8 frystyk 183: <ADDRESS>
2.15 ! vbancrof 184: @(#) $Id: HTProxy.html,v 2.14 2000/02/29 14:25:59 kahan Exp $
2.8 frystyk 185: </ADDRESS>
2.10 frystyk 186: </BODY></HTML>
Webmaster