diff options
Diffstat (limited to 'Master/tlpkg/tlperl.old/lib/Win32/Internet.pm')
-rw-r--r-- | Master/tlpkg/tlperl.old/lib/Win32/Internet.pm | 3009 |
1 files changed, 3009 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl.old/lib/Win32/Internet.pm b/Master/tlpkg/tlperl.old/lib/Win32/Internet.pm new file mode 100644 index 00000000000..f6dac3130af --- /dev/null +++ b/Master/tlpkg/tlperl.old/lib/Win32/Internet.pm @@ -0,0 +1,3009 @@ +####################################################################### +# +# 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. |