ch22_07.htm

by Randal L. Schwartz and Tom Phoenix ISBN 0-596-00132-0 Third Edition, published July 2001. (See

$<em class="replaceable">inet</em>-&gt;Password([<em class="replaceable">password</em>])
</pre><p><a name="INDEX-3260" />Reads or sets the password
used for an FTP or HTTP connection. If no password parameter is
specified, the current value is returned.
</p></div>

<a name="INDEX-3261" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>QueryDataAvailable</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">inet</em>-&gt;QueryDataAvailable(  )
</pre><p><a name="INDEX-3261" />Returns the number of bytes
of data available to be read immediately by a subsequent call to
<tt class="literal">ReadFile</tt> (or <tt class="literal">undef</tt> on error).
Can be applied to URL or HTTP request objects.
</p></div>

<a name="INDEX-3262" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>QueryOption</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">inet</em>-&gt;QueryOption(<em class="replaceable">option</em>)
</pre><p><a name="INDEX-3262" />Queries an Internet option.
For the possible values of <em class="replaceable"><tt>option</tt></em>, refer
to the Microsoft Win32 Internet Functions documentation.
</p></div>

<a name="INDEX-3263" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>ReadEntireFile</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">inet</em>-&gt;ReadEntireFile(  )
</pre><p><a name="INDEX-3263" />Reads all the data available
from an opened URL or HTTP request object. Returns what has been
read, or <tt class="literal">undef</tt> on error.
</p></div>

<a name="INDEX-3264" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>ReadFile</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">inet</em>-&gt;ReadFile(<em class="replaceable">bytes</em>)
</pre><p><a name="INDEX-3264" />Reads and returns the
specified number of bytes of data from an opened URL or HTTP request
object. Returns <tt class="literal">undef</tt> on error. Be careful to keep
<em class="replaceable"><tt>bytes</tt></em> to an acceptable value.
</p></div>

<a name="INDEX-3265" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>SetOption</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">inet</em>-&gt;SetOption(<em class="replaceable">option</em>, <em class="replaceable">value</em>)
</pre><p><a name="INDEX-3265" />Sets an Internet option. For
the possible values of <em class="replaceable"><tt>option</tt></em>, refer to
the Microsoft Win32 Internet Functions documentation.
</p></div>

<a name="INDEX-3266" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>SetStatusCallback</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">inet</em>-&gt;SetStatusCallback(  )
</pre><p><a name="INDEX-3266" />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:
</p><blockquote><pre class="code"># Use the INTERNET_FLAG_ASYNC when initializing
$params{'flags'}=INTERNET_FLAG_ASYNC;
$inet = new Win32::Internet(params);

# Initialize the callback routine
$inet-&gt;SetStatusCallback( );

# Specify the context parameter (the last 1 in this case)
$inet-&gt;HTTP($http, "www.yahoo.com", "anonymous", "dada\@divinf.it", 
            80, 0, 1);</pre></blockquote><p>At this point, control returns immediately to Perl, and
<tt class="literal">$inet-&gt;Error( )</tt> will return
<tt class="literal">997</tt>, which means an asynchronous I/O operation is
pending. Now, you can call:
</p><blockquote><pre class="code">$http-&gt;GetStatusCallback(1);</pre></blockquote><p>in a loop to verify what's happening; see also
<tt class="literal">GetStatusCallback</tt>.
</p></div>

<a name="INDEX-3267" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>TimeConvert</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">inet</em>-&gt;TimeConvert(<em class="replaceable">time</em>)
</pre><p><a name="INDEX-3267" />Takes an HTTP date/time
string and returns the date/time converted in the following array:
(<em class="replaceable"><tt>seconds</tt></em>,
<em class="replaceable"><tt>minutes</em>, <em class="replaceable">hours</tt></em>,
<em class="replaceable"><tt>day</em>, <em class="replaceable">month</tt></em>,
<em class="replaceable"><tt>year</tt></em>,
<em class="replaceable"><tt>day_of_week</tt></em>).
</p></div>

<a name="INDEX-3268" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>UserAgent</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">inet</em>-&gt;UserAgent([<em class="replaceable">name</em>])
</pre><p><a name="INDEX-3268" />Reads or sets the user agent
name used for HTTP requests. If no name is specified, the current
value is returned.
</p></div>

<a name="INDEX-3269" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>Username</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">inet</em>-&gt;Username([<em class="replaceable">name</em>])
</pre><p><a name="INDEX-3269" />Reads or sets the username
used for an FTP or HTTP connection. If no name parameter is
specified, the current value is returned.
</p></div>

<a name="INDEX-3270" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>Version</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">inet</em>-&gt;Version(  )
</pre><p><a name="INDEX-3270" />Returns the version numbers
for the Win32::Internet package and the
<em class="emphasis">WININET.DLL</em> version, as an array or string,
depending on the context. The string returned will contain
<em class="replaceable"><tt>package_version</em>/<em class="replaceable">DLL_version</tt></em>,
while the array will contain:
<em class="replaceable"><tt>package_version</tt></em><tt class="literal">,</tt>
<em class="replaceable"><tt>DLL_version</tt></em>. For example:
</p><blockquote><pre class="code">$version = $inet-&gt;Version( );
# Should return "0.06/4.70.1215"
@version = $inet-&gt;Version( );
# Should return ("0.06", "4.70.1215")</pre></blockquote></div>

</div>
<a name="perlnut2-CHP-22-SECT-7.2" /><div class="sect2">
<h3 class="sect2">22.7.2. FTP Functions</h3>

<p><a name="INDEX-3271" />The methods described in this section are
used to control FTP sessions. They apply to FTP session objects
created by the <tt class="literal">FTP</tt> method on an Internet
connection object. <tt class="literal">FTP</tt> creates an open FTP session
and assigns it to an object (<tt class="literal">$FTP</tt>):
</p>

<blockquote><pre class="code">use Win32::Internet;
$inet = new Win32::Internet( );
$inet-&gt;FTP($FTP, "hostname", "username", "password");</pre></blockquote>

<p>The following methods are used on FTP session objects.</p>



<a name="INDEX-3272" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>Ascii</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><table width="515" border="0" cellpadding="5"><tr><td align="left"><pre>
$<em class="replaceable">FTP</em>-&gt;Ascii(  )
$<em class="replaceable">FTP</em>-&gt;Asc(  )
</pre></td><td align="right" /></tr></table><p><p><a name="INDEX-3272" />Sets the ASCII transfer mode
for this FTP session. It will be applied to subsequent
<tt class="literal">Get</tt> functions.
</p></div>

<a name="INDEX-3273" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>Binary</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><table width="515" border="0" cellpadding="5"><tr><td align="left"><pre>
$<em class="replaceable">FTP</em>-&gt;Binary(  )
$<em class="replaceable">FTP</em>-&gt;Bin(  )
</pre></td><td align="right" /></tr></table><p><p><a name="INDEX-3273" />Sets the binary transfer
mode for this FTP session. It will be applied to subsequent
<tt class="literal">Get</tt> functions.
</p></div>

<a name="INDEX-3274" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>Cd</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><table width="515" border="0" cellpadding="5"><tr><td align="left"><pre>
$<em class="replaceable">FTP</em>-&gt;Cd(<em class="replaceable">path</em>)
$<em class="replaceable">FTP</em>-&gt;Cwd(<em class="replaceable">path</em>)
$<em class="replaceable"><tt>FTP</em>-&gt;Chdir(<em class="replaceable">path</tt></em>)
</pre></td><td align="right" /></tr></table><p><p><a name="INDEX-3274" />Changes the current
directory on the FTP remote host. Returns
<em class="replaceable"><tt>path</tt></em>, or <tt class="literal">undef</tt> on
error.
</p></div>

<a name="INDEX-3275" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>Delete</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><table width="515" border="0" cellpadding="5"><tr><td align="left"><pre>
$<em class="replaceable">FTP</em>-&gt;Delete(<em class="replaceable">file</em>)
$<em class="replaceable">FTP</em>-&gt;Del(<em class="replaceable">file</em>)
</pre></td><td align="right" /></tr></table><p><p><a name="INDEX-3275" />Deletes <em class="replaceable"><tt>file</tt></em>on the FTP remote host. Returns <tt class="literal">undef</tt> on error.
</p></div>

<a name="INDEX-3276" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>Get</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">FTP</em>-&gt;Get(<em class="replaceable">file</em>, [<em class="replaceable">local</em>, <em class="replaceable">overwrite</em>, <em class="replaceable">flags</em>, <em class="replaceable">context</em>])
</pre><p><a name="INDEX-3276" />Gets the remote FTP
<em class="replaceable"><tt>file</tt></em> and saves it locally in
<em class="replaceable"><tt>local</em>. If <em class="replaceable">local</tt></em>is not specified, it will be the same name as
<em class="replaceable"><tt>file</tt></em>. Returns <tt class="literal">undef</tt> on
error. The parameters and their values are:
</p><dl>
<dt><i><em class="replaceable"><tt>file</tt></em></i></dt>
<dd>
The name of the remote file on the FTP server.</p>
</dd>


<dt><i><em class="replaceable"><tt>local</tt></em></i></dt>
<dd>
The name of the local file to create.</p>
</dd>


<dt><i><em class="replaceable"><tt>overwrite</tt></em></i></dt>
<dd>
If <tt class="literal">0</tt>, overwrites <em class="replaceable"><tt>local</tt></em>if it exists. With any other value, the function fails if the local
file already exists. Default is <tt class="literal">0</tt>.
</p>
</dd>


<dt><i><em class="replaceable"><tt>flags</tt></em></i></dt>
<dd>
Additional flags affecting the behavior of the function. None by
default.
</p>
</dd>


<dt><i><em class="replaceable"><tt>context</tt></em></i></dt>
<dd>
A number to identify this operation if it is asynchronous. (See
<tt class="literal">SetStatusCallback</tt> and
<tt class="literal">GetStatusCallback</tt> for more information on
asynchronous operations.) None by default.
</p>
</dd>

</dl></div>

<a name="INDEX-3277" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>List</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><table width="515" border="0" cellpadding="5"><tr><td align="left"><pre>
$<em class="replaceable">FTP</em>-&gt;List([<em class="replaceable">pattern</em>, <em class="replaceable">listmode</em>])
$<em class="replaceable">FTP</em>-&gt;Ls([<em class="replaceable">pattern</em>, <em class="replaceable">listmode</em>])
$<em class="replaceable"><tt>FTP</em>-&gt;Dir([<em class="replaceable">pattern</em>, <em class="replaceable">listmode</tt></em>])
</pre></td><td align="right" /></tr></table><p><p><a name="INDEX-3277" />Returns a list containing the files
found in the current directory, matching the given
<em class="replaceable"><tt>pattern</tt></em>, if specified. The content of the
returned list depends on the <em class="replaceable"><tt>listmode</tt></em>parameter, which can have the following values:
</p><dl>
<dt><b><tt class="literal">1</tt> <em class="emphasis">(default)</em></b></dt>
<dd>
The list contains the names of the files found.</p>
</dd>


<dt><b><tt class="literal">2</tt></b></dt>
<dd>
The list contains seven values for each file:</p>

<ul>
<li><p>The filename</p></li>
<li><p>The DOS short filename, a.k.a. 8.3</p></li>
<li><p>The size</p></li>
<li><p>The attributes</p></li>
<li><p>The creation time</p></li>
<li><p>The last access time</p></li>
<li><p>The last modified time</p></li>
</ul>

</dd>


<dt><b><tt class="literal">3</tt></b></dt>
<dd>
The list contains a reference to a hash for each found file. Each
hash contains the following key/value pairs:
</p>


<blockquote><pre class="code">name =&gt; <em class="replaceable"><tt>filename</tt></em>
altname =&gt; <em class="replaceable"><tt>DOS short filename, a.k.a. 8.3</tt></em>