Win32::Internet Reference

## Reference Manual

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 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@perl.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@perl.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\@perl.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@perl.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:

  Error number | Meaning
  -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:

  Parameter | Meaning | Default
  server | The server to connect to. | none
  username | The username used to login to the server. | `anonymous`
  password | The password used to login to the server. | none
  port | The port of the FTP service on the server. | `21`
  pasv | If it is a value other than 0, use passive transfer mode. | 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. | 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\@perl.it");
       # and then for example...
       $FTP->Cd("/ntperl/perl5.001m/CurrentBuild");

       $params{"server"} = "ftp.activeware.com";
       $params{"password"} = "dada\@perl.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\@perl.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:

  Parameter | Meaning | Default
  server | The server to connect to. | none
  username | The username used to login to the server. | `anonymous`
  password | The password used to login to the server. | none
  port | The port of the HTTP service on the server. | `80`
  flags | Additional flags affecting the behavior of the function. | none
  context | A number to identify this operation if it is asynchronous. See SetStatusCallback and GetStatusCallback for more info on asynchronous operations. | 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\@perl.it");
       # and then for example...
       ($statuscode, $headers, $file) = $HTTP->Request("/gifs/camel.gif");

       $params{"server"} = "www.activeware.com";
       $params{"password"} = "dada\@perl.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:

  Parameter | Meaning | Default
  useragent | The user agent passed to HTTP requests. See OpenRequest. | `Perl-Win32::Internet/version`
  opentype | How to access to the Internet (eg. directly or using a proxy). | `INTERNET_OPEN_TYPE_DIRECT`
  proxy | Name of the proxy server (or servers) to use. | none
  proxybypass | Optional list of host names or IP addresses, or both, that are known locally. | none
  flags | Additional flags affecting the behavior of the function. | 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.
  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 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 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\@perl.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:

  Parameter | Meaning | Default
  remote | The name of the remote file on the FTP server. | none
  local | The name of the local file to create. | `remote`
  overwrite | If 0, overwrites `local` if it exists; with any other value, the function fails if the local file already exists. | `0`
  flags | Additional flags affecting the behavior of the function. | none
  context | A number to identify this operation if it is asynchronous. See SetStatusCallback and GetStatusCallback for more info on asynchronous operations. | 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, 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\@perl.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:

  Parameter | Meaning | Default
  path | The object to request. This is generally a file name, an executable module, etc. | `/`
  method | The method to use; can actually be GET, POST, HEAD or PUT. | `GET`
  version | The HTTP version. | `HTTP/1.0`
  referer | The URL of the document from which the URL in the request was obtained. | none
  accept | The content types accepted. They must be separated by a "\0" (ASCII zero). | `text/* image/gif image/jpeg`
  flags | Additional flags affecting the behavior of the function. | none
  context | A number to identify this operation if it is asynchronous. See SetStatusCallback and GetStatusCallback for more info on asynchronous operations. | 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.
  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");

10 Feb 1997, Aldo Calpini <dada@perl.it>