#===============================================================================
# HTTP::ProxyCheck Version 1.4, Thu May 25 10:47:42 CEST 2006
#===============================================================================
# Copyright (c) 2004 - 2006 Thomas Weibel. All rights reserved.
#
# This library is free software; you can redistribute it and/or modify it
# under the same terms as Perl itself.
#
# More information: See "pod2text ProxyCheck.pm"
#===============================================================================

package HTTP::ProxyCheck;

use strict;
use vars qw($answer $error $VERSION);
use warnings;

use Validate::Net;
use IO::Socket;

BEGIN {
    $VERSION = 1.4;
    $answer  = '';
    $error   = '';

    # Autoflush = True
    $| = 1;
}

=head1 NAME

HTTP::ProxyCheck - a class to check the functionality of HTTP proxy servers.

=head1 SYNOPSIS

    use HTTP::ProxyCheck;
    
    my $proxy       = 'proxy:8080';
    my $url         = 'http://search.cpan.org/';
    my $proxy_check = new HTTP::ProxyCheck(
        proxy       => $proxy,
        url         => $url,
        answer_size => 'header',
        print_error => 0,
    ) 
    or die $HTTP::ProxyCheck::error;
    
    print "Trying to connect to '$proxy' and retrieve '$url'\n";
    
    if ( $proxy_check->check() ) {
        print "'$proxy' returns:\n\n", $proxy_check->get_answer(), "\n\n";
    }
    else {
        print "Error: ", $proxy_check->get_error(), "\n";
    }

=head1 DESCRIPTION

HTTP::ProxyCheck is a class to check HTTP proxy servers. It connects to given 
HTTP proxy servers and tries to retrieve a provided URL through them.

=head1 CONSTRUCTOR

=head2 new( [attribute => $value, ...] )

C<new()> is the HTTP::ProxyCheck object constructor.

If an error happens while constructing the object, use 
C<$HTTP::ProxyCheck::error> to get the error message.

All named attributes of C<new()> are optional.

B<Attributes>

=over 10

=item * proxy => $proxy

Specifies the address of the proxy server to check. This can also be done with 
C<set_proxy()>.

The proxy server address has to match the patter 'host:port'. Host and port are
tested whether they are valid. If you want to disable this test, you can set
C<< check_proxy => 0 >>. 

=item * check_proxy => 1|0

Set C<< check_proxy => 0 >> to disable the check whether the proxy server 
address is valid.

The default value of C<check_proxy> is C<1> which means, the proxy server 
address gets tested.

This attribute can also be set with C<set_check_proxy()>.

=item * url => $url

Specifies the URL to use for the proxy server check. This can also be done 
with C<set_url()>.