Win32::Internet - Access to WININET.DLL functions
This extension to Perl implements the Win32 Internet APIs (found in WININET.DLL). They give a complete support for HTTP, FTP and GOPHER connections.
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.
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 General Internet Functions explained later.
The objects available are:
Internet connections (the main object, see new
)
URLs (see OpenURL
)
FTP sessions (see FTP
)
HTTP sessions (see HTTP
)
HTTP requests (see OpenRequest
)
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@perl.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@perl.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\@perl.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.
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 new
for more information.
Methods
Converts a URL to a canonical format, which includes converting unsafe
characters to escape sequences. Returns the canonicalized URL or
undef
on errors. For the possible values of flags, refer to the
Microsoft Win32 Internet Functions document. See also
CombineURL
and OpenURL
.
Example:
$cURL = $INET->CanonicalizeURL($URL); $URL = $INET->CanonicalizeURL($cURL, ICU_DECODE);
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...
Combines a base and relative URL into a single URL. Returns the
(canonicalized) combined URL or undef
on errors. For the possible
values of flags, refer to the Microsoft Win32 Internet Functions document. See also CombineURL
and OpenURL
.
Example:
$URL = $INET->CombineURL("http://www.divinf.it/dada/perl/internet", "..");
Reads or sets the delay value, in milliseconds, to wait between
connection retries. If no value parameter is specified, the
current value is returned; otherwise, the delay between retries is set
to value. See also ConnectTimeout
, ConnectRetries
,
QueryOption
and SetOption
.
Example:
$HTTP->ConnectBackoff(2000); $backoff = $HTTP->ConnectBackoff();
Reads or sets the number of times a connection is retried before
considering it failed. If no value parameter is specified, the
current value is returned; otherwise, the number of retries is set to
value. The default value for ConnectRetries
is 5. See also
ConnectBackoff
, ConnectTimeout
, QueryOption
and SetOption
.
Example:
$HTTP->ConnectRetries(20); $retries = $HTTP->ConnectRetries();
Reads or sets the timeout value (in milliseconds) before a connection
is considered failed. If no value parameter is specified, the
current value is returned; otherwise, the timeout is set to value.
The default value for ConnectTimeout
is infinite. See also
ConnectBackoff
, ConnectRetries
, QueryOption
and SetOption
.
Example:
$HTTP->ConnectTimeout(10000); $timeout = $HTTP->ConnectTimeout();
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 FTP
sessions. If no value parameter
is specified, the current value is returned; otherwise, the timeout is
set to value. The default value for ControlReceiveTimeout
is
infinite. See also ControlSendTimeout
, QueryOption
and
SetOption
.
Example:
$HTTP->ControlReceiveTimeout(10000); $timeout = $HTTP->ControlReceiveTimeout();
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 FTP
sessions. If no value parameter
is specified, the current value is returned; otherwise, the timeout is
set to value. The default value for ControlSendTimeout
is
infinite. See also ControlReceiveTimeout
, QueryOption
and
SetOption
.
Example:
$HTTP->ControlSendTimeout(10000); $timeout = $HTTP->ControlSendTimeout();
Splits an URL into its component parts and returns them in an array.
Returns undef
on errors, otherwise the array will contain the
following values: 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@perl.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");
Creates a URL from its component parts. Returns undef
on errors,
otherwise the created URL.
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);
Reads or sets the timeout value (in milliseconds) to use for data
receive requests before they are canceled. If no value parameter
is specified, the current value is returned; otherwise, the timeout is
set to value. The default value for DataReceiveTimeout is
infinite. See also DataSendTimeout
, QueryOption
and
SetOption
.
Example:
$HTTP->DataReceiveTimeout(10000); $timeout = $HTTP->DataReceiveTimeout();
Reads or sets the timeout value (in milliseconds) to use for data send
requests before they are canceled. If no value parameter is
specified, the current value is returned; otherwise, the timeout is
set to value. The default value for DataSendTimeout is infinite.
See also DataReceiveTimeout
, QueryOption
and SetOption
.
Example:
$HTTP->DataSendTimeout(10000); $timeout = $HTTP->DataSendTimeout();
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:
A "trivial" error has occurred in the package. For example, you tried to use a method on the wrong type of object.
A generic error has occurred and the Win32::GetLastError error message is returned.
An Internet error has occurred; the extended Win32 Internet API error message is returned.
See also GetResponse
.
Example:
die $INET->Error(), qq(\n); ($ErrNum, $ErrText) = $INET->Error();
Fetch the content of an HTTP, FTP or GOPHER URL. Returns the content
of the file read (or undef
if there was an error and nothing was
read). See also OpenURL
and ReadFile
.
Example:
$file = $INET->FetchURL("http://www.yahoo.com/"); $file = $INET->FetchURL("ftp://www.activeware.com/contrib/internet.zip");
Opens an FTP connection to server logging in with the given username and password.
The parameters and their values are:
The server to connect to. Default: none.
The username used to login to the server. Default: anonymous.
The password used to login to the server. Default: none.
The port of the FTP service on the server. Default: 21.
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 Pasv
method.
A number to identify this operation if it is asynchronous. See
SetStatusCallback
and GetStatusCallback
for more info on
asynchronous operations. Default: none.
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\@perl.it"); # and then for example... $FTP->Cd("/ntperl/perl5.001m/CurrentBuild");
$params{"server"} = "ftp.activeware.com"; $params{"password"} = "dada\@perl.it"; $params{"pasv"} = 0; $result = $INET->FTP($FTP,\%params);
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 FTP sessions. See also
the Error
function.
Example:
print $INET->GetResponse(); $INET->FTP($FTP, "ftp.activeware.com", "anonymous", "dada\@perl.it"); print $FTP->GetResponse();
Returns information about the progress of the asynchronous operation
identified by context; those informations consist of two values: a
status code (one of the INTERNET_STATUS_* 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 Microsoft Win32 Internet Functions documentation. See also SetStatusCallback
.
Example:
($status, $info) = $INET->GetStatusCallback(1);
Opens an HTTP connection to server logging in with the given username and password.
The parameters and their values are:
The server to connect to. Default: none.
The username used to login to the server. Default: anonymous.
The password used to login to the server. Default: none.
The port of the HTTP service on the server. Default: 80.
Additional flags affecting the behavior of the function. Default: none.
A number to identify this operation if it is asynchronous. See
SetStatusCallback
and GetStatusCallback
for more info on
asynchronous operations. Default: none.
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\@perl.it"); # and then for example... ($statuscode, $headers, $file) = $HTTP->Request("/gifs/camel.gif");
$params{"server"} = "www.activeware.com"; $params{"password"} = "dada\@perl.it"; $params{"flags"} = INTERNET_FLAG_RELOAD; $result = $INET->HTTP($HTTP,\%params);
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 undef
if the connection fails, a number
otherwise. The parameters and their values are:
The user agent passed to HTTP requests. See OpenRequest
. Default:
Perl-Win32::Internet/version.
How to access to the Internet (eg. directly or using a proxy). Default: INTERNET_OPEN_TYPE_DIRECT.
Name of the proxy server (or servers) to use. Default: none.
Optional list of host names or IP addresses, or both, that are known locally. Default: none.
Additional flags affecting the behavior of the function. Default: none.
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);
Opens a connection to an HTTP, FTP or GOPHER Uniform Resource Location
(URL). Returns undef
on errors or a number if the connection was
succesful. You can then retrieve the URL content by applying the
methods QueryDataAvailable
and ReadFile
on the newly created
urlobject. See also FetchURL
.
Example:
$INET->OpenURL($URL, "http://www.yahoo.com/"); $bytes = $URL->QueryDataAvailable(); $file = $URL->ReadEntireFile(); $URL->Close();
Reads or sets the password used for an FTP
or HTTP
connection.
If no password parameter is specified, the current value is
returned; otherwise, the password is set to password. See also
Username
, QueryOption
and SetOption
.
Example:
$HTTP->Password("splurfgnagbxam"); $password = $HTTP->Password();
Returns the number of bytes of data that are available to be read
immediately by a subsequent call to ReadFile
(or undef
on
errors). Can be applied to URL or HTTP request objects. See
OpenURL
or OpenRequest
.
Example:
$INET->OpenURL($URL, "http://www.yahoo.com/"); $bytes = $URL->QueryDataAvailable();
Queries an Internet option. For the possible values of option,
refer to the Microsoft Win32 Internet Functions document. See
also SetOption
.
Example:
$value = $INET->QueryOption(INTERNET_OPTION_CONNECT_TIMEOUT); $value = $HTTP->QueryOption(INTERNET_OPTION_USERNAME);
Reads all the data available from an opened URL or HTTP request
object. Returns what have been read or undef
on errors. See also
OpenURL
, OpenRequest
and ReadFile
.
Example:
$INET->OpenURL($URL, "http://www.yahoo.com/"); $file = $URL->ReadEntireFile();
Reads bytes bytes of data from an opened URL or HTTP request
object. Returns what have been read or undef
on errors. See also
OpenURL
, OpenRequest
, QueryDataAvailable
and
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);
Sets an Internet option. For the possible values of option, refer to
the Microsoft Win32 Internet Functions document. See also
QueryOption
.
Example:
$INET->SetOption(INTERNET_OPTION_CONNECT_TIMEOUT,10000); $HTTP->SetOption(INTERNET_OPTION_USERNAME,"dada");
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\@perl.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 first form takes a HTTP date/time string and returns the date/time converted in the following array: 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 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);
Reads or sets the user agent used for HTTP requests. If no name
parameter is specified, the current value is returned; otherwise, the
user agent is set to name. See also QueryOption
and
SetOption
.
Example:
$INET->UserAgent("Mozilla/3.0"); $useragent = $INET->UserAgent();
Reads or sets the username used for an FTP
or HTTP
connection.
If no name parameter is specified, the current value is returned;
otherwise, the username is set to name. See also Password
,
QueryOption
and SetOption.
Example:
$HTTP->Username("dada"); $username = $HTTP->Username();
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")
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 new
and FTP
for more information.
Methods
Sets the ASCII transfer mode for this FTP session. It will be applied
to the subsequent Get
functions. See also the Binary
and
Mode
function.
Example:
$FTP->Ascii();
Sets the binary transfer mode for this FTP session. It will be
applied to the subsequent Get
functions. See also the Ascii
and
Mode
function.
Example:
$FTP->Binary();
Changes the current directory on the FTP remote host. Returns path
or undef
on error.
Example:
$FTP->Cd("/pub");
Deletes a file on the FTP remote host. Returns undef
on error.
Example:
$FTP->Delete("110-i86.zip");
Gets the remote FTP file and saves it locally in local. If
local is not specified, it will be the same name as remote.
Returns undef
on error. The parameters and their values are:
The name of the remote file on the FTP server. Default: none.
The name of the local file to create. Default: remote.
If 0, overwrites local if it exists; with any other value, the function fails if the local file already exists. Default: 0.
Additional flags affecting the behavior of the function. Default: none.
A number to identify this operation if it is asynchronous. See
SetStatusCallback
and GetStatusCallback
for more info on
asynchronous operations. Default: none.
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");
Returns a list containing the files found in this directory, eventually matching the given pattern (which, if omitted, is considered "*.*"). The content of the returned list depends on the listmode parameter, which can have the following values:
the list contains the names of the files found. Example:
@files = $FTP->List(); @textfiles = $FTP->List("*.txt"); foreach $file (@textfiles) { print "Name: ", $file, "\n"; }
the list contains 7 values for each file, which respectively are:
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"; }
the list contains a reference to an hash array for each found file; each hash contains:
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
Creates a directory on the FTP remote host. Returns undef
on error.
Example:
$FTP->Mkdir("NextBuild");
If called with no arguments, returns the current transfer mode for
this FTP session ("asc" for ASCII or "bin" for binary). The mode
argument can be "asc" or "bin", in which case the appropriate transfer
mode is selected. See also the Ascii and Binary functions. Returns
undef
on errors.
Example:
print "Current mode is: ", $FTP->Mode(); $FTP->Mode("asc"); # ... same as $FTP->Ascii();
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 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\@perl.it"); $FTP->Pasv(0); # this will be ignored...
Upload the local file to the FTP server saving it under the name
remote, which if if omitted is the same name as local. Returns
undef
on error.
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");
Returns the current directory on the FTP server or undef
on errors.
Example:
$path = $FTP->Pwd();
Renames a file on the FTP remote host. Returns undef
on error.
Example:
$FTP->Rename("110-i86.zip", "68i-011.zip");
Removes a directory on the FTP remote host. Returns undef
on error.
Example:
$FTP->Rmdir("CurrentBuild");
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 new
and HTTP
for more information.
Methods
Adds HTTP request headers to an HTTP request object created with
OpenRequest
. For the possible values of flags refer to the
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);
Opens an HTTP request. Returns undef
on errors or a number if the
connection was succesful. You can then use one of the AddHeader
,
SendRequest
, QueryInfo
, QueryDataAvailable
and ReadFile
methods on the newly created requestobject. The parameters and
their values are:
The object to request. This is generally a file name, an executable module, etc. Default: /
The method to use; can actually be GET, POST, HEAD or PUT. Default: GET
The HTTP version. Default: HTTP/1.0
The URL of the document from which the URL in the request was obtained. Default: none
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"
Additional flags affecting the behavior of the function. Default: none
A number to identify this operation if it is asynchronous. See
SetStatusCallback
and GetStatusCallback
for more info on
asynchronous operations. Default: none
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);
Queries information about an HTTP request object created with
OpenRequest
. You can specify an header (for example,
"Content-type") and/or one or more flags. If you don't specify
flags, HTTP_QUERY_CUSTOM will be used by default; this means that
header should contain a valid HTTP header name. For the possible
values of flags refer to the 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");
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 OpenRequest
, a SendRequest
, some
QueryInfo
, ReadFile
and finally Close
. For a description of
the parameters, see OpenRequest
.
Example:
($statuscode, $headers, $file) = $HTTP->Request("/index.html"); ($s, $h, $f) = $HTTP->Request("/index.html", "GET", "HTTP/1.0");
Send an HTTP request to the destination server. postdata are any
optional data to send immediately after the request header; this is
generally used for POST or PUT requests. See also 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");
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/
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
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
Move sample.pl and test-async.pl into the eg/ subdirectory to avoid installing them into the Perl/bin directory.
Use T_BOOL instead of T_IV for BOOL typemap entry so that the code doesn't warn on undef.
This release unfortunately did not update $Win32::Internet::VERSION. Only META.yml reffered to this release as version 0.083.
New version for separate upload to CPAN.
Updated email addresses (but some stale references to divinf.it still remain).
Simplified Makefile.PL; added META.yml; added ppport.h.
Renamed test.pl to sample.pl because it doesn't generate TAP output.
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>.
Documentation converted to pod format by Jan Dubois <JanD@ActiveState.com>.
Minor changes from Perl 5.005xx compatibility.
fixed 2 more bugs in Option(s) related subs (thanks to Brian Helterline!).
Error()
now gets error messages directly from WININET.DLL.
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 :)
added an installation program.
fixed a bug in Version()
introduced with 0.06...
completely reworked PM file, fixed *lots* of minor bugs, and removed almost all the warnings with "perl -w".
fixed another hideous bug in "new" (the 'class' parameter was still missing).
added support for asynchronous operations (work still in embryo).
removed the ending \0 (ASCII zero) from the DLL version returned by "Version".
added a lot of constants.
added safefree()
after every safemalloc()
in C... wonder why I didn't
it before :)
added TimeConvert, which actually works one way only.
fixed a bug in "new" (parameters passed were simply ignored).
fixed another bug: "Chdir" and "Cwd" were aliases of RMDIR instead of CD..
added "CrackURL" and "CreateURL".
corrected an error in TEST.PL (there was a GetUserAgent instead of UserAgent).
added "Version" to retrieve package and DLL versions.
added proxies and other options to "new".
changed "OpenRequest" and "Request" to read parameters from a hash.
added "SetOption/QueryOption" and a lot of relative functions (connect, username, password, useragent, etc.).
added "CanonicalizeURL" and "CombineURL".
"Error" covers a wider spectrum of errors.
added support for HTTP sessions and requests.
fetching of HTTP, FTP and GOPHER URLs.
complete set of commands to manage an FTP session.
Version 0.08 (14 Feb 1997) by Aldo Calpini <a.calpini@romagiubileo.it>
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.
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.