[Chapter 19] 19.7 Win32::Internet
Author: Ellen Siever, Stephen Spainhour & Nathan Patwardhan
Date: 1999-07-02T01:59:24Z

#

| Chapter 19 Win32 Modules and Extensions |

## 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:

- CanonicalizeURL
- Close
- CombineURL
- ConnectBackoff
- ConnectionRetries
- ConnectTimeout
- ControlReceiveTimeout
- ControlSendTimeout
- CrackURL
- CreateURL
- DataReceiveTimeout
- DataSendTimeout
- Error
- FetchURL
- FTP
- GetResponse
- GetStatusCallback
- HTTP
- OpenURL
- Password
- QueryDataAvailable
- QueryOption
- ReadEntireFile
- ReadFile
- SetOption
- SetStatusCallback
- TimeConvert
- UserAgent
- Username
- Version

### 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:

- Ascii
- Binary
- Cd
- Delete
- Get
- List
- Mkdir
- Mode
- Pasv
- Put
- Pwd
- Rename
- Rmdir

### 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:

- AddHeader
- OpenRequest
- QueryInfo
- Request
- SendRequest

19.6 Win32::FileSecurity |  | 19.8 Win32::IPC