Win32::Internet (Perl in a Nutshell, 2nd Edition)

22.7. Win32::Internet

The Win32::Internet extension implements the Win32 Internet APIs (found in WININET.DLL), providing support for HTTP, FTP, and Gopher connections.

All types of connections start as a basic Internet connection that must be opened with the following command :

use Win32::Internet;
$Connection = Win32::Internet->new( );

This creates an Internet object in Perl on which you use the functions provided in this module to create more specific connection objects. The objects and functions that create them are:

Internet connections (the main object, with new)
URLs (with OpenURL)
FTP sessions (with FTP)
HTTP sessions (with HTTP)
HTTP requests (with OpenRequest)

This module provides 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 less powerful. Other functions 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.

For example, the function FetchURL fetches the contents of any HTTP, FTP, or Gopher URL with a simple command:

$inet = new Win32::Internet( );
$file = $inet->FetchURL("http://www.yahoo.com");

You can achieve the same result with this series of commands, which is what FetchURL actually does:

$inet = new Win32::Internet( );
$url = $inet->OpenURL("http://www.yahoo.com");
$file = $url->ReadFile( );
$url->Close( );

22.7.1. General Internet Methods

The methods described in this section are used on Internet connection objects created with new:

$inet = Win32::Internet->new( );

You can supply new with an optional list of arguments (or a reference to a hash containing them) that looks like this:

Win32::Internet->new [useragent, opentype, proxy, proxybypass, flags] 
Win32::Internet->new [$hashref]

The parameters and their values are:

useragent: The user agent string passed to HTTP requests. Default is Perl-Win32Internet/version.
opentype: How to access the Internet (e.g., directly or using a proxy). Default is INTERNET_OPEN_TYPE_DIRECT.
proxy: Name of the proxy server (or servers) to use. Default is none.
proxybypass: Optional list of hostnames or IP addresses that are known locally. Default is none.
flags: Additional flags affecting the behavior of the function. Default is none.

If you pass a hash reference to the function, the following values are taken from the hash:

%hash=(
  "useragent"   => "useragent",
  "opentype"    => "opentype",
  "proxy"       => "proxy",
  "proxybypass" => "proxybypass",
  "flags"       => flags,
);

The following methods can be used on Internet connection objects.

CanonicalizeURL

$inet->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 error. For the possible values of flags, refer to the Microsoft Win32 Internet Functions documentation.

Close

$inet->Close([$obj])

Closes an Internet connection. This can be applied to any Win32::Internet object. 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 such an object is destroyed by other means).

CombineURL

$inet->CombineURL(baseURL, relativeURL, [flags])

Combines a base and relative URL into a single URL. Returns the (canonicalized) combined URL, or undef on error. For the possible values of flags, refer to the Microsoft Win32 Internet Functions documentation.

ConnectBackoff

$inet->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.

ConnectionRetries

$inet->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. The default value is 5.

ConnectTimeout

$inet->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 is infinity.

ControlReceiveTimeout

$inet->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. The default value is infinity.

ControlSendTimeout

$inet->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. The default value is infinity.

CrackURL

$inet->CrackURL(URL, [flags])

Splits a URL into its component parts and returns them in an array. Returns undef on error. 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 split into:

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.

CreateURL

$inet->CreateURL(scheme, hostname, port, username, password, path, extrainfo, [flags])
$inet->CreateURL($hashref, [flags])

Creates a URL from its component parts. Returns undef on error and the created URL if successful. If you pass a hash reference, 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.

DataReceiveTimeout

$inet->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. The default value is infinity.

DataSendTimeout

$inet->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. The default value is infinity.

Error

$inet->Error(  )

Returns the last recorded error in the form of an array or string (depending on the context) containing the error number and an error description. Can be applied on any Win32::Internet object (FTP sessions, etc.). There are three types of errors you can encounter, 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-11,999: A generic error has occurred, and the Win32::GetLastError error message is returned.
12,000 and higher: An Internet error has occurred, and the extended Win32 Internet API error message is returned.

FetchURL

$inet->FetchURL(URL)

Fetches the content of an HTTP, FTP, or Gopher URL. Returns the contents of the file read (or undef if there was an error and nothing was read).

FTP

$inet->FTP($ftpobject, server, username, pwd, [port, pasv, context])
$inet->FTP($ftpobject, $hashref)

Opens an FTP connection to server, logging in with the given username and password. The new connection object is saved to ftpobject. The parameters and their values are:

server: The server to connect to.
username: The username used to log in to the server. Default is anonymous.
pwd: The password used to log in to the server. Default is none.
port: The port of the FTP service on the server. Default is 21.
pasv: If it is a value other than 0, use passive transfer mode. Otherwise, it 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.

If you pass a hash reference, the following values are taken from the hash:

%hash=( "server" => "server", "username" => "username", "password" => "password", "port" => port, "pasv" => pasv, "context" => context, );

The FTP 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 FTP object.

GetResponse

$inet->GetResponse(  )

Returns the text sent by a remote server in response to the last function executed. It applies to any Win32::Internet object, particularly FTP sessions.

GetStatusCallback

$inet->GetStatusCallback(context)

Returns information about the progress of the asynchronous operation identified by context; this information consists 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 information on these values, refer to the Microsoft Win32 Internet Functions documentation.

HTTP

$inet->HTTP(httpobject, server, username, password, [port, flags, context])
$inet->HTTP($httpobject, $hashref)

Opens an HTTP connection to server, logging in with the given username and password. The new connection object is saved as httpobject. The parameters and their values are:

server: The server to connect to.
username: The username used to log in to the server. Default is anonymous.
password: The password used to log in to the server. Default is none.
port: The port of the HTTP service on the server. Default is 80.
flags: Additional flags affecting the behavior of the function.
context: A number to identify this operation if it is asynchronous.

If you pass a hash reference, the following values are taken from the hash:

%hash=( "server" => "server", "username" => "username", "password" => "password", "port" => port, "flags" => flags, "context" => context, );

The HTTP 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.

OpenURL

$inet->OpenURL(urlobject, URL)

Opens a connection to an HTTP, FTP, or Gopher URL. Returns undef on error, or a number if the connection was successful. You can then retrieve the URL content by applying the methods QueryDataAvailable and ReadFile on the newly created urlobject. See also FetchURL.

Password

$inet->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.

QueryDataAvailable

$inet->QueryDataAvailable(  )

Returns the number of bytes of data available to be read immediately by a subsequent call to ReadFile (or undef on error). Can be applied to URL or HTTP request objects.

QueryOption

$inet->QueryOption(option)

Queries an Internet option. For the possible values of option, refer to the Microsoft Win32 Internet Functions documentation.

ReadEntireFile

$inet->ReadEntireFile(  )

Reads all the data available from an opened URL or HTTP request object. Returns what has been read, or undef on error.

ReadFile

$inet->ReadFile(bytes)

Reads and returns the specified number of bytes of data from an opened URL or HTTP request object. Returns undef on error. Be careful to keep bytes to an acceptable value.

SetOption

$inet->SetOption(option, value)

Sets an Internet option. For the possible values of option, refer to the Microsoft Win32 Internet Functions documentation.

SetStatusCallback

$inet->SetStatusCallback(  )

Initializes the callback routine used to return data about the progress of an asynchronous operation. This is one of the steps 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

$inet->TimeConvert(time)

Takes an HTTP date/time string and returns the date/time converted in the following array: (seconds, minutes, hours, day, month, year, day_of_week).

UserAgent

$inet->UserAgent([name])

Reads or sets the user agent name used for HTTP requests. If no name is specified, the current value is returned.

Username

$inet->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.

Version

$inet->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. For example:

$version = $inet->Version( );
# Should return "0.06/4.70.1215"
@version = $inet->Version( );
# Should return ("0.06", "4.70.1215")

22.7.2. FTP Functions

The methods described in this section are used to control FTP sessions. They apply to FTP session objects created by the FTP method on an Internet connection object. FTP creates an open FTP session and assigns it to an object ($FTP):

use Win32::Internet;
$inet = new Win32::Internet( );
$inet->FTP($FTP, "hostname", "username", "password");

The following methods are used on FTP session objects.

Ascii

$FTP->Ascii(  )
$FTP->Asc(  )

Sets the ASCII transfer mode for this FTP session. It will be applied to subsequent Get functions.

Binary

$FTP->Binary(  )
$FTP->Bin(  )

Sets the binary transfer mode for this FTP session. It will be applied to subsequent Get functions.

$FTP->Cd(path)
$FTP->Cwd(path)
$FTP->Chdir(path)

Changes the current directory on the FTP remote host. Returns path, or undef on error.

Delete

$FTP->Delete(file)
$FTP->Del(file)

Deletes fileon the FTP remote host. Returns undef on error.

Get

$FTP->Get(file, [local, overwrite, flags, context])

Gets the remote FTP file and saves it locally in local. If localis not specified, it will be the same name as file. Returns undef on error. The parameters and their values are:

file: The name of the remote file on the FTP server.
local: The name of the local file to create.
overwrite: If 0, overwrites localif it exists. With any other value, the function fails if the local file already exists. Default is 0.
flags: Additional flags affecting the behavior of the function. None by default.
context: A number to identify this operation if it is asynchronous. (See SetStatusCallback and GetStatusCallback for more information on asynchronous operations.) None by default.

List

$FTP->List([pattern, listmode])
$FTP->Ls([pattern, listmode])
$FTP->Dir([pattern, listmode])

Returns a list containing the files found in the current directory, matching the given pattern, if specified. The content of the returned list depends on the listmodeparameter, which can have the following values:

1 (default): The list contains the names of the files found.
2: The list contains seven values for each file:

The filename

The DOS short filename, a.k.a. 8.3

The size

The attributes

The creation time

The last access time

The last modified time
3: The list contains a reference to a hash for each found file. Each hash contains the following key/value pairs:

name => filename altname => DOS short filename, a.k.a. 8.3 size => size attr => attributes ctime => creation time atime => last access time mtime => last modified time

All times are reported as strings of the following format: second, hour, minute, day, month, year. For example:

$file->{'mtime'} == "0,10,58,9,12,1996" # Stands for 09 Dec 1996 at 10:58:00

Mkdir

$FTP->Mkdir(name)
$FTP->Md(name)

Creates the directory name on the FTP remote host. Returns undef on error.

Mode

$FTP->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. Returns undef on error.

Pasv

$FTP->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, in which case it will set the default value for the next FTP object you create (i.e., set it before, because you can't change this value once you open the FTP session).

Put

$FTP->Put(file, [remote, context])

Uploads the local file to the FTP server, saving it under the name remote, which, if omitted, is the same name as file. Returns undef on error. contextis a number to identify this operation if it is asynchronous. See SetStatusCallback and GetStatusCallback for more information on asynchronous operations.

Pwd

$FTP->Pwd(  )

Returns the current directory on the FTP server, or undef on error.

Rename

$FTP->Rename(oldfile, newfile)
$FTP->Ren(oldfile, newfile)

Renames a file on the FTP remote host. Returns undef on error.

Rmdir

$FTP->Rmdir(name)
$FTP->Rd(name)

Removes the directory name on the FTP remote host. Returns undef on error.

22.7.3. HTTP Functions

The methods described in this section are used to create and control an HTTP session. Open an HTTP session using the HTTP method on an Internet connection object:

use Win32::Internet;
$inet = new Win32::Internet( );
$inet->HTTP($http, "hostname", "username", "password");

This opens the session and creates the HTTP session object $http. The following methods can be used on HTTP session objects.

AddHeader

$request->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 documentation.

OpenRequest

$http->OpenRequest(requestobject, [path, method, version, 
referer, accept, flags, context])
$http->OpenRequest($requestobject, hashref)

Opens an HTTP request and saves it as $requestobject. Returns undef on error, or a number if the connection was successful. You can then use one of the AddHeader, SendRequest, QueryInfo, QueryDataAvailable, and ReadFile methods on the newly created requestobject. The optional parameters and their values are:

path: The object to request. This is generally a filename, an executable module, etc. The default is /.
method: The method to use, which can be GET, POST, HEAD, or PUT. Default is GET.
version: The HTTP version. Default is HTTP/1.0.
referer: The URL of the document from which the URL in the request was obtained.
accept: The content types accepted. They must be separated by a \0 (ASCII zero). Default types are text/* image/gif image/jpeg.
flags: Additional flags affecting the behavior of the function.
context: A number to identify this operation if it is asynchronous. See SetStatusCallback and GetStatusCallback for more information on asynchronous operations.

A reference to a hash containing the previous list of parameters can also be supplied to this method:

%hash=(
  "path"        => "path",
  "method"      => "method",
  "version"     => "version",
  "referer"     => "referer",
  "accept"      => "accept",
  "flags"       => flags,
  "context"     => context,
);

QueryInfo

$request->QueryInfo(header, [flags])

Queries information about an HTTP request object ($request) created with OpenRequest. You can specify a 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 the header should contain a valid HTTP header name. For the possible values of flags, refer to the Microsoft Win32 Internet Functions documentation.

Request

$http->Request([path, method, version, referer, accept, flags])
$http->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 executes OpenRequest, SendRequest, QueryInfo, ReadFile, and finally, Close. For a description of the parameters, see OpenRequest.

SendRequest

$request->SendRequest([postdata])

Sends an HTTP request to the destination server. postdata contains any optional data to send immediately after the request header; this is generally used for POST or PUT requests. Your request object must contain the following content header for post data to be processed. You can add the header with AddHeader:

...
$request->AddHeader("Content-Type: application/x-www-form-urlencoded");
$request->SendRequest("key1=value1&key2=value2&key3=value3");