Internet(3) User Contributed Perl Documentation Internet(3)NAME
Win32::Internet - Access to WININET.DLL functions
INTRODUCTION
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.
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
"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@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.
General Internet Functions
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
CanonicalizeURL URL, [flags]
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);
Close
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...
CombineURL baseURL, relativeURL, [flags]
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", "..");
ConnectBackoff [value]
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();
ConnectRetries [value]
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();
ConnectTimeout [value]
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();
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 "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();
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 "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();
CrackURL URL, [flags]
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@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");
CreateURL scheme, hostname, port, username, password, path, extrainfo,
[flags]
CreateURL hashref, [flags]
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);
DataReceiveTimeout [value]
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();
DataSendTimeout [value]
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();
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:
· -1
A "trivial" error has occurred in the package. For example,
you tried to use a method on the wrong type of object.
· 1 .. 11999
A generic error has occurred and the Win32::GetLastError error
message is returned.
· 12000 and higher
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();
FetchURL URL
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");
FTP ftpobject, server, username, password, [port, pasv, context]
FTP ftpobject, hashref
Opens an FTP connection to server logging in with the given
username and password.
The parameters and their values are:
· server
The server to connect to. Default: none.
· username
The username used to login to the server. Default: anonymous.
· password
The password used to login to the server. Default: none.
· port
The port of the FTP service on the server. Default: 21.
· 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 "Pasv" method.
· context
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\@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);
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 FTP sessions. See also the "Error"
function.
Example:
print $INET->GetResponse();
$INET->FTP($FTP, "ftp.activeware.com", "anonymous", "dada\@divinf.it");
print $FTP->GetResponse();
GetStatusCallback context
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);
HTTP httpobject, server, username, password, [port, flags, context]
HTTP httpobject, hashref
Opens an HTTP connection to server logging in with the given
username and password.
The parameters and their values are:
· server
The server to connect to. Default: none.
· username
The username used to login to the server. Default: anonymous.
· password
The password used to login to the server. Default: none.
· port
The port of the HTTP service on the server. Default: 80.
· flags
Additional flags affecting the behavior of the function.
Default: none.
· context
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\@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);
new Win32::Internet [useragent, opentype, proxy, proxybypass, flags]
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 "undef" if the connection fails,
a number otherwise. The parameters and their values are:
· useragent
The user agent passed to HTTP requests. See "OpenRequest".
Default: Perl-Win32::Internet/version.
· opentype
How to access to the Internet (eg. directly or using a proxy).
Default: INTERNET_OPEN_TYPE_DIRECT.
· proxy
Name of the proxy server (or servers) to use. Default: none.
· proxybypass
Optional list of host names or IP addresses, or both, that are
known locally. Default: none.
· flags
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);
OpenURL urlobject, URL
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();
Password [password]
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();
QueryDataAvailable
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();
QueryOption option
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);
ReadEntireFile
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();
ReadFile bytes
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);
SetOption option, value
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");
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 "GetStatusCallback".
TimeConvert time
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: 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);
UserAgent [name]
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();
Username [name]
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();
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")
FTP Functions
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
Ascii
Asc 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();
Binary
Bin 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();
Cd path
Cwd path
Chdir path
Changes the current directory on the FTP remote host. Returns path
or "undef" on error.
Example:
$FTP->Cd("/pub");
Delete file
Del file
Deletes a file on the FTP remote host. Returns "undef" on error.
Example:
$FTP->Delete("110-i86.zip");
Get remote, [local, overwrite, flags, context]
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:
· remote
The name of the remote file on the FTP server. Default: none.
· local
The name of the local file to create. Default: remote.
· overwrite
If 0, overwrites local if it exists; with any other value, the
function fails if the local file already exists. Default: 0.
· flags
Additional flags affecting the behavior of the function.
Default: none.
· context
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");
List [pattern, listmode]
Ls [pattern, listmode]
Dir [pattern, listmode]
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:
· 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";
}
· listmode=2
the list contains 7 values for each file, which respectively
are:
· the file name
· the DOS short file name, aka 8.3
· the size
· the attributes
· the creation time
· the last access time
· the last modified time
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";
}
· listmode=3
the list contains a reference to an hash array for each found
file; each hash contains:
· name => the file name
· altname => the DOS short file name, aka 8.3
· size => the size
· attr => the attributes
· ctime => the creation time
· atime => the last access time
· mtime => the last modified time
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
Mkdir name
Md name
Creates a directory on the FTP remote host. Returns "undef" on
error.
Example:
$FTP->Mkdir("NextBuild");
Mode [mode]
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();
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 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...
Put local, [remote, context]
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");
Pwd Returns the current directory on the FTP server or "undef" on
errors.
Example:
$path = $FTP->Pwd();
Rename oldfile, newfile
Ren oldfile, newfile
Renames a file on the FTP remote host. Returns "undef" on error.
Example:
$FTP->Rename("110-i86.zip", "68i-011.zip");
Rmdir name
Rd name
Removes a directory on the FTP remote host. Returns "undef" on
error.
Example:
$FTP->Rmdir("CurrentBuild");
HTTP Functions
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
AddHeader header, [flags]
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);
OpenRequest requestobject, [path, method, version, referer, accept,
flags, context]
OpenRequest requestobject, hashref
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:
· path
The object to request. This is generally a file name, an
executable module, etc. Default: /
· method
The method to use; can actually be GET, POST, HEAD or PUT.
Default: GET
· version
The HTTP version. Default: HTTP/1.0
· referer
The URL of the document from which the URL in the request was
obtained. Default: none
· 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"
· flags
Additional flags affecting the behavior of the function.
Default: none
· context
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);
QueryInfo header, [flags]
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");
Request [path, method, version, referer, accept, flags]
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 "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");
SendRequest [postdata]
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");
APPENDIX
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/
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
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
VERSION HISTORY
· 0.082 (4 Sep 2001)
· 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>.
· 0.081 (25 Sep 1999)
· Documentation converted to pod format by Jan Dubois
<JanD@ActiveState.com>.
· Minor changes from Perl 5.005xx compatibility.
· 0.08 (14 Feb 1997)
· 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.
· 0.07 (10 Feb 1997)
· 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".
· 0.06 (26 Jan 1997)
· 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.
· 0.05f (29 Nov 1996)
· fixed a bug in "new" (parameters passed were simply ignored).
· fixed another bug: "Chdir" and "Cwd" were aliases of RMDIR
instead of CD..
· 0.05 (29 Nov 1996)
· added "CrackURL" and "CreateURL".
· corrected an error in TEST.PL (there was a GetUserAgent instead
of UserAgent).
· 0.04 (25 Nov 1996)
· 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.
· 0.02 (18 Nov 1996)
· added support for HTTP sessions and requests.
· 0.01 (11 Nov 1996)
· fetching of HTTP, FTP and GOPHER URLs.
· complete set of commands to manage an FTP session.
AUTHOR
Version 0.08 (14 Feb 1997) by Aldo Calpini <a.calpini@romagiubileo.it>
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.
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.
perl v5.14.2 2005-09-17 Internet(3)
