Annotation of libwww/Library/src/HTProxy.html, revision 2.13
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>
112: <H2>
113: Look for a Proxy server
114: </H2>
115: <P>
116: This function evaluates the lists of registered proxies and if one is found
117: for the actual access method and it is not registered in the `noproxy' list,
118: then a URL containing the host to be contacted is returned to the caller.
119: This string must be freed be the caller.
2.1 frystyk 120: <PRE>
2.6 frystyk 121: extern char * HTProxy_find (const char * url);
2.1 frystyk 122: </PRE>
2.10 frystyk 123: <H2>
124: Registering a gateway
125: </H2>
126: <P>
127: A gateway is registered with a corresponding access method, for example
128: <EM>http</EM>, <EM>ftp</EM> etc. The `gate' parameter should be a fully valid
129: name, like <CODE>http://gateway.w3.org:8001</CODE> but domain name is not
130: required. If an entry exists for this access then delete it and use the new
131: one.
2.1 frystyk 132: <PRE>
2.6 frystyk 133: extern BOOL HTGateway_add (const char * access, const char * gate);
2.5 frystyk 134: extern BOOL HTGateway_deleteAll (void);
2.1 frystyk 135: </PRE>
2.10 frystyk 136: <P>
137: The remove function removes all registered proxies. This is automatically
138: done in <A HREF="HTLib.html"> HTLibTerminate()</A>
139: <H2>
140: Look for a Gateway
141: </H2>
142: <P>
143: This function evaluates the lists of registered gateways and if one is found
144: for the actual access method then it is returned and must be freed by the
145: caller.
2.1 frystyk 146: <PRE>
2.6 frystyk 147: extern char * HTGateway_find (const char * url);
2.1 frystyk 148: </PRE>
2.10 frystyk 149: <H2>
150: Backwards Compability with Environment Variables
151: </H2>
152: <P>
153: This function maintains backwards compatibility with the old environment
154: variables and searches for the most common values: http, ftp, news, wais,
155: and gopher
2.1 frystyk 156: <PRE>
2.5 frystyk 157: extern void HTProxy_getEnvVar (void);
2.1 frystyk 158: </PRE>
159: <PRE>
160: #endif /* HTPROXY_H */
161: </PRE>
2.10 frystyk 162: <P>
163: <HR>
2.8 frystyk 164: <ADDRESS>
2.13 ! frystyk 165: @(#) $Id: HTProxy.html,v 2.12 1998/05/14 02:10:56 frystyk Exp $
2.8 frystyk 166: </ADDRESS>
2.10 frystyk 167: </BODY></HTML>
Webmaster