See the ``Version History'' and the ``Functions Table'' for a list of the currently supported features. You should also get a copy of the ``Microsoft Win32 Internet Functions'' documentation.
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 ``General Internet Functions'' explained later.
The objects available are:
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 "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 "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 ``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.
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 "new" for more information.
Methods
Example:
$cURL = $INET->CanonicalizeURL($URL);
$URL = $INET->CanonicalizeURL($cURL, ICU_DECODE);
Example:
$INET->Close();
$FTP->Close();
$INET->Close($FTP); # same as above...
Example:
$URL = $INET->CombineURL("http://www.divinf.it/dada/perl/internet", "..");
Example:
$HTTP->ConnectBackoff(2000);
$backoff = $HTTP->ConnectBackoff();
Example:
$HTTP->ConnectRetries(20);
$retries = $HTTP->ConnectRetries();
Example:
$HTTP->ConnectTimeout(10000);
$timeout = $HTTP->ConnectTimeout();
Example:
$HTTP->ControlReceiveTimeout(10000);
$timeout = $HTTP->ControlReceiveTimeout();
Example:
$HTTP->ControlSendTimeout(10000);
$timeout = $HTTP->ControlSendTimeout();
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 flags parameter, ICU_ESCAPE will be used by default; for the possible values of flags refer to the ``Microsoft Win32 Internet Functions'' documentation. See also "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");
If you pass 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 flags parameter, ICU_ESCAPE will be used by default; for the other possible values of flags refer to the ``Microsoft Win32 Internet Functions'' documentation. See also "CrackURL".
Example:
$URL=$I->CreateURL("http", "www.divinf.it", 80, "", "", "/perl-win32/index.sht", "#feedback");
$URL=$I->CreateURL(\%params);
Example:
$HTTP->DataReceiveTimeout(10000);
$timeout = $HTTP->DataReceiveTimeout();
Example:
$HTTP->DataSendTimeout(10000);
$timeout = $HTTP->DataSendTimeout();
See also "GetResponse".
Example:
die $INET->Error(), qq(\n);
($ErrNum, $ErrText) = $INET->Error();
Example:
$file = $INET->FetchURL("http://www.yahoo.com/");
$file = $INET->FetchURL("ftp://www.activeware.com/contrib/internet.zip");
The parameters and their values are:
If you pass 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 "undef" if the connection failed, a number otherwise. You can then call any of the ``FTP functions'' as methods of the newly created 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);
Example:
print $INET->GetResponse();
$INET->FTP($FTP, "ftp.activeware.com", "anonymous", "dada\@divinf.it");
print $FTP->GetResponse();
Example:
($status, $info) = $INET->GetStatusCallback(1);
The parameters and their values are:
Refer to the ``Microsoft Win32 Internet Functions'' documentation for more details on those parameters.
If you pass 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 "undef" if the connection failed, a number otherwise. You can then call any of the ``HTTP functions'' as methods of the newly created 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);
Refer to the ``Microsoft Win32 Internet Functions'' documentation for more details on those parameters. If you pass 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);
Example:
$INET->OpenURL($URL, "http://www.yahoo.com/");
$bytes = $URL->QueryDataAvailable();
$file = $URL->ReadEntireFile();
$URL->Close();
Example:
$HTTP->Password("splurfgnagbxam");
$password = $HTTP->Password();
Example:
$INET->OpenURL($URL, "http://www.yahoo.com/");
$bytes = $URL->QueryDataAvailable();
Example:
$value = $INET->QueryOption(INTERNET_OPTION_CONNECT_TIMEOUT);
$value = $HTTP->QueryOption(INTERNET_OPTION_USERNAME);
Example:
$INET->OpenURL($URL, "http://www.yahoo.com/");
$file = $URL->ReadEntireFile();
Note: be careful to keep bytes to an acceptable value (eg. don't tell him to swallow megabytes at once...). "ReadEntireFile" in fact uses "QueryDataAvailable" and "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);
Example:
$INET->SetOption(INTERNET_OPTION_CONNECT_TIMEOUT,10000);
$HTTP->SetOption(INTERNET_OPTION_USERNAME,"dada");
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 "GetStatusCallback".
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 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);
Example:
$INET->UserAgent("Mozilla/3.0");
$useragent = $INET->UserAgent();
Example:
$HTTP->Username("dada");
$username = $HTTP->Username();
Example:
$version = $INET->Version(); # should return "0.06/4.70.1215"
@version = $INET->Version(); # should return ("0.06", "4.70.1215")
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 "new" and "FTP" for more information.
Methods
Example:
$FTP->Ascii();
Example:
$FTP->Binary();
Example:
$FTP->Cd("/pub");
Example:
$FTP->Delete("110-i86.zip");
Refer to the ``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");
@files = $FTP->List();
@textfiles = $FTP->List("*.txt");
foreach $file (@textfiles) {
print "Name: ", $file, "\n";
}
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";
}
Example:
@files = $FTP->List("*.*", 3);
foreach $file (@files) {
print $file->{'name'}, " ", $file->{'size'}, " ", $file->{'attr'}, "\n";
}
Note: all times are reported as strings of the following format: second, hour, minute, day, month, year.
Example:
$file->{'mtime'} == "0,10,58,9,12,1996" stands for 09 Dec 1996 at 10:58:00
Example:
$FTP->Mkdir("NextBuild");
Example:
print "Current mode is: ", $FTP->Mode();
$FTP->Mode("asc"); # ... same as $FTP->Ascii();
You can call it with a mode parameter (0/1) only as a method of a Internet object (see "new"), in which case it will set the default value for the next "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...
context is a number to identify this operation if it is asynchronous. See "SetStatusCallback" and "GetStatusCallback" for more info on asynchronous operations.
Example:
$FTP->Put("internet.zip");
$FTP->Put("d:/users/dada/temp.zip", "/temp/dada.zip");
Example:
$path = $FTP->Pwd();
Example:
$FTP->Rename("110-i86.zip", "68i-011.zip");
Example:
$FTP->Rmdir("CurrentBuild");
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 "new" and "HTTP" for more information.
Methods
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);
Refer to the ``Microsoft Win32 Internet Functions'' documentation for more details on those parameters. If you pass 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 "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);
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");
Example:
($statuscode, $headers, $file) = $HTTP->Request("/index.html");
($s, $h, $f) = $HTTP->Request("/index.html", "GET", "HTTP/1.0");
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");
http://www.microsoft.com/intdev/sdk/docs/wininet/
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
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
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.
This is distributed under the terms of Larry Wall's Artistic License.