NAME

HTTP::ProxyAutoConfig - use a .pac or wpad.dat file to get proxy information

SYNOPSIS

  use HTTP::ProxyAutoConfig;

  my $pac = HTTP::ProxyAutoConfig->new("http://foo.bar/auto-proxy.pac");
  my $pac = new HTTP::ProxyAutoConfig('/Documents and Settings/me/proxy.pac');
  my $pac = HTTP::ProxyAutoConfig->new();

  my $proxy = $pac->FindProxy('http://www.yahoo.com');

DESCRIPTION

HTTP::ProxyAutoConfig allows perl scripts that need to access the Internet to determine whether to do so via a proxy server. To do this, it uses proxy settings provided by an IT department, either on the Web or in a browser's .pac file on disk.

It provides means to find the proxy server (or lack of one) for a given URL. If your application has located either a wpad.dat file or a .pac file, HTTP::ProxyAutoConfig processes it to determine how to handle a particular destination URL. If it's not given a wpad.dat or .pac file, HTTP::ProxyAutoConfig tests environment variables to determine whether there's a proxy server.

A wpad.dat or .pac file contains a JavaScript function called FindProxyForURL. This module allows you to call the function to learn how to access various URLs.

Mapping from a URL to the proxy information is provided by a FindProxyForURL(url, host) or FindProxy(url) function call. Both functions return a string that tells your application what to do, namely a direct connection to the Internet or a connection via a proxy server.

The Proxy Auto Config format and rules were originally developed at Netscape. The Netscape documentation is archived at http://linuxmafia.com/faq/Web/autoproxy.html

More recent references include:

http://en.wikipedia.org/wiki/Proxy_auto-config

http://en.wikipedia.org/wiki/Web_Proxy_Autodiscovery_Protocol

http://www.craigjconsulting.com/proxypac.html

http://www.returnproxy.com/proxypac/

METHODS

new( url_or_file )

This call creates the FindProxyForURL function and the object through which it can be called. The url_or_file argument is optional, and points to the auto-proxy file provided on your network or a file used by your browser. If there is no argument, HTTP::ProxyAutoConfig will check the http_auto_proxy environment variable, followed by the http_proxy, https_proxy, and ftp_proxy variables.

As shown above, you can use either the HTTP::ProxyAutoConfig->new() or the new HTTP::ProxyAutoConfig() form, but don't use the HTTP::ProxyAutoConfig::new() form.

FindProxyForURL( url, host )

This takes the url, and the host (minus port) from the URL, and determines the action you should take to contact that host. It returns one of three strings:

  DIRECT           - connect directly
  PROXY host:port  - connect via the proxy
  SOCKS host:port  - connect via SOCKS

This result can be used to configure a net-access module like LWP.

FindProxy( url )

Same as the previous call, except you don't have to extract the host from the URL.

AUTHORS

  By Ryan Eatmon in May of 2001
  0.2 by Craig MacKenna, March 2010

COPYRIGHT AND LICENSE

  Copyright (C) 2001, Ryan Eatmon
  Copyright (C) 2010, Craig MacKenna

This module is free software; you may redistribute it and/or modify it under the same terms as Perl 5.10.1. For more details, see the full text of the licenses at http://www.perlfoundation.org/artistic_license_1_0 and http://www.gnu.org/licenses/gpl-2.0.html

This program is distributed in the hope that it will be useful, but it is provided 'as is' and without any express or implied warranties. For details, see the full text of the licenses at the above URLs.