19.7 Win32::Internet (Perl in a Nutshell)

19.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();

19.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 host names 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:

19.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:

19.7.3 HTTP Functions

The methods described in this section are used to create and control an HTTP session. You 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: