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

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. Win32::Internet

22.7.1. General Internet Methods

22.7.2. FTP Functions

22.7.3. HTTP Functions