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