ch22_07.htm

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

  "password"  => "password",
  "path"      => "path",
  "extrainfo" => "extrainfo",
);</pre></blockquote><p>If you don't specify a flags parameter,
<tt class="literal">ICU_ESCAPE</tt> will be used by default; for the other
possible values of <em class="replaceable"><tt>flags</tt></em>, refer to the
Microsoft Win32 Internet Functions documentation.
</p></div>

<a name="INDEX-3251" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>DataReceiveTimeout</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;DataReceiveTimeout([<em class="replaceable">value</em>])
</pre><p><a name="INDEX-3251" />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.
</p></div>

<a name="INDEX-3252" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>DataSendTimeout</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;DataSendTimeout([<em class="replaceable">value</em>])
</pre><p><a name="INDEX-3252" />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.
</p></div>

<a name="INDEX-3253" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>Error</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;Error(  )
</pre><p><a name="INDEX-3253" />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:
</p><dl>
<dt><i><em class="emphasis">-1</em></i></dt>
<dd>
A "trivial" error has occurred in
the package. For example, you tried to use a method on the wrong type
of object.
</p>
</dd>


<dt><i><em class="emphasis">1-11,999</em></i></dt>
<dd>
A generic error has occurred, and the Win32::GetLastError error
message is returned.
</p>
</dd>


<dt><i><em class="emphasis">12,000 and higher</em></i></dt>
<dd>
An Internet error has occurred, and the extended Win32 Internet API
error message is returned.
</p>
</dd>

</dl></div>

<a name="INDEX-3254" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>FetchURL</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;FetchURL(<em class="replaceable">URL</em>)
</pre><p><a name="INDEX-3254" />Fetches the content of an
HTTP, FTP, or Gopher URL. Returns the contents of the file read (or
<tt class="literal">undef</tt> if there was an error and nothing was read).
</p></div>

<a name="INDEX-3255" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>FTP</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">inet</em>-&gt;FTP($<em class="replaceable">ftpobject</em>, <em class="replaceable">server</em>, <em class="replaceable">username</em>, <em class="replaceable">pwd</em>, [<em class="replaceable">port</em>, <em class="replaceable">pasv</em>, <em class="replaceable">context</em>])
$<em class="replaceable">inet</em>-&gt;FTP($<em class="replaceable">ftpobject</em>, $<em class="replaceable">hashref</em>)
</pre></td><td align="right" /></tr></table><p><p><a name="INDEX-3255" />Opens an FTP connection to
<em class="replaceable"><tt>server</tt></em>, logging in with the given username
and password. The new connection object is saved to
<em class="replaceable"><tt>ftpobject</tt></em>. The parameters and their values
are:
</p><dl>
<dt><i><em class="replaceable"><tt>server</tt></em></i></dt>
<dd>
The server to connect to.</p>
</dd>


<dt><i><em class="replaceable"><tt>username</tt></em></i></dt>
<dd>
The username used to log in to the server. Default is
<tt class="literal">anonymous</tt>.
</p>
</dd>


<dt><i><em class="replaceable"><tt>pwd</tt></em></i></dt>
<dd>
The password used to log in to the server. Default is none.</p>
</dd>


<dt><i><em class="replaceable"><tt>port</tt></em></i></dt>
<dd>
The port of the FTP service on the server. Default is
<tt class="literal">21</tt>.
</p>
</dd>


<dt><i><em class="replaceable"><tt>pasv</tt></em></i></dt>
<dd>
If it is a value other than <tt class="literal">0</tt>, use passive
transfer mode. Otherwise, it is taken from the parent Internet
connection object; you can set this value with the
<tt class="literal">Pasv</tt> method.
</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 info on asynchronous
operations.
</p>

<p>If you pass a hash reference, the following values are taken from the
hash:
</p>

<blockquote><pre class="code">%hash=(
  "server"   =&gt; "server",
  "username" =&gt; "username",
  "password" =&gt; "password",
  "port"     =&gt; port,
  "pasv"     =&gt; pasv,
  "context"  =&gt; context,
);</pre></blockquote>

<p>The <tt class="literal">FTP</tt> method returns <tt class="literal">undef</tt> if
the connection failed, a number otherwise. You can then call any of
the FTP functions as methods of the newly created FTP object.
</p>
</dd>

</dl></div>

<a name="INDEX-3256" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>GetResponse</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;GetResponse(  )
</pre><p><a name="INDEX-3256" />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.
</p></div>

<a name="INDEX-3257" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>GetStatusCallback</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;GetStatusCallback(<em class="replaceable">context</em>)
</pre><p><a name="INDEX-3257" />Returns information about
the progress of the asynchronous operation identified by context;
this information consists of two values: a status code (one of the
<tt class="literal">INTERNET_STATUS_*</tt> constants) and an additional
value depending on the status code. For example, if the status code
returned is <tt class="literal">INTERNET_STATUS_HANDLE_CREATED</tt>, the
second value will hold the handle just created. For more information
on these values, refer to the Microsoft Win32 Internet Functions
documentation.
</p></div>

<a name="INDEX-3258" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>HTTP</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">inet</em>-&gt;HTTP(<em class="replaceable">httpobject</em>, <em class="replaceable">server</em>, <em class="replaceable">username</em>, <em class="replaceable">password</em>, [<em class="replaceable">port</em>, <em class="replaceable">flags</em>, <em class="replaceable">context</em>])
$<em class="replaceable">inet</em>-&gt;HTTP($<em class="replaceable">httpobject</em>, $<em class="replaceable">hashref</em>)
</pre></td><td align="right" /></tr></table><p><p><a name="INDEX-3258" />Opens an HTTP connection to
<em class="replaceable"><tt>server</tt></em>, logging in with the given username
and password. The new connection object is saved as
<em class="replaceable"><tt>httpobject</tt></em>. The parameters and their
values are:
</p><dl>
<dt><i><em class="replaceable"><tt>server</tt></em></i></dt>
<dd>
The server to connect to.</p>
</dd>


<dt><i><em class="replaceable"><tt>username</tt></em></i></dt>
<dd>
The username used to log in to the server. Default is
<tt class="literal">anonymous</tt>.
</p>
</dd>


<dt><i><em class="replaceable"><tt>password</tt></em></i></dt>
<dd>
The password used to log in to the server. Default is none.</p>
</dd>


<dt><i><em class="replaceable"><tt>port</tt></em></i></dt>
<dd>
The port of the HTTP service on the server. Default is
<tt class="literal">80</tt>. 
</p>
</dd>


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


<dt><i><em class="replaceable"><tt>context</tt></em></i></dt>
<dd>
A number to identify this operation if it is asynchronous.</p>

<p>If you pass a hash reference, the following values are taken from the
hash:
</p>

<blockquote><pre class="code">%hash=(
  "server"   =&gt; "server",
  "username" =&gt; "username",
  "password" =&gt; "password",
  "port"     =&gt; port,
  "flags"    =&gt; flags,
  "context"  =&gt; context,
);</pre></blockquote>
<p>The <tt class="literal">HTTP</tt> method returns <tt class="literal">undef</tt>
if the connection failed, a number otherwise. You can then call any
of the HTTP functions as methods of the newly created
<em class="replaceable"><tt>httpobject</tt></em>.
</p>
</dd>

</dl></div>

<a name="INDEX-3259" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>OpenURL</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;OpenURL(<em class="replaceable">urlobject</em>, <em class="replaceable">URL</em>)
</pre><p><a name="INDEX-3259" />Opens a connection to an
HTTP, FTP, or Gopher URL. Returns <tt class="literal">undef</tt> on error,
or a number if the connection was successful. You can then retrieve
the URL content by applying the methods
<tt class="literal">QueryDataAvailable</tt> and <tt class="literal">ReadFile</tt>
on the newly created <em class="replaceable"><tt>urlobject</tt></em>. See also
<tt class="literal">FetchURL</tt>.
</p></div>

<a name="INDEX-3260" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>Password</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>