summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Win32/Internet.pm
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Win32/Internet.pm')
-rw-r--r--Master/tlpkg/tlperl/lib/Win32/Internet.pm3009
1 files changed, 0 insertions, 3009 deletions
diff --git a/Master/tlpkg/tlperl/lib/Win32/Internet.pm b/Master/tlpkg/tlperl/lib/Win32/Internet.pm
deleted file mode 100644
index f6dac3130af..00000000000
--- a/Master/tlpkg/tlperl/lib/Win32/Internet.pm
+++ /dev/null
@@ -1,3009 +0,0 @@
-#######################################################################
-#
-# Win32::Internet - Perl Module for Internet Extensions
-# ^^^^^^^^^^^^^^^
-# This module creates an object oriented interface to the Win32
-# Internet Functions (WININET.DLL).
-#
-# Version: 0.08 (14 Feb 1997)
-# Version: 0.081 (25 Sep 1999)
-# Version: 0.082 (04 Sep 2001)
-#
-#######################################################################
-
-# changes:
-# - fixed 2 bugs in Option(s) related subs
-# - works with build 30x also
-
-package Win32::Internet;
-
-require Exporter; # to export the constants to the main:: space
-require DynaLoader; # to dynuhlode the module.
-
-# use Win32::WinError; # for windows constants.
-
-@ISA= qw( Exporter DynaLoader );
-@EXPORT = qw(
- HTTP_ADDREQ_FLAG_ADD
- HTTP_ADDREQ_FLAG_REPLACE
- HTTP_QUERY_ALLOW
- HTTP_QUERY_CONTENT_DESCRIPTION
- HTTP_QUERY_CONTENT_ID
- HTTP_QUERY_CONTENT_LENGTH
- HTTP_QUERY_CONTENT_TRANSFER_ENCODING
- HTTP_QUERY_CONTENT_TYPE
- HTTP_QUERY_COST
- HTTP_QUERY_CUSTOM
- HTTP_QUERY_DATE
- HTTP_QUERY_DERIVED_FROM
- HTTP_QUERY_EXPIRES
- HTTP_QUERY_FLAG_REQUEST_HEADERS
- HTTP_QUERY_FLAG_SYSTEMTIME
- HTTP_QUERY_LANGUAGE
- HTTP_QUERY_LAST_MODIFIED
- HTTP_QUERY_MESSAGE_ID
- HTTP_QUERY_MIME_VERSION
- HTTP_QUERY_PRAGMA
- HTTP_QUERY_PUBLIC
- HTTP_QUERY_RAW_HEADERS
- HTTP_QUERY_RAW_HEADERS_CRLF
- HTTP_QUERY_REQUEST_METHOD
- HTTP_QUERY_SERVER
- HTTP_QUERY_STATUS_CODE
- HTTP_QUERY_STATUS_TEXT
- HTTP_QUERY_URI
- HTTP_QUERY_USER_AGENT
- HTTP_QUERY_VERSION
- HTTP_QUERY_WWW_LINK
- ICU_BROWSER_MODE
- ICU_DECODE
- ICU_ENCODE_SPACES_ONLY
- ICU_ESCAPE
- ICU_NO_ENCODE
- ICU_NO_META
- ICU_USERNAME
- INTERNET_FLAG_PASSIVE
- INTERNET_FLAG_ASYNC
- INTERNET_HYPERLINK
- INTERNET_FLAG_KEEP_CONNECTION
- INTERNET_FLAG_MAKE_PERSISTENT
- INTERNET_FLAG_NO_AUTH
- INTERNET_FLAG_NO_AUTO_REDIRECT
- INTERNET_FLAG_NO_CACHE_WRITE
- INTERNET_FLAG_NO_COOKIES
- INTERNET_FLAG_READ_PREFETCH
- INTERNET_FLAG_RELOAD
- INTERNET_FLAG_RESYNCHRONIZE
- INTERNET_FLAG_TRANSFER_ASCII
- INTERNET_FLAG_TRANSFER_BINARY
- INTERNET_INVALID_PORT_NUMBER
- INTERNET_INVALID_STATUS_CALLBACK
- INTERNET_OPEN_TYPE_DIRECT
- INTERNET_OPEN_TYPE_PROXY
- INTERNET_OPEN_TYPE_PROXY_PRECONFIG
- INTERNET_OPTION_CONNECT_BACKOFF
- INTERNET_OPTION_CONNECT_RETRIES
- INTERNET_OPTION_CONNECT_TIMEOUT
- INTERNET_OPTION_CONTROL_SEND_TIMEOUT
- INTERNET_OPTION_CONTROL_RECEIVE_TIMEOUT
- INTERNET_OPTION_DATA_SEND_TIMEOUT
- INTERNET_OPTION_DATA_RECEIVE_TIMEOUT
- INTERNET_OPTION_HANDLE_SIZE
- INTERNET_OPTION_LISTEN_TIMEOUT
- INTERNET_OPTION_PASSWORD
- INTERNET_OPTION_READ_BUFFER_SIZE
- INTERNET_OPTION_USER_AGENT
- INTERNET_OPTION_USERNAME
- INTERNET_OPTION_VERSION
- INTERNET_OPTION_WRITE_BUFFER_SIZE
- INTERNET_SERVICE_FTP
- INTERNET_SERVICE_GOPHER
- INTERNET_SERVICE_HTTP
- INTERNET_STATUS_CLOSING_CONNECTION
- INTERNET_STATUS_CONNECTED_TO_SERVER
- INTERNET_STATUS_CONNECTING_TO_SERVER
- INTERNET_STATUS_CONNECTION_CLOSED
- INTERNET_STATUS_HANDLE_CLOSING
- INTERNET_STATUS_HANDLE_CREATED
- INTERNET_STATUS_NAME_RESOLVED
- INTERNET_STATUS_RECEIVING_RESPONSE
- INTERNET_STATUS_REDIRECT
- INTERNET_STATUS_REQUEST_COMPLETE
- INTERNET_STATUS_REQUEST_SENT
- INTERNET_STATUS_RESOLVING_NAME
- INTERNET_STATUS_RESPONSE_RECEIVED
- INTERNET_STATUS_SENDING_REQUEST
-);
-
-
-#######################################################################
-# This AUTOLOAD is used to 'autoload' constants from the constant()
-# XS function. If a constant is not found then control is passed
-# to the AUTOLOAD in AutoLoader.
-#
-
-sub AUTOLOAD {
- my($constname);
- ($constname = $AUTOLOAD) =~ s/.*:://;
- #reset $! to zero to reset any current errors.
- local $! = 0;
- my $val = constant($constname, @_ ? $_[0] : 0);
- if ($! != 0) {
-
- # [dada] This results in an ugly Autoloader error
- #if ($! =~ /Invalid/) {
- # $AutoLoader::AUTOLOAD = $AUTOLOAD;
- # goto &AutoLoader::AUTOLOAD;
- #} else {
-
- # [dada] ... I prefer this one :)
-
- ($pack,$file,$line) = caller; undef $pack;
- die "Win32::Internet::$constname is not defined, used at $file line $line.";
-
- #}
- }
- eval "sub $AUTOLOAD { $val }";
- goto &$AUTOLOAD;
-}
-
-
-#######################################################################
-# STATIC OBJECT PROPERTIES
-#
-$VERSION = "0.082";
-
-%callback_code = ();
-%callback_info = ();
-
-
-#######################################################################
-# PUBLIC METHODS
-#
-
-#======== ### CLASS CONSTRUCTOR
-sub new {
-#========
- my($class, $useragent, $opentype, $proxy, $proxybypass, $flags) = @_;
- my $self = {};
-
- if(ref($useragent) and ref($useragent) eq "HASH") {
- $opentype = $useragent->{'opentype'};
- $proxy = $useragent->{'proxy'};
- $proxybypass = $useragent->{'proxybypass'};
- $flags = $useragent->{'flags'};
- my $myuseragent = $useragent->{'useragent'};
- undef $useragent;
- $useragent = $myuseragent;
- }
-
- $useragent = "Perl-Win32::Internet/".$VERSION unless defined($useragent);
- $opentype = constant("INTERNET_OPEN_TYPE_DIRECT",0) unless defined($opentype);
- $proxy = "" unless defined($proxy);
- $proxybypass = "" unless defined($proxybypass);
- $flags = 0 unless defined($flags);
-
-
- my $handle = InternetOpen($useragent, $opentype, $proxy, $proxybypass, $flags);
- if ($handle) {
- $self->{'connections'} = 0;
- $self->{'pasv'} = 0;
- $self->{'handle'} = $handle;
- $self->{'useragent'} = $useragent;
- $self->{'proxy'} = $proxy;
- $self->{'proxybypass'} = $proxybypass;
- $self->{'flags'} = $flags;
- $self->{'Type'} = "Internet";
-
- # [dada] I think it's better to call SetStatusCallback explicitly...
- #if($flags & constant("INTERNET_FLAG_ASYNC",0)) {
- # my $callbackresult=InternetSetStatusCallback($handle);
- # if($callbackresult==&constant("INTERNET_INVALID_STATUS_CALLBACK",0)) {
- # $self->{'Error'} = -2;
- # }
- #}
-
- bless $self;
- } else {
- $self->{'handle'} = undef;
- bless $self;
- }
- $self;
-}
-
-
-#============
-sub OpenURL {
-#============
- my($self,$new,$URL) = @_;
- return undef unless ref($self);
-
- my $newhandle=InternetOpenUrl($self->{'handle'},$URL,"",0,0,0);
- if(!$newhandle) {
- $self->{'Error'} = "Cannot open URL.";
- return undef;
- } else {
- $self->{'connections'}++;
- $_[1] = _new($newhandle);
- $_[1]->{'Type'} = "URL";
- $_[1]->{'URL'} = $URL;
- return $newhandle;
- }
-}
-
-
-#================
-sub TimeConvert {
-#================
- my($self, $sec, $min, $hour, $day, $mon, $year, $wday, $rfc) = @_;
- return undef unless ref($self);
-
- if(!defined($rfc)) {
- return InternetTimeToSystemTime($sec);
- } else {
- return InternetTimeFromSystemTime($sec, $min, $hour,
- $day, $mon, $year,
- $wday, $rfc);
- }
-}
-
-
-#=======================
-sub QueryDataAvailable {
-#=======================
- my($self) = @_;
- return undef unless ref($self);
-
- return InternetQueryDataAvailable($self->{'handle'});
-}
-
-
-#=============
-sub ReadFile {
-#=============
- my($self, $buffersize) = @_;
- return undef unless ref($self);
-
- my $howmuch = InternetQueryDataAvailable($self->{'handle'});
- $buffersize = $howmuch unless defined($buffersize);
- return InternetReadFile($self->{'handle'}, ($howmuch<$buffersize) ? $howmuch
- : $buffersize);
-}
-
-
-#===================
-sub ReadEntireFile {
-#===================
- my($handle) = @_;
- my $content = "";
- my $buffersize = 16000;
- my $howmuch = 0;
- my $buffer = "";
-
- $handle = $handle->{'handle'} if defined($handle) and ref($handle);
-
- $howmuch = InternetQueryDataAvailable($handle);
- # print "\nReadEntireFile: $howmuch bytes to read...\n";
-
- while($howmuch>0) {
- $buffer = InternetReadFile($handle, ($howmuch<$buffersize) ? $howmuch
- : $buffersize);
- # print "\nReadEntireFile: ", length($buffer), " bytes read...\n";
-
- if(!defined($buffer)) {
- return undef;
- } else {
- $content .= $buffer;
- }
- $howmuch = InternetQueryDataAvailable($handle);
- # print "\nReadEntireFile: still $howmuch bytes to read...\n";
-
- }
- return $content;
-}
-
-
-#=============
-sub FetchURL {
-#=============
- # (OpenURL+Read+Close)...
- my($self, $URL) = @_;
- return undef unless ref($self);
-
- my $newhandle = InternetOpenUrl($self->{'handle'}, $URL, "", 0, 0, 0);
- if(!$newhandle) {
- $self->{'Error'} = "Cannot open URL.";
- return undef;
- } else {
- my $content = ReadEntireFile($newhandle);
- InternetCloseHandle($newhandle);
- return $content;
- }
-}
-
-
-#================
-sub Connections {
-#================
- my($self) = @_;
- return undef unless ref($self);
-
- return $self->{'connections'} if $self->{'Type'} eq "Internet";
- return undef;
-}
-
-
-#================
-sub GetResponse {
-#================
- my($num, $text) = InternetGetLastResponseInfo();
- return $text;
-}
-
-#===========
-sub Option {
-#===========
- my($self, $option, $value) = @_;
- return undef unless ref($self);
-
- my $retval = 0;
-
- $option = constant("INTERNET_OPTION_USER_AGENT", 0) unless defined($option);
-
- if(!defined($value)) {
- $retval = InternetQueryOption($self->{'handle'}, $option);
- } else {
- $retval = InternetSetOption($self->{'handle'}, $option, $value);
- }
- return $retval;
-}
-
-
-#==============
-sub UserAgent {
-#==============
- my($self, $value) = @_;
- return undef unless ref($self);
-
- return Option($self, constant("INTERNET_OPTION_USER_AGENT", 0), $value);
-}
-
-
-#=============
-sub Username {
-#=============
- my($self, $value) = @_;
- return undef unless ref($self);
-
- if($self->{'Type'} ne "HTTP" and $self->{'Type'} ne "FTP") {
- $self->{'Error'} = "Username() only on FTP or HTTP sessions.";
- return undef;
- }
-
- return Option($self, constant("INTERNET_OPTION_USERNAME", 0), $value);
-}
-
-
-#=============
-sub Password {
-#=============
- my($self, $value)=@_;
- return undef unless ref($self);
-
- if($self->{'Type'} ne "HTTP" and $self->{'Type'} ne "FTP") {
- $self->{'Error'} = "Password() only on FTP or HTTP sessions.";
- return undef;
- }
-
- return Option($self, constant("INTERNET_OPTION_PASSWORD", 0), $value);
-}
-
-
-#===================
-sub ConnectTimeout {
-#===================
- my($self, $value) = @_;
- return undef unless ref($self);
-
- return Option($self, constant("INTERNET_OPTION_CONNECT_TIMEOUT", 0), $value);
-}
-
-
-#===================
-sub ConnectRetries {
-#===================
- my($self, $value) = @_;
- return undef unless ref($self);
-
- return Option($self, constant("INTERNET_OPTION_CONNECT_RETRIES", 0), $value);
-}
-
-
-#===================
-sub ConnectBackoff {
-#===================
- my($self,$value)=@_;
- return undef unless ref($self);
-
- return Option($self, constant("INTERNET_OPTION_CONNECT_BACKOFF", 0), $value);
-}
-
-
-#====================
-sub DataSendTimeout {
-#====================
- my($self,$value) = @_;
- return undef unless ref($self);
-
- return Option($self, constant("INTERNET_OPTION_DATA_SEND_TIMEOUT", 0), $value);
-}
-
-
-#=======================
-sub DataReceiveTimeout {
-#=======================
- my($self, $value) = @_;
- return undef unless ref($self);
-
- return Option($self, constant("INTERNET_OPTION_DATA_RECEIVE_TIMEOUT", 0), $value);
-}
-
-
-#==========================
-sub ControlReceiveTimeout {
-#==========================
- my($self, $value) = @_;
- return undef unless ref($self);
-
- return Option($self, constant("INTERNET_OPTION_CONTROL_RECEIVE_TIMEOUT", 0), $value);
-}
-
-
-#=======================
-sub ControlSendTimeout {
-#=======================
- my($self, $value) = @_;
- return undef unless ref($self);
-
- return Option($self, constant("INTERNET_OPTION_CONTROL_SEND_TIMEOUT", 0), $value);
-}
-
-
-#================
-sub QueryOption {
-#================
- my($self, $option) = @_;
- return undef unless ref($self);
-
- return InternetQueryOption($self->{'handle'}, $option);
-}
-
-
-#==============
-sub SetOption {
-#==============
- my($self, $option, $value) = @_;
- return undef unless ref($self);
-
- return InternetSetOption($self->{'handle'}, $option, $value);
-}
-
-
-#=============
-sub CrackURL {
-#=============
- my($self, $URL, $flags) = @_;
- return undef unless ref($self);
-
- $flags = constant("ICU_ESCAPE", 0) unless defined($flags);
-
- my @newurl = InternetCrackUrl($URL, $flags);
-
- if(!defined($newurl[0])) {
- $self->{'Error'} = "Cannot crack URL.";
- return undef;
- } else {
- return @newurl;
- }
-}
-
-
-#==============
-sub CreateURL {
-#==============
- my($self, $scheme, $hostname, $port,
- $username, $password,
- $path, $extrainfo, $flags) = @_;
- return undef unless ref($self);
-
- if(ref($scheme) and ref($scheme) eq "HASH") {
- $flags = $hostname;
- $hostname = $scheme->{'hostname'};
- $port = $scheme->{'port'};
- $username = $scheme->{'username'};
- $password = $scheme->{'password'};
- $path = $scheme->{'path'};
- $extrainfo = $scheme->{'extrainfo'};
- my $myscheme = $scheme->{'scheme'};
- undef $scheme;
- $scheme = $myscheme;
- }
-
- $hostname = "" unless defined($hostname);
- $port = 0 unless defined($port);
- $username = "" unless defined($username);
- $password = "" unless defined($password);
- $path = "" unless defined($path);
- $extrainfo = "" unless defined($extrainfo);
- $flags = constant("ICU_ESCAPE", 0) unless defined($flags);
-
- my $newurl = InternetCreateUrl($scheme, $hostname, $port,
- $username, $password,
- $path, $extrainfo, $flags);
- if(!defined($newurl)) {
- $self->{'Error'} = "Cannot create URL.";
- return undef;
- } else {
- return $newurl;
- }
-}
-
-
-#====================
-sub CanonicalizeURL {
-#====================
- my($self, $URL, $flags) = @_;
- return undef unless ref($self);
-
- my $newurl = InternetCanonicalizeUrl($URL, $flags);
- if(!defined($newurl)) {
- $self->{'Error'} = "Cannot canonicalize URL.";
- return undef;
- } else {
- return $newurl;
- }
-}
-
-
-#===============
-sub CombineURL {
-#===============
- my($self, $baseURL, $relativeURL, $flags) = @_;
- return undef unless ref($self);
-
- my $newurl = InternetCombineUrl($baseURL, $relativeURL, $flags);
- if(!defined($newurl)) {
- $self->{'Error'} = "Cannot combine URL(s).";
- return undef;
- } else {
- return $newurl;
- }
-}
-
-
-#======================
-sub SetStatusCallback {
-#======================
- my($self) = @_;
- return undef unless ref($self);
-
- my $callback = InternetSetStatusCallback($self->{'handle'});
- print "callback=$callback, constant=",constant("INTERNET_INVALID_STATUS_CALLBACK", 0), "\n";
- if($callback == constant("INTERNET_INVALID_STATUS_CALLBACK", 0)) {
- return undef;
- } else {
- return $callback;
- }
-}
-
-
-#======================
-sub GetStatusCallback {
-#======================
- my($self, $context) = @_;
- $context = $self if not defined $context;
- return($callback_code{$context}, $callback_info{$context});
-}
-
-
-#==========
-sub Error {
-#==========
- my($self) = @_;
- return undef unless ref($self);
-
- require Win32 unless defined &Win32::GetLastError;
- my $errtext = "";
- my $tmp = "";
- my $errnum = Win32::GetLastError();
-
- if($errnum < 12000) {
- $errtext = Win32::FormatMessage($errnum);
- $errtext =~ s/[\r\n]//g;
- } elsif($errnum == 12003) {
- ($tmp, $errtext) = InternetGetLastResponseInfo();
- chomp $errtext;
- 1 while($errtext =~ s/(.*)\n//); # the last line should be significative...
- # otherwise call GetResponse() to get it whole
- } elsif($errnum >= 12000) {
- $errtext = FormatMessage($errnum);
- $errtext =~ s/[\r\n]//g;
- } else {
- $errtext="Error";
- }
- if($errnum == 0 and defined($self->{'Error'})) {
- if($self->{'Error'} == -2) {
- $errnum = -2;
- $errtext = "Asynchronous operations not available.";
- } else {
- $errnum = -1;
- $errtext = $self->{'Error'};
- }
- }
- return (wantarray)? ($errnum, $errtext) : "\[".$errnum."\] ".$errtext;
-}
-
-
-#============
-sub Version {
-#============
- my $dll = InternetDllVersion();
- $dll =~ s/\0//g;
- return (wantarray)? ($Win32::Internet::VERSION, $dll)
- : $Win32::Internet::VERSION."/".$dll;
-}
-
-
-#==========
-sub Close {
-#==========
- my($self, $handle) = @_;
- if(!defined($handle)) {
- return undef unless ref($self);
- $handle = $self->{'handle'};
- }
- InternetCloseHandle($handle);
-}
-
-
-
-#######################################################################
-# FTP CLASS METHODS
-#
-
-#======== ### FTP CONSTRUCTOR
-sub FTP {
-#========
- my($self, $new, $server, $username, $password, $port, $pasv, $context) = @_;
- return undef unless ref($self);
-
- if(ref($server) and ref($server) eq "HASH") {
- $port = $server->{'port'};
- $username = $server->{'username'};
- $password = $password->{'host'};
- my $myserver = $server->{'server'};
- $pasv = $server->{'pasv'};
- $context = $server->{'context'};
- undef $server;
- $server = $myserver;
- }
-
- $server = "" unless defined($server);
- $username = "anonymous" unless defined($username);
- $password = "" unless defined($password);
- $port = 21 unless defined($port);
- $context = 0 unless defined($context);
-
- $pasv = $self->{'pasv'} unless defined $pasv;
- $pasv = $pasv ? constant("INTERNET_FLAG_PASSIVE",0) : 0;
-
- my $newhandle = InternetConnect($self->{'handle'}, $server, $port,
- $username, $password,
- constant("INTERNET_SERVICE_FTP", 0),
- $pasv, $context);
- if($newhandle) {
- $self->{'connections'}++;
- $_[1] = _new($newhandle);
- $_[1]->{'Type'} = "FTP";
- $_[1]->{'Mode'} = "bin";
- $_[1]->{'pasv'} = $pasv;
- $_[1]->{'username'} = $username;
- $_[1]->{'password'} = $password;
- $_[1]->{'server'} = $server;
- return $newhandle;
- } else {
- return undef;
- }
-}
-
-#========
-sub Pwd {
-#========
- my($self) = @_;
- return undef unless ref($self);
-
- if($self->{'Type'} ne "FTP" or !defined($self->{'handle'})) {
- $self->{'Error'} = "Pwd() only on FTP sessions.";
- return undef;
- }
-
- return FtpGetCurrentDirectory($self->{'handle'});
-}
-
-
-#=======
-sub Cd {
-#=======
- my($self, $path) = @_;
- return undef unless ref($self);
-
- if($self->{'Type'} ne "FTP" || !defined($self->{'handle'})) {
- $self->{'Error'} = "Cd() only on FTP sessions.";
- return undef;
- }
-
- my $retval = FtpSetCurrentDirectory($self->{'handle'}, $path);
- if(!defined($retval)) {
- return undef;
- } else {
- return $path;
- }
-}
-#====================
-sub Cwd { Cd(@_); }
-sub Chdir { Cd(@_); }
-#====================
-
-
-#==========
-sub Mkdir {
-#==========
- my($self, $path) = @_;
- return undef unless ref($self);
-
- if($self->{'Type'} ne "FTP" or !defined($self->{'handle'})) {
- $self->{'Error'} = "Mkdir() only on FTP sessions.";
- return undef;
- }
-
- my $retval = FtpCreateDirectory($self->{'handle'}, $path);
- $self->{'Error'} = "Can't create directory." unless defined($retval);
- return $retval;
-}
-#====================
-sub Md { Mkdir(@_); }
-#====================
-
-
-#=========
-sub Mode {
-#=========
- my($self, $value) = @_;
- return undef unless ref($self);
-
- if($self->{'Type'} ne "FTP" or !defined($self->{'handle'})) {
- $self->{'Error'} = "Mode() only on FTP sessions.";
- return undef;
- }
-
- if(!defined($value)) {
- return $self->{'Mode'};
- } else {
- my $modesub = ($value =~ /^a/i) ? "Ascii" : "Binary";
- $self->$modesub($_[0]);
- }
- return $self->{'Mode'};
-}
-
-
-#==========
-sub Rmdir {
-#==========
- my($self, $path) = @_;
- return undef unless ref($self);
-
- if($self->{'Type'} ne "FTP" or !defined($self->{'handle'})) {
- $self->{'Error'} = "Rmdir() only on FTP sessions.";
- return undef;
- }
- my $retval = FtpRemoveDirectory($self->{'handle'}, $path);
- $self->{'Error'} = "Can't remove directory." unless defined($retval);
- return $retval;
-}
-#====================
-sub Rd { Rmdir(@_); }
-#====================
-
-
-#=========
-sub Pasv {
-#=========
- my($self, $value) = @_;
- return undef unless ref($self);
-
- if(defined($value) and $self->{'Type'} eq "Internet") {
- if($value == 0) {
- $self->{'pasv'} = 0;
- } else {
- $self->{'pasv'} = 1;
- }
- }
- return $self->{'pasv'};
-}
-
-#=========
-sub List {
-#=========
- my($self, $pattern, $retmode) = @_;
- return undef unless ref($self);
-
- my $retval = "";
- my $size = "";
- my $attr = "";
- my $ctime = "";
- my $atime = "";
- my $mtime = "";
- my $csec = 0; my $cmin = 0; my $chou = 0; my $cday = 0; my $cmon = 0; my $cyea = 0;
- my $asec = 0; my $amin = 0; my $ahou = 0; my $aday = 0; my $amon = 0; my $ayea = 0;
- my $msec = 0; my $mmin = 0; my $mhou = 0; my $mday = 0; my $mmon = 0; my $myea = 0;
- my $newhandle = 0;
- my $nextfile = 1;
- my @results = ();
- my ($filename, $altname, $file);
-
- if($self->{'Type'} ne "FTP") {
- $self->{'Error'} = "List() only on FTP sessions.";
- return undef;
- }
-
- $pattern = "" unless defined($pattern);
- $retmode = 1 unless defined($retmode);
-
- if($retmode == 2) {
-
- ( $newhandle,$filename, $altname, $size, $attr,
- $csec, $cmin, $chou, $cday, $cmon, $cyea,
- $asec, $amin, $ahou, $aday, $amon, $ayea,
- $msec, $mmin, $mhou, $mday, $mmon, $myea
- ) = FtpFindFirstFile($self->{'handle'}, $pattern, 0, 0);
-
- if(!$newhandle) {
- $self->{'Error'} = "Can't read FTP directory.";
- return undef;
- } else {
-
- while($nextfile) {
- $ctime = join(",", ($csec, $cmin, $chou, $cday, $cmon, $cyea));
- $atime = join(",", ($asec, $amin, $ahou, $aday, $amon, $ayea));
- $mtime = join(",", ($msec, $mmin, $mhou, $mday, $mmon, $myea));
- push(@results, $filename, $altname, $size, $attr, $ctime, $atime, $mtime);
-
- ( $nextfile, $filename, $altname, $size, $attr,
- $csec, $cmin, $chou, $cday, $cmon, $cyea,
- $asec, $amin, $ahou, $aday, $amon, $ayea,
- $msec, $mmin, $mhou, $mday, $mmon, $myea
- ) = InternetFindNextFile($newhandle);
-
- }
- InternetCloseHandle($newhandle);
- return @results;
-
- }
-
- } elsif($retmode == 3) {
-
- ( $newhandle,$filename, $altname, $size, $attr,
- $csec, $cmin, $chou, $cday, $cmon, $cyea,
- $asec, $amin, $ahou, $aday, $amon, $ayea,
- $msec, $mmin, $mhou, $mday, $mmon, $myea
- ) = FtpFindFirstFile($self->{'handle'}, $pattern, 0, 0);
-
- if(!$newhandle) {
- $self->{'Error'} = "Can't read FTP directory.";
- return undef;
-
- } else {
-
- while($nextfile) {
- $ctime = join(",", ($csec, $cmin, $chou, $cday, $cmon, $cyea));
- $atime = join(",", ($asec, $amin, $ahou, $aday, $amon, $ayea));
- $mtime = join(",", ($msec, $mmin, $mhou, $mday, $mmon, $myea));
- $file = { "name" => $filename,
- "altname" => $altname,
- "size" => $size,
- "attr" => $attr,
- "ctime" => $ctime,
- "atime" => $atime,
- "mtime" => $mtime,
- };
- push(@results, $file);
-
- ( $nextfile, $filename, $altname, $size, $attr,
- $csec, $cmin, $chou, $cday, $cmon, $cyea,
- $asec, $amin, $ahou, $aday, $amon, $ayea,
- $msec, $mmin, $mhou, $mday, $mmon, $myea
- ) = InternetFindNextFile($newhandle);
-
- }
- InternetCloseHandle($newhandle);
- return @results;
- }
-
- } else {
-
- ($newhandle, $filename) = FtpFindFirstFile($self->{'handle'}, $pattern, 0, 0);
-
- if(!$newhandle) {
- $self->{'Error'} = "Can't read FTP directory.";
- return undef;
-
- } else {
-
- while($nextfile) {
- push(@results, $filename);
-
- ($nextfile, $filename) = InternetFindNextFile($newhandle);
- # print "List.no more files\n" if !$nextfile;
-
- }
- InternetCloseHandle($newhandle);
- return @results;
- }
- }
-}
-#====================
-sub Ls { List(@_); }
-sub Dir { List(@_); }
-#====================
-
-
-#=================
-sub FileAttrInfo {
-#=================
- my($self,$attr) = @_;
- my @attrinfo = ();
- push(@attrinfo, "READONLY") if $attr & 1;
- push(@attrinfo, "HIDDEN") if $attr & 2;
- push(@attrinfo, "SYSTEM") if $attr & 4;
- push(@attrinfo, "DIRECTORY") if $attr & 16;
- push(@attrinfo, "ARCHIVE") if $attr & 32;
- push(@attrinfo, "NORMAL") if $attr & 128;
- push(@attrinfo, "TEMPORARY") if $attr & 256;
- push(@attrinfo, "COMPRESSED") if $attr & 2048;
- return (wantarray)? @attrinfo : join(" ", @attrinfo);
-}
-
-
-#===========
-sub Binary {
-#===========
- my($self) = @_;
- return undef unless ref($self);
-
- if($self->{'Type'} ne "FTP") {
- $self->{'Error'} = "Binary() only on FTP sessions.";
- return undef;
- }
- $self->{'Mode'} = "bin";
- return undef;
-}
-#======================
-sub Bin { Binary(@_); }
-#======================
-
-
-#==========
-sub Ascii {
-#==========
- my($self) = @_;
- return undef unless ref($self);
-
- if($self->{'Type'} ne "FTP") {
- $self->{'Error'} = "Ascii() only on FTP sessions.";
- return undef;
- }
- $self->{'Mode'} = "asc";
- return undef;
-}
-#=====================
-sub Asc { Ascii(@_); }
-#=====================
-
-
-#========
-sub Get {
-#========
- my($self, $remote, $local, $overwrite, $flags, $context) = @_;
- return undef unless ref($self);
-
- if($self->{'Type'} ne "FTP") {
- $self->{'Error'} = "Get() only on FTP sessions.";
- return undef;
- }
- my $mode = ($self->{'Mode'} eq "asc" ? 1 : 2);
-
- $remote = "" unless defined($remote);
- $local = $remote unless defined($local);
- $overwrite = 0 unless defined($overwrite);
- $flags = 0 unless defined($flags);
- $context = 0 unless defined($context);
-
- my $retval = FtpGetFile($self->{'handle'},
- $remote,
- $local,
- $overwrite,
- $flags,
- $mode,
- $context);
- $self->{'Error'} = "Can't get file." unless defined($retval);
- return $retval;
-}
-
-
-#===========
-sub Rename {
-#===========
- my($self, $oldname, $newname) = @_;
- return undef unless ref($self);
-
- if($self->{'Type'} ne "FTP") {
- $self->{'Error'} = "Rename() only on FTP sessions.";
- return undef;
- }
-
- my $retval = FtpRenameFile($self->{'handle'}, $oldname, $newname);
- $self->{'Error'} = "Can't rename file." unless defined($retval);
- return $retval;
-}
-#======================
-sub Ren { Rename(@_); }
-#======================
-
-
-#===========
-sub Delete {
-#===========
- my($self, $filename) = @_;
- return undef unless ref($self);
-
- if($self->{'Type'} ne "FTP") {
- $self->{'Error'} = "Delete() only on FTP sessions.";
- return undef;
- }
- my $retval = FtpDeleteFile($self->{'handle'}, $filename);
- $self->{'Error'} = "Can't delete file." unless defined($retval);
- return $retval;
-}
-#======================
-sub Del { Delete(@_); }
-#======================
-
-
-#========
-sub Put {
-#========
- my($self, $local, $remote, $context) = @_;
- return undef unless ref($self);
-
- if($self->{'Type'} ne "FTP") {
- $self->{'Error'} = "Put() only on FTP sessions.";
- return undef;
- }
- my $mode = ($self->{'Mode'} eq "asc" ? 1 : 2);
-
- $context = 0 unless defined($context);
-
- my $retval = FtpPutFile($self->{'handle'}, $local, $remote, $mode, $context);
- $self->{'Error'} = "Can't put file." unless defined($retval);
- return $retval;
-}
-
-
-#######################################################################
-# HTTP CLASS METHODS
-#
-
-#========= ### HTTP CONSTRUCTOR
-sub HTTP {
-#=========
- my($self, $new, $server, $username, $password, $port, $flags, $context) = @_;
- return undef unless ref($self);
-
- if(ref($server) and ref($server) eq "HASH") {
- my $myserver = $server->{'server'};
- $username = $server->{'username'};
- $password = $password->{'host'};
- $port = $server->{'port'};
- $flags = $server->{'flags'};
- $context = $server->{'context'};
- undef $server;
- $server = $myserver;
- }
-
- $server = "" unless defined($server);
- $username = "anonymous" unless defined($username);
- $password = "" unless defined($password);
- $port = 80 unless defined($port);
- $flags = 0 unless defined($flags);
- $context = 0 unless defined($context);
-
- my $newhandle = InternetConnect($self->{'handle'}, $server, $port,
- $username, $password,
- constant("INTERNET_SERVICE_HTTP", 0),
- $flags, $context);
- if($newhandle) {
- $self->{'connections'}++;
- $_[1] = _new($newhandle);
- $_[1]->{'Type'} = "HTTP";
- $_[1]->{'username'} = $username;
- $_[1]->{'password'} = $password;
- $_[1]->{'server'} = $server;
- $_[1]->{'accept'} = "text/*\0image/gif\0image/jpeg\0\0";
- return $newhandle;
- } else {
- return undef;
- }
-}
-
-
-#================
-sub OpenRequest {
-#================
- # alternatively to Request:
- # it creates a new HTTP_Request object
- # you can act upon it with AddHeader, SendRequest, ReadFile, QueryInfo, Close, ...
-
- my($self, $new, $path, $method, $version, $referer, $accept, $flags, $context) = @_;
- return undef unless ref($self);
-
- if($self->{'Type'} ne "HTTP") {
- $self->{'Error'} = "OpenRequest() only on HTTP sessions.";
- return undef;
- }
-
- if(ref($path) and ref($path) eq "HASH") {
- $method = $path->{'method'};
- $version = $path->{'version'};
- $referer = $path->{'referer'};
- $accept = $path->{'accept'};
- $flags = $path->{'flags'};
- $context = $path->{'context'};
- my $mypath = $path->{'path'};
- undef $path;
- $path = $mypath;
- }
-
- $method = "GET" unless defined($method);
- $path = "/" unless defined($path);
- $version = "HTTP/1.0" unless defined($version);
- $referer = "" unless defined($referer);
- $accept = $self->{'accept'} unless defined($accept);
- $flags = 0 unless defined($flags);
- $context = 0 unless defined($context);
-
- $path = "/".$path if substr($path,0,1) ne "/";
- # accept string list needs to be terminated by double-NULL
- $accept .= "\0\0" unless $accept =~ /\0\0\z/;
-
- my $newhandle = HttpOpenRequest($self->{'handle'},
- $method,
- $path,
- $version,
- $referer,
- $accept,
- $flags,
- $context);
- if($newhandle) {
- $_[1] = _new($newhandle);
- $_[1]->{'Type'} = "HTTP_Request";
- $_[1]->{'method'} = $method;
- $_[1]->{'request'} = $path;
- $_[1]->{'accept'} = $accept;
- return $newhandle;
- } else {
- return undef;
- }
-}
-
-#================
-sub SendRequest {
-#================
- my($self, $postdata) = @_;
- return undef unless ref($self);
-
- if($self->{'Type'} ne "HTTP_Request") {
- $self->{'Error'} = "SendRequest() only on HTTP requests.";
- return undef;
- }
-
- $postdata = "" unless defined($postdata);
-
- return HttpSendRequest($self->{'handle'}, "", $postdata);
-}
-
-
-#==============
-sub AddHeader {
-#==============
- my($self, $header, $flags) = @_;
- return undef unless ref($self);
-
- if($self->{'Type'} ne "HTTP_Request") {
- $self->{'Error'} = "AddHeader() only on HTTP requests.";
- return undef;
- }
-
- $flags = constant("HTTP_ADDREQ_FLAG_ADD", 0) if (!defined($flags) or $flags == 0);
-
- return HttpAddRequestHeaders($self->{'handle'}, $header, $flags);
-}
-
-
-#==============
-sub QueryInfo {
-#==============
- my($self, $header, $flags) = @_;
- return undef unless ref($self);
-
- if($self->{'Type'} ne "HTTP_Request") {
- $self->{'Error'}="QueryInfo() only on HTTP requests.";
- return undef;
- }
-
- $flags = constant("HTTP_QUERY_CUSTOM", 0) if (!defined($flags) and defined($header));
- my @queryresult = HttpQueryInfo($self->{'handle'}, $flags, $header);
- return (wantarray)? @queryresult : join(" ", @queryresult);
-}
-
-
-#============
-sub Request {
-#============
- # HttpOpenRequest+HttpAddHeaders+HttpSendRequest+InternetReadFile+HttpQueryInfo
- my($self, $path, $method, $version, $referer, $accept, $flags, $postdata) = @_;
- return undef unless ref($self);
-
- if($self->{'Type'} ne "HTTP") {
- $self->{'Error'} = "Request() only on HTTP sessions.";
- return undef;
- }
-
- if(ref($path) and ref($path) eq "HASH") {
- $method = $path->{'method'};
- $version = $path->{'version'};
- $referer = $path->{'referer'};
- $accept = $path->{'accept'};
- $flags = $path->{'flags'};
- $postdata = $path->{'postdata'};
- my $mypath = $path->{'path'};
- undef $path;
- $path = $mypath;
- }
-
- my $content = "";
- my $result = "";
- my @queryresult = ();
- my $statuscode = "";
- my $headers = "";
-
- $path = "/" unless defined($path);
- $method = "GET" unless defined($method);
- $version = "HTTP/1.0" unless defined($version);
- $referer = "" unless defined($referer);
- $accept = $self->{'accept'} unless defined($accept);
- $flags = 0 unless defined($flags);
- $postdata = "" unless defined($postdata);
-
- $path = "/".$path if substr($path,0,1) ne "/";
- # accept string list needs to be terminated by double-NULL
- $accept .= "\0\0" unless $accept =~ /\0\0\z/;
-
- my $newhandle = HttpOpenRequest($self->{'handle'},
- $method,
- $path,
- $version,
- $referer,
- $accept,
- $flags,
- 0);
-
- if($newhandle) {
-
- $result = HttpSendRequest($newhandle, "", $postdata);
-
- if(defined($result)) {
- $statuscode = HttpQueryInfo($newhandle,
- constant("HTTP_QUERY_STATUS_CODE", 0), "");
- $headers = HttpQueryInfo($newhandle,
- constant("HTTP_QUERY_RAW_HEADERS_CRLF", 0), "");
- $content = ReadEntireFile($newhandle);
-
- InternetCloseHandle($newhandle);
-
- return($statuscode, $headers, $content);
- } else {
- return undef;
- }
- } else {
- return undef;
- }
-}
-
-
-#######################################################################
-# END OF THE PUBLIC METHODS
-#
-
-
-#========= ### SUB-CLASSES CONSTRUCTOR
-sub _new {
-#=========
- my $self = {};
- if ($_[0]) {
- $self->{'handle'} = $_[0];
- bless $self;
- } else {
- undef($self);
- }
- $self;
-}
-
-
-#============ ### CLASS DESTRUCTOR
-sub DESTROY {
-#============
- my($self) = @_;
- # print "Closing handle $self->{'handle'}...\n";
- InternetCloseHandle($self->{'handle'});
- # [dada] rest in peace
-}
-
-
-#=============
-sub callback {
-#=============
- my($name, $status, $info) = @_;
- $callback_code{$name} = $status;
- $callback_info{$name} = $info;
-}
-
-#######################################################################
-# dynamically load in the Internet.pll module.
-#
-
-bootstrap Win32::Internet;
-
-# Preloaded methods go here.
-
-#Currently Autoloading is not implemented in Perl for win32
-# Autoload methods go after __END__, and are processed by the autosplit program.
-
-1;
-__END__
-
-=head1 NAME
-
-Win32::Internet - Access to WININET.DLL functions
-
-=head1 INTRODUCTION
-
-This extension to Perl implements the Win32 Internet APIs (found in
-F<WININET.DLL>). They give a complete support for HTTP, FTP and GOPHER
-connections.
-
-See the L<"Version History"> and the L<"Functions Table"> for a list
-of the currently supported features. You should also get a copy of the
-L<"Microsoft Win32 Internet Functions"> documentation.
-
-=head1 REFERENCE
-
-To use this module, first add the following line at the beginning of
-your script:
-
- use Win32::Internet;
-
-Then you have to open an Internet connection with this command:
-
- $Connection = new Win32::Internet();
-
-This is required to use any of the function of this module. It will
-create an Internet object in Perl on which you can act upon with the
-L<"General Internet Functions"> explained later.
-
-The objects available are:
-
-=over
-
-=item *
-
-Internet connections (the main object, see C<new>)
-
-=item *
-
-URLs (see C<OpenURL>)
-
-=item *
-
-FTP sessions (see C<FTP>)
-
-=item *
-
-HTTP sessions (see C<HTTP>)
-
-=item *
-
-HTTP requests (see C<OpenRequest>)
-
-=back
-
-As in the good Perl tradition, there are in this extension different
-ways to do the same thing; there are, in fact, different levels of
-implementation of the Win32 Internet Functions. Some routines use
-several Win32 API functions to perform a complex task in a single
-call; they are simpler to use, but of course less powerful.
-
-There are then other functions that implement nothing more and nothing
-less than the corresponding API function, so you can use all of their
-power, but with some additional programming steps.
-
-To make an example, there is a function called C<FetchURL> that you
-can use to fetch the content of any HTTP, FTP or GOPHER URL with this
-simple commands:
-
- $INET = new Win32::Internet();
- $file = $INET->FetchURL("http://www.yahoo.com");
-
-You can have the same result (and this is actually what is done by
-C<FetchURL>) this way:
-
- $INET = new Win32::Internet();
- $URL = $INET->OpenURL("http://www.yahoo.com");
- $file = $URL->ReadFile();
- $URL->Close();
-
-Or, you can open a complete HTTP session:
-
- $INET = new Win32::Internet();
- $HTTP = $INET->HTTP("www.yahoo.com", "anonymous", "dada@divinf.it");
- ($statuscode, $headers, $file) = $HTTP->Request("/");
- $HTTP->Close();
-
-Finally, you can choose to manage even the HTTP request:
-
- $INET = new Win32::Internet();
- $HTTP = $INET->HTTP("www.yahoo.com", "anonymous", "dada@divinf.it");
- $HTTP->OpenRequest($REQ, "/");
- $REQ->AddHeader("If-Modified-Since: Saturday, 16-Nov-96 15:58:50 GMT");
- $REQ->SendRequest();
- $statuscode = $REQ->QueryInfo("",HTTP_QUERY_STATUS_CODE);
- $lastmodified = $REQ->QueryInfo("Last-Modified");
- $file = $REQ->ReadEntireFile();
- $REQ->Close();
- $HTTP->Close();
-
-To open and control a complete FTP session, type:
-
- $Connection->FTP($Session, "ftp://ftp.activeware.com", "anonymous", "dada\@divinf.it");
-
-This will create an FTP object in Perl to which you can apply the L<"FTP
-functions"> provided by the package:
-
- $Session->Cd("/ntperl/perl5.001m/CurrentBuild");
- $Session->Ascii();
- $Session->Get("110-i86.zip");
- $Session->Close();
-
-For a more complete example, see the TEST.PL file that comes with the
-package.
-
-=head2 General Internet Functions
-
-B<General Note>
-
-All methods assume that you have the line:
-
- use Win32::Internet;
-
-somewhere before the method calls, and that you have an Internet
-object called $INET which was created using this call:
-
- $INET = new Win32::Internet();
-
-See C<new> for more information.
-
-B<Methods>
-
-=over
-
-=item CanonicalizeURL URL, [flags]
-
-Converts a URL to a canonical format, which includes converting unsafe
-characters to escape sequences. Returns the canonicalized URL or
-C<undef> on errors. For the possible values of I<flags>, refer to the
-L<"Microsoft Win32 Internet Functions"> document. See also
-C<CombineURL> and C<OpenURL>.
-
-Example:
-
- $cURL = $INET->CanonicalizeURL($URL);
- $URL = $INET->CanonicalizeURL($cURL, ICU_DECODE);
-
-=item Close
-
-=item Close object
-
-Closes an Internet connection. This can be applied to any
-Win32::Internet object (Internet connections, URLs, FTP sessions,
-etc.). Note that it is not "strictly" required to close the
-connections you create, since the Win32::Internet objects are
-automatically closed when the program ends (or when you elsehow
-destroy such an object).
-
-Example:
-
- $INET->Close();
- $FTP->Close();
- $INET->Close($FTP); # same as above...
-
-=item CombineURL baseURL, relativeURL, [flags]
-
-Combines a base and relative URL into a single URL. Returns the
-(canonicalized) combined URL or C<undef> on errors. For the possible
-values of I<flags>, refer to the L<"Microsoft Win32 Internet
-Functions"> document. See also C<CombineURL> and C<OpenURL>.
-
-Example:
-
- $URL = $INET->CombineURL("http://www.divinf.it/dada/perl/internet", "..");
-
-=item ConnectBackoff [value]
-
-Reads or sets the delay value, in milliseconds, to wait between
-connection retries. If no I<value> parameter is specified, the
-current value is returned; otherwise, the delay between retries is set
-to I<value>. See also C<ConnectTimeout>, C<ConnectRetries>,
-C<QueryOption> and C<SetOption>.
-
-Example:
-
- $HTTP->ConnectBackoff(2000);
- $backoff = $HTTP->ConnectBackoff();
-
-=item ConnectRetries [value]
-
-Reads or sets the number of times a connection is retried before
-considering it failed. If no I<value> parameter is specified, the
-current value is returned; otherwise, the number of retries is set to
-I<value>. The default value for C<ConnectRetries> is 5. See also
-C<ConnectBackoff>, C<ConnectTimeout>, C<QueryOption> and C<SetOption>.
-
-Example:
-
- $HTTP->ConnectRetries(20);
- $retries = $HTTP->ConnectRetries();
-
-=item ConnectTimeout [value]
-
-Reads or sets the timeout value (in milliseconds) before a connection
-is considered failed. If no I<value> parameter is specified, the
-current value is returned; otherwise, the timeout is set to I<value>.
-The default value for C<ConnectTimeout> is infinite. See also
-C<ConnectBackoff>, C<ConnectRetries>, C<QueryOption> and C<SetOption>.
-
-Example:
-
- $HTTP->ConnectTimeout(10000);
- $timeout = $HTTP->ConnectTimeout();
-
-=item ControlReceiveTimeout [value]
-
-Reads or sets the timeout value (in milliseconds) to use for non-data
-(control) receive requests before they are canceled. Currently, this
-value has meaning only for C<FTP> sessions. If no I<value> parameter
-is specified, the current value is returned; otherwise, the timeout is
-set to I<value>. The default value for C<ControlReceiveTimeout> is
-infinite. See also C<ControlSendTimeout>, C<QueryOption> and
-C<SetOption>.
-
-Example:
-
- $HTTP->ControlReceiveTimeout(10000);
- $timeout = $HTTP->ControlReceiveTimeout();
-
-=item ControlSendTimeout [value]
-
-Reads or sets the timeout value (in milliseconds) to use for non-data
-(control) send requests before they are canceled. Currently, this
-value has meaning only for C<FTP> sessions. If no I<value> parameter
-is specified, the current value is returned; otherwise, the timeout is
-set to I<value>. The default value for C<ControlSendTimeout> is
-infinite. See also C<ControlReceiveTimeout>, C<QueryOption> and
-C<SetOption>.
-
-Example:
-
- $HTTP->ControlSendTimeout(10000);
- $timeout = $HTTP->ControlSendTimeout();
-
-=item CrackURL URL, [flags]
-
-Splits an URL into its component parts and returns them in an array.
-Returns C<undef> on errors, otherwise the array will contain the
-following values: I<scheme, host, port, username, password, path,
-extrainfo>.
-
-For example, the URL "http://www.divinf.it/index.html#top" can be
-splitted in:
-
- http, www.divinf.it, 80, anonymous, dada@divinf.it, /index.html, #top
-
-If you don't specify a I<flags> parameter, ICU_ESCAPE will be used by
-default; for the possible values of I<flags> refer to the L<"Microsoft
-Win32 Internet Functions"> documentation. See also C<CreateURL>.
-
-Example:
-
- @parts=$INET->CrackURL("http://www.activeware.com");
- ($scheme, $host, $port, $user, $pass, $path, $extra) =
- $INET->CrackURL("http://www.divinf.it:80/perl-win32/index.sht#feedback");
-
-=item CreateURL scheme, hostname, port, username, password, path, extrainfo, [flags]
-
-=item CreateURL hashref, [flags]
-
-Creates a URL from its component parts. Returns C<undef> on errors,
-otherwise the created URL.
-
-If you pass I<hashref> (a reference to an hash array), the following
-values are taken from the array:
-
- %hash=(
- "scheme" => "scheme",
- "hostname" => "hostname",
- "port" => port,
- "username" => "username",
- "password" => "password",
- "path" => "path",
- "extrainfo" => "extrainfo",
- );
-
-If you don't specify a I<flags> parameter, ICU_ESCAPE will be used by
-default; for the other possible values of I<flags> refer to the
-L<"Microsoft Win32 Internet Functions"> documentation. See also
-C<CrackURL>.
-
-Example:
-
- $URL=$I->CreateURL("http", "www.divinf.it", 80, "", "", "/perl-win32/index.sht", "#feedback");
- $URL=$I->CreateURL(\%params);
-
-=item DataReceiveTimeout [value]
-
-Reads or sets the timeout value (in milliseconds) to use for data
-receive requests before they are canceled. If no I<value> parameter
-is specified, the current value is returned; otherwise, the timeout is
-set to I<value>. The default value for DataReceiveTimeout is
-infinite. See also C<DataSendTimeout>, C<QueryOption> and
-C<SetOption>.
-
-Example:
-
- $HTTP->DataReceiveTimeout(10000);
- $timeout = $HTTP->DataReceiveTimeout();
-
-=item DataSendTimeout [value]
-
-Reads or sets the timeout value (in milliseconds) to use for data send
-requests before they are canceled. If no I<value> parameter is
-specified, the current value is returned; otherwise, the timeout is
-set to I<value>. The default value for DataSendTimeout is infinite.
-See also C<DataReceiveTimeout>, C<QueryOption> and C<SetOption>.
-
-Example:
-
- $HTTP->DataSendTimeout(10000);
- $timeout = $HTTP->DataSendTimeout();
-
-=item Error
-
-Returns the last recorded error in the form of an array or string
-(depending upon the context) containing the error number and an error
-description. Can be applied on any Win32::Internet object (FTP
-sessions, etc.). There are 3 types of error you can encounter; they
-are recognizable by the error number returned:
-
-=over
-
-=item * -1
-
-A "trivial" error has occurred in the package. For example, you tried
-to use a method on the wrong type of object.
-
-=item * 1 .. 11999
-
-A generic error has occurred and the Win32::GetLastError error message
-is returned.
-
-=item * 12000 and higher
-
-An Internet error has occurred; the extended Win32 Internet API error
-message is returned.
-
-=back
-
-See also C<GetResponse>.
-
-Example:
-
- die $INET->Error(), qq(\n);
- ($ErrNum, $ErrText) = $INET->Error();
-
-=item FetchURL URL
-
-Fetch the content of an HTTP, FTP or GOPHER URL. Returns the content
-of the file read (or C<undef> if there was an error and nothing was
-read). See also C<OpenURL> and C<ReadFile>.
-
-Example:
-
- $file = $INET->FetchURL("http://www.yahoo.com/");
- $file = $INET->FetchURL("ftp://www.activeware.com/contrib/internet.zip");
-
-=item FTP ftpobject, server, username, password, [port, pasv, context]
-
-=item FTP ftpobject, hashref
-
-Opens an FTP connection to server logging in with the given
-I<username> and I<password>.
-
-The parameters and their values are:
-
-=over
-
-=item * server
-
-The server to connect to. Default: I<none>.
-
-=item * username
-
-The username used to login to the server. Default: anonymous.
-
-=item * password
-
-The password used to login to the server. Default: I<none>.
-
-=item * port
-
-The port of the FTP service on the server. Default: 21.
-
-=item * pasv
-
-If it is a value other than 0, use passive transfer mode. Default is
-taken from the parent Internet connection object; you can set this
-value with the C<Pasv> method.
-
-=item * context
-
-A number to identify this operation if it is asynchronous. See
-C<SetStatusCallback> and C<GetStatusCallback> for more info on
-asynchronous operations. Default: I<none>.
-
-=back
-
-If you pass I<hashref> (a reference to an hash array), the following
-values are taken from the array:
-
- %hash=(
- "server" => "server",
- "username" => "username",
- "password" => "password",
- "port" => port,
- "pasv" => pasv,
- "context" => context,
- );
-
-This method returns C<undef> if the connection failed, a number
-otherwise. You can then call any of the L<"FTP functions"> as methods
-of the newly created I<ftpobject>.
-
-Example:
-
- $result = $INET->FTP($FTP, "ftp.activeware.com", "anonymous", "dada\@divinf.it");
- # and then for example...
- $FTP->Cd("/ntperl/perl5.001m/CurrentBuild");
-
- $params{"server"} = "ftp.activeware.com";
- $params{"password"} = "dada\@divinf.it";
- $params{"pasv"} = 0;
- $result = $INET->FTP($FTP,\%params);
-
-=item GetResponse
-
-Returns the text sent by a remote server in response to the last
-function executed. It applies on any Win32::Internet object,
-particularly of course on L<FTP sessions|"FTP functions">. See also
-the C<Error> function.
-
-Example:
-
- print $INET->GetResponse();
- $INET->FTP($FTP, "ftp.activeware.com", "anonymous", "dada\@divinf.it");
- print $FTP->GetResponse();
-
-=item GetStatusCallback context
-
-Returns information about the progress of the asynchronous operation
-identified by I<context>; those informations consist of two values: a
-status code (one of the INTERNET_STATUS_* L<"Constants">) and an
-additional value depending on the status code; for example, if the
-status code returned is INTERNET_STATUS_HANDLE_CREATED, the second
-value will hold the handle just created. For more informations on
-those values, please refer to the L<"Microsoft Win32 Internet
-Functions"> documentation. See also C<SetStatusCallback>.
-
-Example:
-
- ($status, $info) = $INET->GetStatusCallback(1);
-
-=item HTTP httpobject, server, username, password, [port, flags, context]
-
-=item HTTP httpobject, hashref
-
-Opens an HTTP connection to I<server> logging in with the given
-I<username> and I<password>.
-
-The parameters and their values are:
-
-=over
-
-=item * server
-
-The server to connect to. Default: I<none>.
-
-=item * username
-
-The username used to login to the server. Default: anonymous.
-
-=item * password
-
-The password used to login to the server. Default: I<none>.
-
-=item * port
-
-The port of the HTTP service on the server. Default: 80.
-
-=item * flags
-
-Additional flags affecting the behavior of the function. Default:
-I<none>.
-
-=item * context
-
-A number to identify this operation if it is asynchronous. See
-C<SetStatusCallback> and C<GetStatusCallback> for more info on
-asynchronous operations. Default: I<none>.
-
-=back
-
-Refer to the L<"Microsoft Win32 Internet Functions"> documentation for
-more details on those parameters.
-
-If you pass I<hashref> (a reference to an hash array), the following
-values are taken from the array:
-
- %hash=(
- "server" => "server",
- "username" => "username",
- "password" => "password",
- "port" => port,
- "flags" => flags,
- "context" => context,
- );
-
-This method returns C<undef> if the connection failed, a number
-otherwise. You can then call any of the L<"HTTP functions"> as
-methods of the newly created I<httpobject>.
-
-Example:
-
- $result = $INET->HTTP($HTTP,"www.activeware.com","anonymous","dada\@divinf.it");
- # and then for example...
- ($statuscode, $headers, $file) = $HTTP->Request("/gifs/camel.gif");
-
- $params{"server"} = "www.activeware.com";
- $params{"password"} = "dada\@divinf.it";
- $params{"flags"} = INTERNET_FLAG_RELOAD;
- $result = $INET->HTTP($HTTP,\%params);
-
-=item new Win32::Internet [useragent, opentype, proxy, proxybypass, flags]
-
-=item new Win32::Internet [hashref]
-
-Creates a new Internet object and initializes the use of the Internet
-functions; this is required before any of the functions of this
-package can be used. Returns C<undef> if the connection fails, a number
-otherwise. The parameters and their values are:
-
-=over
-
-=item * useragent
-
-The user agent passed to HTTP requests. See C<OpenRequest>. Default:
-Perl-Win32::Internet/I<version>.
-
-=item * opentype
-
-How to access to the Internet (eg. directly or using a proxy).
-Default: INTERNET_OPEN_TYPE_DIRECT.
-
-=item * proxy
-
-Name of the proxy server (or servers) to use. Default: I<none>.
-
-=item * proxybypass
-
-Optional list of host names or IP addresses, or both, that are known
-locally. Default: I<none>.
-
-=item * flags
-
-Additional flags affecting the behavior of the function. Default:
-I<none>.
-
-=back
-
-Refer to the L<"Microsoft Win32 Internet Functions"> documentation for
-more details on those parameters. If you pass I<hashref> (a reference to
-an hash array), the following values are taken from the array:
-
- %hash=(
- "useragent" => "useragent",
- "opentype" => "opentype",
- "proxy" => "proxy",
- "proxybypass" => "proxybypass",
- "flags" => flags,
- );
-
-Example:
-
- $INET = new Win32::Internet();
- die qq(Cannot connect to Internet...\n) if ! $INET;
-
- $INET = new Win32::Internet("Mozilla/3.0", INTERNET_OPEN_TYPE_PROXY, "www.microsoft.com", "");
-
- $params{"flags"} = INTERNET_FLAG_ASYNC;
- $INET = new Win32::Internet(\%params);
-
-=item OpenURL urlobject, URL
-
-Opens a connection to an HTTP, FTP or GOPHER Uniform Resource Location
-(URL). Returns C<undef> on errors or a number if the connection was
-succesful. You can then retrieve the URL content by applying the
-methods C<QueryDataAvailable> and C<ReadFile> on the newly created
-I<urlobject>. See also C<FetchURL>.
-
-Example:
-
- $INET->OpenURL($URL, "http://www.yahoo.com/");
- $bytes = $URL->QueryDataAvailable();
- $file = $URL->ReadEntireFile();
- $URL->Close();
-
-=item Password [password]
-
-Reads or sets the password used for an C<FTP> or C<HTTP> connection.
-If no I<password> parameter is specified, the current value is
-returned; otherwise, the password is set to I<password>. See also
-C<Username>, C<QueryOption> and C<SetOption>.
-
-Example:
-
- $HTTP->Password("splurfgnagbxam");
- $password = $HTTP->Password();
-
-=item QueryDataAvailable
-
-Returns the number of bytes of data that are available to be read
-immediately by a subsequent call to C<ReadFile> (or C<undef> on
-errors). Can be applied to URL or HTTP request objects. See
-C<OpenURL> or C<OpenRequest>.
-
-Example:
-
- $INET->OpenURL($URL, "http://www.yahoo.com/");
- $bytes = $URL->QueryDataAvailable();
-
-=item QueryOption option
-
-Queries an Internet option. For the possible values of I<option>,
-refer to the L<"Microsoft Win32 Internet Functions"> document. See
-also C<SetOption>.
-
-Example:
-
- $value = $INET->QueryOption(INTERNET_OPTION_CONNECT_TIMEOUT);
- $value = $HTTP->QueryOption(INTERNET_OPTION_USERNAME);
-
-=item ReadEntireFile
-
-Reads all the data available from an opened URL or HTTP request
-object. Returns what have been read or C<undef> on errors. See also
-C<OpenURL>, C<OpenRequest> and C<ReadFile>.
-
-Example:
-
- $INET->OpenURL($URL, "http://www.yahoo.com/");
- $file = $URL->ReadEntireFile();
-
-=item ReadFile bytes
-
-Reads I<bytes> bytes of data from an opened URL or HTTP request
-object. Returns what have been read or C<undef> on errors. See also
-C<OpenURL>, C<OpenRequest>, C<QueryDataAvailable> and
-C<ReadEntireFile>.
-
-B<Note:> be careful to keep I<bytes> to an acceptable value (eg. don't
-tell him to swallow megabytes at once...). C<ReadEntireFile> in fact
-uses C<QueryDataAvailable> and C<ReadFile> in a loop to read no more
-than 16k at a time.
-
-Example:
-
- $INET->OpenURL($URL, "http://www.yahoo.com/");
- $chunk = $URL->ReadFile(16000);
-
-=item SetOption option, value
-
-Sets an Internet option. For the possible values of I<option>, refer to
-the L<"Microsoft Win32 Internet Functions"> document. See also
-C<QueryOption>.
-
-Example:
-
- $INET->SetOption(INTERNET_OPTION_CONNECT_TIMEOUT,10000);
- $HTTP->SetOption(INTERNET_OPTION_USERNAME,"dada");
-
-=item SetStatusCallback
-
-Initializes the callback routine used to return data about the
-progress of an asynchronous operation.
-
-Example:
-
- $INET->SetStatusCallback();
-
-This is one of the step required to perform asynchronous operations;
-the complete procedure is:
-
- # use the INTERNET_FLAG_ASYNC when initializing
- $params{'flags'}=INTERNET_FLAG_ASYNC;
- $INET = new Win32::Internet(\%params);
-
- # initialize the callback routine
- $INET->SetStatusCallback();
-
- # specify the context parameter (the last 1 in this case)
- $INET->HTTP($HTTP, "www.yahoo.com", "anonymous", "dada\@divinf.it", 80, 0, 1);
-
-At this point, control returns immediately to Perl and $INET->Error()
-will return 997, which means an asynchronous I/O operation is
-pending. Now, you can call
-
- $HTTP->GetStatusCallback(1);
-
-in a loop to verify what's happening; see also C<GetStatusCallback>.
-
-=item TimeConvert time
-
-=item TimeConvert seconds, minute, hours, day, month, year,
- day_of_week, RFC
-
-The first form takes a HTTP date/time string and returns the date/time
-converted in the following array: I<seconds, minute, hours, day,
-month, year, day_of_week>.
-
-The second form does the opposite (or at least it should, because
-actually seems to be malfunctioning): it takes the values and returns
-an HTTP date/time string, in the RFC format specified by the I<RFC>
-parameter (OK, I didn't find yet any accepted value in the range
-0..2000, let me know if you have more luck with it).
-
-Example:
-
- ($sec, $min, $hour, $day, $mday, $year, $wday) =
- $INET->TimeConvert("Sun, 26 Jan 1997 20:01:52 GMT");
-
- # the opposite DOESN'T WORK! which value should $RFC have???
- $time = $INET->TimeConvert(52, 1, 20, 26, 1, 1997, 0, $RFC);
-
-=item UserAgent [name]
-
-Reads or sets the user agent used for HTTP requests. If no I<name>
-parameter is specified, the current value is returned; otherwise, the
-user agent is set to I<name>. See also C<QueryOption> and
-C<SetOption>.
-
-Example:
-
- $INET->UserAgent("Mozilla/3.0");
- $useragent = $INET->UserAgent();
-
-=item Username [name]
-
-Reads or sets the username used for an C<FTP> or C<HTTP> connection.
-If no I<name> parameter is specified, the current value is returned;
-otherwise, the username is set to I<name>. See also C<Password>,
-C<QueryOption> and SetOption.
-
-Example:
-
- $HTTP->Username("dada");
- $username = $HTTP->Username();
-
-=item Version
-
-Returns the version numbers for the Win32::Internet package and the
-WININET.DLL version, as an array or string, depending on the context.
-The string returned will contain "package_version/DLL_version", while
-the array will contain: "package_version", "DLL_version".
-
-Example:
-
- $version = $INET->Version(); # should return "0.06/4.70.1215"
- @version = $INET->Version(); # should return ("0.06", "4.70.1215")
-
-=back
-
-
-=head2 FTP Functions
-
-B<General Note>
-
-All methods assume that you have the following lines:
-
- use Win32::Internet;
- $INET = new Win32::Internet();
- $INET->FTP($FTP, "hostname", "username", "password");
-
-somewhere before the method calls; in other words, we assume that you
-have an Internet object called $INET and an open FTP session called
-$FTP.
-
-See C<new> and C<FTP> for more information.
-
-
-B<Methods>
-
-=over
-
-=item Ascii
-
-=item Asc
-
-Sets the ASCII transfer mode for this FTP session. It will be applied
-to the subsequent C<Get> functions. See also the C<Binary> and
-C<Mode> function.
-
-Example:
-
- $FTP->Ascii();
-
-=item Binary
-
-=item Bin
-
-Sets the binary transfer mode for this FTP session. It will be
-applied to the subsequent C<Get> functions. See also the C<Ascii> and
-C<Mode> function.
-
-Example:
-
- $FTP->Binary();
-
-=item Cd path
-
-=item Cwd path
-
-=item Chdir path
-
-Changes the current directory on the FTP remote host. Returns I<path>
-or C<undef> on error.
-
-Example:
-
- $FTP->Cd("/pub");
-
-=item Delete file
-
-=item Del file
-
-Deletes a file on the FTP remote host. Returns C<undef> on error.
-
-Example:
-
- $FTP->Delete("110-i86.zip");
-
-=item Get remote, [local, overwrite, flags, context]
-
-Gets the I<remote> FTP file and saves it locally in I<local>. If
-I<local> is not specified, it will be the same name as I<remote>.
-Returns C<undef> on error. The parameters and their values are:
-
-=over
-
-=item * remote
-
-The name of the remote file on the FTP server. Default: I<none>.
-
-=item * local
-
-The name of the local file to create. Default: remote.
-
-=item * overwrite
-
-If 0, overwrites I<local> if it exists; with any other value, the
-function fails if the I<local> file already exists. Default: 0.
-
-=item * flags
-
-Additional flags affecting the behavior of the function. Default:
-I<none>.
-
-=item * context
-
-A number to identify this operation if it is asynchronous. See
-C<SetStatusCallback> and C<GetStatusCallback> for more info on
-asynchronous operations. Default: I<none>.
-
-=back
-
-Refer to the L<"Microsoft Win32 Internet Functions"> documentation for
-more details on those parameters.
-
-Example:
-
- $FTP->Get("110-i86.zip");
- $FTP->Get("/pub/perl/languages/CPAN/00index.html", "CPAN_index.html");
-
-=item List [pattern, listmode]
-
-=item Ls [pattern, listmode]
-
-=item Dir [pattern, listmode]
-
-Returns a list containing the files found in this directory,
-eventually matching the given I<pattern> (which, if omitted, is
-considered "*.*"). The content of the returned list depends on the
-I<listmode> parameter, which can have the following values:
-
-=over
-
-=item * listmode=1 (or omitted)
-
-the list contains the names of the files found. Example:
-
- @files = $FTP->List();
- @textfiles = $FTP->List("*.txt");
- foreach $file (@textfiles) {
- print "Name: ", $file, "\n";
- }
-
-=item * listmode=2
-
-the list contains 7 values for each file, which respectively are:
-
-=over
-
-=item * the file name
-
-=item * the DOS short file name, aka 8.3
-
-=item * the size
-
-=item * the attributes
-
-=item * the creation time
-
-=item * the last access time
-
-=item * the last modified time
-
-=back
-
-Example:
-
- @files = $FTP->List("*.*", 2);
- for($i=0; $i<=$#files; $i+=7) {
- print "Name: ", @files[$i], "\n";
- print "Size: ", @files[$i+2], "\n";
- print "Attr: ", @files[$i+3], "\n";
- }
-
-=item * listmode=3
-
-the list contains a reference to an hash array for each found file;
-each hash contains:
-
-=over
-
-=item * name => the file name
-
-=item * altname => the DOS short file name, aka 8.3
-
-=item * size => the size
-
-=item * attr => the attributes
-
-=item * ctime => the creation time
-
-=item * atime => the last access time
-
-=item * mtime => the last modified time
-
-=back
-
-Example:
-
- @files = $FTP->List("*.*", 3);
- foreach $file (@files) {
- print $file->{'name'}, " ", $file->{'size'}, " ", $file->{'attr'}, "\n";
- }
-
-B<Note:> all times are reported as strings of the following format:
-I<second, hour, minute, day, month, year>.
-
-Example:
-
- $file->{'mtime'} == "0,10,58,9,12,1996" stands for 09 Dec 1996 at 10:58:00
-
-=back
-
-=item Mkdir name
-
-=item Md name
-
-Creates a directory on the FTP remote host. Returns C<undef> on error.
-
-Example:
-
- $FTP->Mkdir("NextBuild");
-
-=item Mode [mode]
-
-If called with no arguments, returns the current transfer mode for
-this FTP session ("asc" for ASCII or "bin" for binary). The I<mode>
-argument can be "asc" or "bin", in which case the appropriate transfer
-mode is selected. See also the Ascii and Binary functions. Returns
-C<undef> on errors.
-
-Example:
-
- print "Current mode is: ", $FTP->Mode();
- $FTP->Mode("asc"); # ... same as $FTP->Ascii();
-
-=item Pasv [mode]
-
-If called with no arguments, returns 1 if the current FTP session has
-passive transfer mode enabled, 0 if not.
-
-You can call it with a I<mode> parameter (0/1) only as a method of a
-Internet object (see C<new>), in which case it will set the default
-value for the next C<FTP> objects you create (read: set it before,
-because you can't change this value once you opened the FTP session).
-
-Example:
-
- print "Pasv is: ", $FTP->Pasv();
-
- $INET->Pasv(1);
- $INET->FTP($FTP,"ftp.activeware.com", "anonymous", "dada\@divinf.it");
- $FTP->Pasv(0); # this will be ignored...
-
-=item Put local, [remote, context]
-
-Upload the I<local> file to the FTP server saving it under the name
-I<remote>, which if if omitted is the same name as I<local>. Returns
-C<undef> on error.
-
-I<context> is a number to identify this operation if it is asynchronous.
-See C<SetStatusCallback> and C<GetStatusCallback> for more info on
-asynchronous operations.
-
-Example:
-
- $FTP->Put("internet.zip");
- $FTP->Put("d:/users/dada/temp.zip", "/temp/dada.zip");
-
-=item Pwd
-
-Returns the current directory on the FTP server or C<undef> on errors.
-
-Example:
-
- $path = $FTP->Pwd();
-
-=item Rename oldfile, newfile
-
-=item Ren oldfile, newfile
-
-Renames a file on the FTP remote host. Returns C<undef> on error.
-
-Example:
-
- $FTP->Rename("110-i86.zip", "68i-011.zip");
-
-=item Rmdir name
-
-=item Rd name
-
-Removes a directory on the FTP remote host. Returns C<undef> on error.
-
-Example:
-
- $FTP->Rmdir("CurrentBuild");
-
-=back
-
-=head2 HTTP Functions
-
-B<General Note>
-
-All methods assume that you have the following lines:
-
- use Win32::Internet;
- $INET = new Win32::Internet();
- $INET->HTTP($HTTP, "hostname", "username", "password");
-
-somewhere before the method calls; in other words, we assume that you
-have an Internet object called $INET and an open HTTP session called
-$HTTP.
-
-See C<new> and C<HTTP> for more information.
-
-
-B<Methods>
-
-=over
-
-=item AddHeader header, [flags]
-
-Adds HTTP request headers to an HTTP request object created with
-C<OpenRequest>. For the possible values of I<flags> refer to the
-L<"Microsoft Win32 Internet Functions"> document.
-
-Example:
-
- $HTTP->OpenRequest($REQUEST,"/index.html");
- $REQUEST->AddHeader("If-Modified-Since: Sunday, 17-Nov-96 11:40:03 GMT");
- $REQUEST->AddHeader("Accept: text/html\r\n", HTTP_ADDREQ_FLAG_REPLACE);
-
-=item OpenRequest requestobject, [path, method, version, referer, accept, flags, context]
-
-=item OpenRequest requestobject, hashref
-
-Opens an HTTP request. Returns C<undef> on errors or a number if the
-connection was succesful. You can then use one of the C<AddHeader>,
-C<SendRequest>, C<QueryInfo>, C<QueryDataAvailable> and C<ReadFile>
-methods on the newly created I<requestobject>. The parameters and
-their values are:
-
-=over
-
-=item * path
-
-The object to request. This is generally a file name, an executable
-module, etc. Default: /
-
-=item * method
-
-The method to use; can actually be GET, POST, HEAD or PUT. Default:
-GET
-
-=item * version
-
-The HTTP version. Default: HTTP/1.0
-
-=item * referer
-
-The URL of the document from which the URL in the request was
-obtained. Default: I<none>
-
-=item * accept
-
-A single string with "\0" (ASCII zero) delimited list of content
-types accepted. The string must be terminated by "\0\0".
-Default: "text/*\0image/gif\0image/jpeg\0\0"
-
-=item * flags
-
-Additional flags affecting the behavior of the function. Default:
-I<none>
-
-=item * context
-
-A number to identify this operation if it is asynchronous. See
-C<SetStatusCallback> and C<GetStatusCallback> for more info on
-asynchronous operations. Default: I<none>
-
-=back
-
-Refer to the L<"Microsoft Win32 Internet Functions"> documentation for
-more details on those parameters. If you pass I<hashref> (a reference to
-an hash array), the following values are taken from the array:
-
- %hash=(
- "path" => "path",
- "method" => "method",
- "version" => "version",
- "referer" => "referer",
- "accept" => "accept",
- "flags" => flags,
- "context" => context,
- );
-
-See also C<Request>.
-
-Example:
-
- $HTTP->OpenRequest($REQUEST, "/index.html");
- $HTTP->OpenRequest($REQUEST, "/index.html", "GET", "HTTP/0.9");
-
- $params{"path"} = "/index.html";
- $params{"flags"} = "
- $HTTP->OpenRequest($REQUEST, \%params);
-
-=item QueryInfo header, [flags]
-
-Queries information about an HTTP request object created with
-C<OpenRequest>. You can specify an I<header> (for example,
-"Content-type") and/or one or more I<flags>. If you don't specify
-I<flags>, HTTP_QUERY_CUSTOM will be used by default; this means that
-I<header> should contain a valid HTTP header name. For the possible
-values of I<flags> refer to the L<"Microsoft Win32 Internet
-Functions"> document.
-
-Example:
-
- $HTTP->OpenRequest($REQUEST,"/index.html");
- $statuscode = $REQUEST->QueryInfo("", HTTP_QUERY_STATUS_CODE);
- $headers = $REQUEST->QueryInfo("", HTTP_QUERY_RAW_HEADERS_CRLF); # will get all the headers
- $length = $REQUEST->QueryInfo("Content-length");
-
-=item Request [path, method, version, referer, accept, flags]
-
-=item Request hashref
-
-Performs an HTTP request and returns an array containing the status
-code, the headers and the content of the file. It is a one-step
-procedure that makes an C<OpenRequest>, a C<SendRequest>, some
-C<QueryInfo>, C<ReadFile> and finally C<Close>. For a description of
-the parameters, see C<OpenRequest>.
-
-Example:
-
- ($statuscode, $headers, $file) = $HTTP->Request("/index.html");
- ($s, $h, $f) = $HTTP->Request("/index.html", "GET", "HTTP/1.0");
-
-=item SendRequest [postdata]
-
-Send an HTTP request to the destination server. I<postdata> are any
-optional data to send immediately after the request header; this is
-generally used for POST or PUT requests. See also C<OpenRequest>.
-
-Example:
-
- $HTTP->OpenRequest($REQUEST, "/index.html");
- $REQUEST->SendRequest();
-
- # A POST request...
- $HTTP->OpenRequest($REQUEST, "/cgi-bin/somescript.pl", "POST");
-
- #This line is a must -> (thanks Philip :)
- $REQUEST->AddHeader("Content-Type: application/x-www-form-urlencoded");
-
- $REQUEST->SendRequest("key1=value1&key2=value2&key3=value3");
-
-=back
-
-
-=head1 APPENDIX
-
-
-=head2 Microsoft Win32 Internet Functions
-
-Complete documentation for the Microsoft Win32 Internet Functions can
-be found, in both HTML and zipped Word format, at this address:
-
- http://www.microsoft.com/intdev/sdk/docs/wininet/
-
-=head2 Functions Table
-
-This table reports the correspondence between the functions offered by
-WININET.DLL and their implementation in the Win32::Internet
-extension. Functions showing a "---" are not currently
-implemented. Functions enclosed in parens ( ) aren't implemented
-straightforwardly, but in a higher-level routine, eg. together with
-other functions.
-
- WININET.DLL Win32::Internet
-
- InternetOpen new Win32::Internet
- InternetConnect FTP / HTTP
- InternetCloseHandle Close
- InternetQueryOption QueryOption
- InternetSetOption SetOption
- InternetSetOptionEx ---
- InternetSetStatusCallback SetStatusCallback
- InternetStatusCallback GetStatusCallback
- InternetConfirmZoneCrossing ---
- InternetTimeFromSystemTime TimeConvert
- InternetTimeToSystemTime TimeConvert
- InternetAttemptConnect ---
- InternetReadFile ReadFile
- InternetSetFilePointer ---
- InternetFindNextFile (List)
- InternetQueryDataAvailable QueryDataAvailable
- InternetGetLastResponseInfo GetResponse
- InternetWriteFile ---
- InternetCrackUrl CrackURL
- InternetCreateUrl CreateURL
- InternetCanonicalizeUrl CanonicalizeURL
- InternetCombineUrl CombineURL
- InternetOpenUrl OpenURL
- FtpFindFirstFile (List)
- FtpGetFile Get
- FtpPutFile Put
- FtpDeleteFile Delete
- FtpRenameFile Rename
- FtpOpenFile ---
- FtpCreateDirectory Mkdir
- FtpRemoveDirectory Rmdir
- FtpSetCurrentDirectory Cd
- FtpGetCurrentDirectory Pwd
- HttpOpenRequest OpenRequest
- HttpAddRequestHeaders AddHeader
- HttpSendRequest SendRequest
- HttpQueryInfo QueryInfo
- InternetErrorDlg ---
-
-
-Actually, I don't plan to add support for Gopher, Cookie and Cache
-functions. I will if there will be consistent requests to do so.
-
-There are a number of higher-level functions in the Win32::Internet
-that simplify some usual procedures, calling more that one WININET API
-function. This table reports those functions and the relative WININET
-functions they use.
-
- Win32::Internet WININET.DLL
-
- FetchURL InternetOpenUrl
- InternetQueryDataAvailable
- InternetReadFile
- InternetCloseHandle
-
- ReadEntireFile InternetQueryDataAvailable
- InternetReadFile
-
- Request HttpOpenRequest
- HttpSendRequest
- HttpQueryInfo
- InternetQueryDataAvailable
- InternetReadFile
- InternetCloseHandle
-
- List FtpFindFirstFile
- InternetFindNextFile
-
-
-=head2 Constants
-
-Those are the constants exported by the package in the main namespace
-(eg. you can use them in your scripts); for their meaning and proper
-use, refer to the Microsoft Win32 Internet Functions document.
-
- HTTP_ADDREQ_FLAG_ADD
- HTTP_ADDREQ_FLAG_REPLACE
- HTTP_QUERY_ALLOW
- HTTP_QUERY_CONTENT_DESCRIPTION
- HTTP_QUERY_CONTENT_ID
- HTTP_QUERY_CONTENT_LENGTH
- HTTP_QUERY_CONTENT_TRANSFER_ENCODING
- HTTP_QUERY_CONTENT_TYPE
- HTTP_QUERY_COST
- HTTP_QUERY_CUSTOM
- HTTP_QUERY_DATE
- HTTP_QUERY_DERIVED_FROM
- HTTP_QUERY_EXPIRES
- HTTP_QUERY_FLAG_REQUEST_HEADERS
- HTTP_QUERY_FLAG_SYSTEMTIME
- HTTP_QUERY_LANGUAGE
- HTTP_QUERY_LAST_MODIFIED
- HTTP_QUERY_MESSAGE_ID
- HTTP_QUERY_MIME_VERSION
- HTTP_QUERY_PRAGMA
- HTTP_QUERY_PUBLIC
- HTTP_QUERY_RAW_HEADERS
- HTTP_QUERY_RAW_HEADERS_CRLF
- HTTP_QUERY_REQUEST_METHOD
- HTTP_QUERY_SERVER
- HTTP_QUERY_STATUS_CODE
- HTTP_QUERY_STATUS_TEXT
- HTTP_QUERY_URI
- HTTP_QUERY_USER_AGENT
- HTTP_QUERY_VERSION
- HTTP_QUERY_WWW_LINK
- ICU_BROWSER_MODE
- ICU_DECODE
- ICU_ENCODE_SPACES_ONLY
- ICU_ESCAPE
- ICU_NO_ENCODE
- ICU_NO_META
- ICU_USERNAME
- INTERNET_FLAG_PASSIVE
- INTERNET_FLAG_ASYNC
- INTERNET_FLAG_HYPERLINK
- INTERNET_FLAG_KEEP_CONNECTION
- INTERNET_FLAG_MAKE_PERSISTENT
- INTERNET_FLAG_NO_AUTH
- INTERNET_FLAG_NO_AUTO_REDIRECT
- INTERNET_FLAG_NO_CACHE_WRITE
- INTERNET_FLAG_NO_COOKIES
- INTERNET_FLAG_READ_PREFETCH
- INTERNET_FLAG_RELOAD
- INTERNET_FLAG_RESYNCHRONIZE
- INTERNET_FLAG_TRANSFER_ASCII
- INTERNET_FLAG_TRANSFER_BINARY
- INTERNET_INVALID_PORT_NUMBER
- INTERNET_INVALID_STATUS_CALLBACK
- INTERNET_OPEN_TYPE_DIRECT
- INTERNET_OPEN_TYPE_PROXY
- INTERNET_OPEN_TYPE_PROXY_PRECONFIG
- INTERNET_OPTION_CONNECT_BACKOFF
- INTERNET_OPTION_CONNECT_RETRIES
- INTERNET_OPTION_CONNECT_TIMEOUT
- INTERNET_OPTION_CONTROL_SEND_TIMEOUT
- INTERNET_OPTION_CONTROL_RECEIVE_TIMEOUT
- INTERNET_OPTION_DATA_SEND_TIMEOUT
- INTERNET_OPTION_DATA_RECEIVE_TIMEOUT
- INTERNET_OPTION_HANDLE_TYPE
- INTERNET_OPTION_LISTEN_TIMEOUT
- INTERNET_OPTION_PASSWORD
- INTERNET_OPTION_READ_BUFFER_SIZE
- INTERNET_OPTION_USER_AGENT
- INTERNET_OPTION_USERNAME
- INTERNET_OPTION_VERSION
- INTERNET_OPTION_WRITE_BUFFER_SIZE
- INTERNET_SERVICE_FTP
- INTERNET_SERVICE_GOPHER
- INTERNET_SERVICE_HTTP
- INTERNET_STATUS_CLOSING_CONNECTION
- INTERNET_STATUS_CONNECTED_TO_SERVER
- INTERNET_STATUS_CONNECTING_TO_SERVER
- INTERNET_STATUS_CONNECTION_CLOSED
- INTERNET_STATUS_HANDLE_CLOSING
- INTERNET_STATUS_HANDLE_CREATED
- INTERNET_STATUS_NAME_RESOLVED
- INTERNET_STATUS_RECEIVING_RESPONSE
- INTERNET_STATUS_REDIRECT
- INTERNET_STATUS_REQUEST_COMPLETE
- INTERNET_STATUS_REQUEST_SENT
- INTERNET_STATUS_RESOLVING_NAME
- INTERNET_STATUS_RESPONSE_RECEIVED
- INTERNET_STATUS_SENDING_REQUEST
-
-
-=head1 VERSION HISTORY
-
-=over
-
-=item * 0.082 (4 Sep 2001)
-
-=over
-
-=item *
-
-Fix passive FTP mode. INTERNET_FLAG_PASSIVE was misspelled in earlier
-versions (as INTERNET_CONNECT_FLAG_PASSIVE) and wouldn't work. Found
-by Steve Raynesford <stever@evolvecomm.com>.
-
-=back
-
-=item * 0.081 (25 Sep 1999)
-
-=over
-
-=item *
-
-Documentation converted to pod format by Jan Dubois <JanD@ActiveState.com>.
-
-=item *
-
-Minor changes from Perl 5.005xx compatibility.
-
-=back
-
-=item * 0.08 (14 Feb 1997)
-
-=over
-
-=item *
-
-fixed 2 more bugs in Option(s) related subs (thanks to Brian
-Helterline!).
-
-=item *
-
-Error() now gets error messages directly from WININET.DLL.
-
-=item *
-
-The PLL file now comes in 2 versions, one for Perl version 5.001
-(build 100) and one for Perl version 5.003 (build 300 and
-higher). Everybody should be happy now :)
-
-=item *
-
-added an installation program.
-
-=back
-
-=item * 0.07 (10 Feb 1997)
-
-=over
-
-=item *
-
-fixed a bug in Version() introduced with 0.06...
-
-=item *
-
-completely reworked PM file, fixed *lots* of minor bugs, and removed
-almost all the warnings with "perl -w".
-
-=back
-
-=item * 0.06 (26 Jan 1997)
-
-=over
-
-=item *
-
-fixed another hideous bug in "new" (the 'class' parameter was still
-missing).
-
-=item *
-
-added support for asynchronous operations (work still in embryo).
-
-=item *
-
-removed the ending \0 (ASCII zero) from the DLL version returned by
-"Version".
-
-=item *
-
-added a lot of constants.
-
-=item *
-
-added safefree() after every safemalloc() in C... wonder why I didn't
-it before :)
-
-=item *
-
-added TimeConvert, which actually works one way only.
-
-=back
-
-=item * 0.05f (29 Nov 1996)
-
-=over
-
-=item *
-
-fixed a bug in "new" (parameters passed were simply ignored).
-
-=item *
-
-fixed another bug: "Chdir" and "Cwd" were aliases of RMDIR instead of
-CD..
-
-=back
-
-=item * 0.05 (29 Nov 1996)
-
-=over
-
-=item *
-
-added "CrackURL" and "CreateURL".
-
-=item *
-
-corrected an error in TEST.PL (there was a GetUserAgent instead of
-UserAgent).
-
-=back
-
-=item * 0.04 (25 Nov 1996)
-
-=over
-
-=item *
-
-added "Version" to retrieve package and DLL versions.
-
-=item *
-
-added proxies and other options to "new".
-
-=item *
-
-changed "OpenRequest" and "Request" to read parameters from a hash.
-
-=item *
-
-added "SetOption/QueryOption" and a lot of relative functions
-(connect, username, password, useragent, etc.).
-
-=item *
-
-added "CanonicalizeURL" and "CombineURL".
-
-=item *
-
-"Error" covers a wider spectrum of errors.
-
-=back
-
-=item * 0.02 (18 Nov 1996)
-
-=over
-
-=item *
-
-added support for HTTP sessions and requests.
-
-=back
-
-=item * 0.01 (11 Nov 1996)
-
-=over
-
-=item *
-
-fetching of HTTP, FTP and GOPHER URLs.
-
-=item *
-
-complete set of commands to manage an FTP session.
-
-=back
-
-=back
-
-=head1 AUTHOR
-
-Version 0.08 (14 Feb 1997) by Aldo Calpini <a.calpini@romagiubileo.it>
-
-
-=head1 CREDITS
-
-Win32::Internet is based on the Win32::Registry code written by Jesse
-Dougherty.
-
-Additional thanks to: Carl Tichler for his help in the initial
-development; Tore Haraldsen, Brian Helterline for the bugfixes; Dave
-Roth for his great source code examples.
-
-
-=head1 DISCLAIMER
-
-This program is FREE; you can redistribute, modify, disassemble, or
-even reverse engineer this software at your will. Keep in mind,
-however, that NOTHING IS GUARANTEED to work and everything you do is
-AT YOUR OWN RISK - I will not take responsability for any damage, loss
-of money and/or health that may arise from the use of this program!
-
-This is distributed under the terms of Larry Wall's Artistic License.