Proxy and gateway Manager

/*
**	(c) COPYRIGHT MIT 1995.
**	Please first read the full copyright statement in the file COPYRIGH.
*/

This module keeps a list of proxies and gateways to be contacted on a request in stead of requesting it directly from the origin server. The module replaces the old system of environment variables for gateways and proxies. However for backward compatibility there is a function that reads the environment variables at start up. Note that there is a difference between a proxy and a gateway - the difference is the way the URL is set up in the RequestLine of the HTTP request. If the original, full URL looks like "http://www.w3.org/test.html" then the result will for a proxy is "http://www.w3.org/test.html" and a gateway "/www.w3.org/test.html"

The module is implemented by HTProxy.c, and it is a part of the W3C Sample Code Library.

#ifndef HTPROXY_H
#define HTPROXY_H

#ifdef __cplusplus
extern "C" { 
#endif 

#include "HTList.h"

Registering a Proxy Server

A proxy server is registered with a corresponding access method, for example http, ftp etc. The `proxy' parameter should be a fully valid name, like http://proxy.w3.org:8001 but domain name is not required. If an entry exists for this access then delete it and use the new one.

extern BOOL HTProxy_add		(const char * access, const char * proxy);

Registering a Proxy Using Regular Expressions

Registers a proxy as the server to contact for any URL matching the regular expression. This requires that you have compiled with the HT_POSIX_REGEX flag, see the installation instructions. If you call this function without having compiled with the HT_POSIX_REGEX flag then you will essentially get the non-regex version. The name of the proxy should be a fully valid URL, like "http://proxy.w3.org:8001". Returns YES if OK, else NO

extern BOOL HTProxy_addRegex (const char * regex,
                              const char * proxy,
                              int regex_flags);

Deleting All Registered Proxies

extern BOOL HTProxy_deleteAll	(void);

The remove function removes all registered proxies. This is automatically done in HTLibTerminate()

Registering a No Proxy Location

The noproxy list is a list of host names and domain names where we don't contact a proxy even though a proxy is in fact registered for this particular access method . When registering a noproxy item, you can specify a specific port for this access method in which case it isvalid only for requests to this port. If `port' is '0' then it applies to all ports and if `access' is NULL then it applies to to all access methods. Examples of host names are w3.org and www.close.com

extern BOOL HTNoProxy_add	(const char * host, const char * access,
				 unsigned port);

Registering a NoProxy Location Using Regular Expressions

Registers a regular expression where URIs matching this expression should go directly and not via a proxy. Examples: http://<star>\.w3\.org and http://www\.noproxy\.com/<star> (I use <star> in order not interfere with C comments) This requires that you have compiled with the HT_POSIX_REGEX flag, see the installation instructions. If you call this function without having compiled with the HT_POSIX_REGEX flag then you will essentially get the non-regex version. 

extern BOOL HTNoProxy_addRegex (const char * regex, int regex_flags);

Delete all Noproxy Destinations

extern BOOL HTNoProxy_deleteAll	(void);

The remove function removes all entries in the list. This is automatically done in HTLibTerminate()

Inverse the meaning of the NoProxy list

Allows to change the value of a flag so that the NoProxy list is interpreted as if it were an OnlyProxy list.

extern int  HTProxy_NoProxyIsOnlyProxy (void);
extern void HTProxy_setNoProxyIsOnlyProxy (int value);

Look for a Proxy server

This function evaluates the lists of registered proxies and if one is found for the actual access method and it is not registered in the `noproxy' list, then a URL containing the host to be contacted is returned to the caller. This string must be freed be the caller.

extern char * HTProxy_find	(const char * url);

Registering a gateway

A gateway is registered with a corresponding access method, for example http, ftp etc. The `gate' parameter should be a fully valid name, like http://gateway.w3.org:8001 but domain name is not required. If an entry exists for this access then delete it and use the new one.

extern BOOL HTGateway_add	(const char * access, const char * gate);
extern BOOL HTGateway_deleteAll	(void);

The remove function removes all registered proxies. This is automatically done in HTLibTerminate()

Look for a Gateway

This function evaluates the lists of registered gateways and if one is found for the actual access method then it is returned and must be freed by the caller.

extern char * HTGateway_find	(const char * url);

Backwards Compability with Environment Variables

This function maintains backwards compatibility with the old environment variables and searches for the most common values: http, ftp, news, wais, and gopher

extern void HTProxy_getEnvVar	(void);

#ifdef __cplusplus
}
#endif

#endif /* HTPROXY_H */