home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _a30df6acf5e786f88f71632a26ce3a48 < prev    next >
Text File  |  2000-03-23  |  64KB  |  1,446 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>Win32::Internet - Access to WININET.DLL functions</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> Win32::Internet - Access to WININET.DLL functions</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#introduction">INTRODUCTION</A></LI>
  24.     <LI><A HREF="#reference">REFERENCE</A></LI>
  25.     <UL>
  26.  
  27.         <LI><A HREF="#general internet functions">General Internet Functions</A></LI>
  28.         <LI><A HREF="#ftp functions">FTP Functions</A></LI>
  29.         <LI><A HREF="#http functions">HTTP Functions</A></LI>
  30.     </UL>
  31.  
  32.     <LI><A HREF="#appendix">APPENDIX</A></LI>
  33.     <UL>
  34.  
  35.         <LI><A HREF="#microsoft win32 internet functions">Microsoft Win32 Internet Functions</A></LI>
  36.         <LI><A HREF="#functions table">Functions Table</A></LI>
  37.         <LI><A HREF="#constants">Constants</A></LI>
  38.     </UL>
  39.  
  40.     <LI><A HREF="#version history">VERSION HISTORY</A></LI>
  41.     <LI><A HREF="#author">AUTHOR</A></LI>
  42.     <LI><A HREF="#credits">CREDITS</A></LI>
  43.     <LI><A HREF="#disclaimer">DISCLAIMER</A></LI>
  44. </UL>
  45. <!-- INDEX END -->
  46.  
  47. <HR>
  48. <P>
  49. <H1><A NAME="name">NAME</A></H1>
  50. <P>Win32::Internet - Access to WININET.DLL functions</P>
  51. <P>
  52. <HR>
  53. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  54. <UL>
  55. <LI>Windows</LI>
  56. </UL>
  57. <HR>
  58. <H1><A NAME="introduction">INTRODUCTION</A></H1>
  59. <P>This extension to Perl implements the Win32 Internet APIs (found in
  60. <EM>WININET.DLL</EM>). They give a complete support for HTTP, FTP and GOPHER
  61. connections.</P>
  62. <P>See the <A HREF="#version history">Version History</A> and the <A HREF="#functions table">Functions Table</A> for a list
  63. of the currently supported features. You should also get a copy of the
  64. <A HREF="#microsoft win32 internet functions">Microsoft Win32 Internet Functions</A> documentation.</P>
  65. <P>
  66. <HR>
  67. <H1><A NAME="reference">REFERENCE</A></H1>
  68. <P>To use this module, first add the following line at the beginning of
  69. your script:</P>
  70. <PRE>
  71.     use Win32::Internet;</PRE>
  72. <P>Then you have to open an Internet connection with this command:</P>
  73. <PRE>
  74.     $Connection = new Win32::Internet();</PRE>
  75. <P>This is required to use any of the function of this module.  It will
  76. create an Internet object in Perl on which you can act upon with the
  77. <A HREF="#general internet functions">General Internet Functions</A> explained later.</P>
  78. <P>The objects available are:</P>
  79. <UL>
  80. <LI>
  81. Internet connections (the main object, see <CODE>new</CODE>)
  82. <P></P>
  83. <LI>
  84. URLs (see <CODE>OpenURL</CODE>)
  85. <P></P>
  86. <LI>
  87. FTP sessions (see <CODE>FTP</CODE>)
  88. <P></P>
  89. <LI>
  90. HTTP sessions (see <CODE>HTTP</CODE>)
  91. <P></P>
  92. <LI>
  93. HTTP requests (see <CODE>OpenRequest</CODE>)
  94. <P></P></UL>
  95. <P>As in the good Perl tradition, there are in this extension different
  96. ways to do the same thing; there are, in fact, different levels of
  97. implementation of the Win32 Internet Functions.  Some routines use
  98. several Win32 API functions to perform a complex task in a single
  99. call; they are simpler to use, but of course less powerful.</P>
  100. <P>There are then other functions that implement nothing more and nothing
  101. less than the corresponding API function, so you can use all of their
  102. power, but with some additional programming steps.</P>
  103. <P>To make an example, there is a function called <CODE>FetchURL</CODE> that you
  104. can use to fetch the content of any HTTP, FTP or GOPHER URL with this
  105. simple commands:</P>
  106. <PRE>
  107.     $INET = new Win32::Internet();
  108.     $file = $INET->FetchURL("<A HREF="http://www.yahoo.com"">http://www.yahoo.com"</A>;);</PRE>
  109. <P>You can have the same result (and this is actually what is done by
  110. <CODE>FetchURL</CODE>) this way:</P>
  111. <PRE>
  112.     $INET = new Win32::Internet();
  113.     $URL = $INET->OpenURL("<A HREF="http://www.yahoo.com"">http://www.yahoo.com"</A>;);
  114.     $file = $URL->ReadFile();
  115.     $URL->Close();</PRE>
  116. <P>Or, you can open a complete HTTP session:</P>
  117. <PRE>
  118.     $INET = new Win32::Internet();
  119.     $HTTP = $INET->HTTP("www.yahoo.com", "anonymous", "dada@divinf.it");
  120.     ($statuscode, $headers, $file) = $HTTP->Request("/");
  121.     $HTTP->Close();</PRE>
  122. <P>Finally, you can choose to manage even the HTTP request:</P>
  123. <PRE>
  124.     $INET = new Win32::Internet();
  125.     $HTTP = $INET->HTTP("www.yahoo.com", "anonymous", "dada@divinf.it");
  126.     $HTTP->OpenRequest($REQ, "/");
  127.     $REQ->AddHeader("If-Modified-Since: Saturday, 16-Nov-96 15:58:50 GMT");
  128.     $REQ->SendRequest();
  129.     $statuscode = $REQ->QueryInfo("",HTTP_QUERY_STATUS_CODE);
  130.     $lastmodified = $REQ->QueryInfo("Last-Modified");
  131.     $file = $REQ->ReadEntireFile();
  132.     $REQ->Close();
  133.     $HTTP->Close();</PRE>
  134. <P>To open and control a complete FTP session, type:</P>
  135. <PRE>
  136.     $Connection->FTP($Session, "<A HREF="ftp://ftp.activeware.com"">ftp://ftp.activeware.com"</A>;, "anonymous", "dada\@divinf.it");</PRE>
  137. <P>This will create an FTP object in Perl to which you can apply the <A HREF="#ftp functions">FTP functions</A> provided by the package:</P>
  138. <PRE>
  139.     $Session->Cd("/ntperl/perl5.001m/CurrentBuild");
  140.     $Session->Ascii();
  141.     $Session->Get("110-i86.zip");
  142.     $Session->Close();</PRE>
  143. <P>For a more complete example, see the TEST.PL file that comes with the
  144. package.</P>
  145. <P>
  146. <H2><A NAME="general internet functions">General Internet Functions</A></H2>
  147. <P><STRONG>General Note</STRONG></P>
  148. <P>All methods assume that you have the line:</P>
  149. <PRE>
  150.     use Win32::Internet;</PRE>
  151. <P>somewhere before the method calls, and that you have an Internet
  152. object called $INET which was created using this call:</P>
  153. <PRE>
  154.     $INET = new Win32::Internet();</PRE>
  155. <P>See <CODE>new</CODE> for more information.</P>
  156. <P><STRONG>Methods</STRONG></P>
  157. <DL>
  158. <DT><STRONG><A NAME="item_CanonicalizeURL_URL%2C_%5Bflags%5D">CanonicalizeURL URL, [flags]</A></STRONG><BR>
  159. <DD>
  160. Converts a URL to a canonical format, which includes converting unsafe
  161. characters to escape sequences.  Returns the canonicalized URL or
  162. <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> on errors.  For the possible values of <EM>flags</EM>, refer to the
  163. <A HREF="#microsoft win32 internet functions">Microsoft Win32 Internet Functions</A> document.  See also
  164. <CODE>CombineURL</CODE> and <CODE>OpenURL</CODE>.
  165. <P>Example:</P>
  166. <PRE>
  167.     $cURL = $INET->CanonicalizeURL($URL);
  168.     $URL = $INET->CanonicalizeURL($cURL, ICU_DECODE);</PRE>
  169. <P></P>
  170. <DT><STRONG><A NAME="item_Close">Close</A></STRONG><BR>
  171. <DD>
  172. <DT><STRONG><A NAME="item_Close_object">Close object</A></STRONG><BR>
  173. <DD>
  174. Closes an Internet connection.  This can be applied to any
  175. Win32::Internet object (Internet connections, URLs, FTP sessions,
  176. etc.).  Note that it is not ``strictly'' required to close the
  177. connections you create, since the Win32::Internet objects are
  178. automatically closed when the program ends (or when you elsehow
  179. destroy such an object).
  180. <P>Example:</P>
  181. <PRE>
  182.     $INET->Close();
  183.     $FTP->Close();
  184.     $INET->Close($FTP); # same as above...</PRE>
  185. <P></P>
  186. <DT><STRONG><A NAME="item_CombineURL_baseURL%2C_relativeURL%2C_%5Bflags%5D">CombineURL baseURL, relativeURL, [flags]</A></STRONG><BR>
  187. <DD>
  188. Combines a base and relative URL into a single URL.  Returns the
  189. (canonicalized) combined URL or <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> on errors.  For the possible
  190. values of <EM>flags</EM>, refer to the <A HREF="#microsoft win32 internet functions">Microsoft Win32 Internet Functions</A> document.  See also <CODE>CombineURL</CODE> and <CODE>OpenURL</CODE>.
  191. <P>Example:</P>
  192. <PRE>
  193.     $URL = $INET->CombineURL("<A HREF="http://www.divinf.it/dada/perl/internet"">http://www.divinf.it/dada/perl/internet"</A>;, "..");</PRE>
  194. <P></P>
  195. <DT><STRONG><A NAME="item_ConnectBackoff_%5Bvalue%5D">ConnectBackoff [value]</A></STRONG><BR>
  196. <DD>
  197. Reads or sets the delay value, in milliseconds, to wait between
  198. connection retries.  If no <EM>value</EM> parameter is specified, the
  199. current value is returned; otherwise, the delay between retries is set
  200. to <EM>value</EM>.  See also <CODE>ConnectTimeout</CODE>, <CODE>ConnectRetries</CODE>,
  201. <CODE>QueryOption</CODE> and <CODE>SetOption</CODE>.
  202. <P>Example:</P>
  203. <PRE>
  204.     $HTTP->ConnectBackoff(2000);
  205.     $backoff = $HTTP->ConnectBackoff();</PRE>
  206. <P></P>
  207. <DT><STRONG><A NAME="item_ConnectRetries_%5Bvalue%5D">ConnectRetries [value]</A></STRONG><BR>
  208. <DD>
  209. Reads or sets the number of times a connection is retried before
  210. considering it failed.  If no <EM>value</EM> parameter is specified, the
  211. current value is returned; otherwise, the number of retries is set to
  212. <EM>value</EM>.  The default value for <CODE>ConnectRetries</CODE> is 5.  See also
  213. <CODE>ConnectBackoff</CODE>, <CODE>ConnectTimeout</CODE>, <CODE>QueryOption</CODE> and <CODE>SetOption</CODE>.
  214. <P>Example:</P>
  215. <PRE>
  216.     $HTTP->ConnectRetries(20);
  217.     $retries = $HTTP->ConnectRetries();</PRE>
  218. <P></P>
  219. <DT><STRONG><A NAME="item_ConnectTimeout_%5Bvalue%5D">ConnectTimeout [value]</A></STRONG><BR>
  220. <DD>
  221. Reads or sets the timeout value (in milliseconds) before a connection
  222. is considered failed.  If no <EM>value</EM> parameter is specified, the
  223. current value is returned; otherwise, the timeout is set to <EM>value</EM>.
  224. The default value for <CODE>ConnectTimeout</CODE> is infinite.  See also
  225. <CODE>ConnectBackoff</CODE>, <CODE>ConnectRetries</CODE>, <CODE>QueryOption</CODE> and <CODE>SetOption</CODE>.
  226. <P>Example:</P>
  227. <PRE>
  228.     $HTTP->ConnectTimeout(10000);
  229.     $timeout = $HTTP->ConnectTimeout();</PRE>
  230. <P></P>
  231. <DT><STRONG><A NAME="item_ControlReceiveTimeout_%5Bvalue%5D">ControlReceiveTimeout [value]</A></STRONG><BR>
  232. <DD>
  233. Reads or sets the timeout value (in milliseconds) to use for non-data
  234. (control) receive requests before they are canceled.  Currently, this
  235. value has meaning only for <CODE>FTP</CODE> sessions.  If no <EM>value</EM> parameter
  236. is specified, the current value is returned; otherwise, the timeout is
  237. set to <EM>value</EM>.  The default value for <CODE>ControlReceiveTimeout</CODE> is
  238. infinite.  See also <CODE>ControlSendTimeout</CODE>, <CODE>QueryOption</CODE> and
  239. <CODE>SetOption</CODE>.
  240. <P>Example:</P>
  241. <PRE>
  242.     $HTTP->ControlReceiveTimeout(10000);
  243.     $timeout = $HTTP->ControlReceiveTimeout();</PRE>
  244. <P></P>
  245. <DT><STRONG><A NAME="item_ControlSendTimeout_%5Bvalue%5D">ControlSendTimeout [value]</A></STRONG><BR>
  246. <DD>
  247. Reads or sets the timeout value (in milliseconds) to use for non-data
  248. (control) send requests before they are canceled.  Currently, this
  249. value has meaning only for <CODE>FTP</CODE> sessions.  If no <EM>value</EM> parameter
  250. is specified, the current value is returned; otherwise, the timeout is
  251. set to <EM>value</EM>.  The default value for <CODE>ControlSendTimeout</CODE> is
  252. infinite.  See also <CODE>ControlReceiveTimeout</CODE>, <CODE>QueryOption</CODE> and
  253. <CODE>SetOption</CODE>.
  254. <P>Example:</P>
  255. <PRE>
  256.     $HTTP->ControlSendTimeout(10000);
  257.     $timeout = $HTTP->ControlSendTimeout();</PRE>
  258. <P></P>
  259. <DT><STRONG><A NAME="item_CrackURL_URL%2C_%5Bflags%5D">CrackURL URL, [flags]</A></STRONG><BR>
  260. <DD>
  261. Splits an URL into its component parts and returns them in an array.
  262. Returns <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> on errors, otherwise the array will contain the
  263. following values: <EM>scheme, host, port, username, password, path,
  264. extrainfo</EM>.
  265. <P>For example, the URL ``http://www.divinf.it/index.html#top'' can be
  266. splitted in:</P>
  267. <PRE>
  268.     http, www.divinf.it, 80, anonymous, dada@divinf.it, /index.html, #top</PRE>
  269. <P>If you don't specify a <EM>flags</EM> parameter, ICU_ESCAPE will be used by
  270. default; for the possible values of <EM>flags</EM> refer to the <A HREF="#microsoft win32 internet functions">Microsoft Win32 Internet Functions</A> documentation.  See also <CODE>CreateURL</CODE>.</P>
  271. <P>Example:</P>
  272. <PRE>
  273.     @parts=$INET->CrackURL("<A HREF="http://www.activeware.com"">http://www.activeware.com"</A>;);
  274.     ($scheme, $host, $port, $user, $pass, $path, $extra) =
  275.          $INET->CrackURL("<A HREF="http://www.divinf.it:80/perl-win32/index.sht#feedback"">http://www.divinf.it:80/perl-win32/index.sht#feedback"</A>;);</PRE>
  276. <P></P>
  277. <DT><STRONG><A NAME="item_CreateURL_scheme%2C_hostname%2C_port%2C_username%2">CreateURL scheme, hostname, port, username, password, path, extrainfo, [flags]</A></STRONG><BR>
  278. <DD>
  279. <DT><STRONG><A NAME="item_CreateURL_hashref%2C_%5Bflags%5D">CreateURL hashref, [flags]</A></STRONG><BR>
  280. <DD>
  281. Creates a URL from its component parts.  Returns <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> on errors,
  282. otherwise the created URL.
  283. <P>If you pass <EM>hashref</EM> (a reference to an hash array), the following
  284. values are taken from the array:</P>
  285. <PRE>
  286.     %hash=(
  287.       "scheme"    => "scheme",
  288.       "hostname"  => "hostname",
  289.       "port"      => port,
  290.       "username"  => "username",
  291.       "password"  => "password",
  292.       "path"      => "path",
  293.       "extrainfo" => "extrainfo",
  294.     );</PRE>
  295. <P>If you don't specify a <EM>flags</EM> parameter, ICU_ESCAPE will be used by
  296. default; for the other possible values of <EM>flags</EM> refer to the
  297. <A HREF="#microsoft win32 internet functions">Microsoft Win32 Internet Functions</A> documentation.  See also
  298. <CODE>CrackURL</CODE>.</P>
  299. <P>Example:</P>
  300. <PRE>
  301.     $URL=$I->CreateURL("http", "www.divinf.it", 80, "", "", "/perl-win32/index.sht", "#feedback");
  302.     $URL=$I->CreateURL(\%params);</PRE>
  303. <P></P>
  304. <DT><STRONG><A NAME="item_DataReceiveTimeout_%5Bvalue%5D">DataReceiveTimeout [value]</A></STRONG><BR>
  305. <DD>
  306. Reads or sets the timeout value (in milliseconds) to use for data
  307. receive requests before they are canceled.  If no <EM>value</EM> parameter
  308. is specified, the current value is returned; otherwise, the timeout is
  309. set to <EM>value</EM>.  The default value for DataReceiveTimeout is
  310. infinite.  See also <CODE>DataSendTimeout</CODE>, <CODE>QueryOption</CODE> and
  311. <CODE>SetOption</CODE>.
  312. <P>Example:</P>
  313. <PRE>
  314.     $HTTP->DataReceiveTimeout(10000);
  315.     $timeout = $HTTP->DataReceiveTimeout();</PRE>
  316. <P></P>
  317. <DT><STRONG><A NAME="item_DataSendTimeout_%5Bvalue%5D">DataSendTimeout [value]</A></STRONG><BR>
  318. <DD>
  319. Reads or sets the timeout value (in milliseconds) to use for data send
  320. requests before they are canceled.  If no <EM>value</EM> parameter is
  321. specified, the current value is returned; otherwise, the timeout is
  322. set to <EM>value</EM>.  The default value for DataSendTimeout is infinite.
  323. See also <CODE>DataReceiveTimeout</CODE>, <CODE>QueryOption</CODE> and <CODE>SetOption</CODE>.
  324. <P>Example:</P>
  325. <PRE>
  326.     $HTTP->DataSendTimeout(10000);
  327.     $timeout = $HTTP->DataSendTimeout();</PRE>
  328. <P></P>
  329. <DT><STRONG><A NAME="item_Error">Error</A></STRONG><BR>
  330. <DD>
  331. Returns the last recorded error in the form of an array or string
  332. (depending upon the context) containing the error number and an error
  333. description.  Can be applied on any Win32::Internet object (FTP
  334. sessions, etc.).  There are 3 types of error you can encounter; they
  335. are recognizable by the error number returned:
  336. <UL>
  337. <LI><STRONG><A NAME="item_%2D1">-1</A></STRONG><BR>
  338.  
  339. A ``trivial'' error has occurred in the package.  For example, you tried
  340. to use a method on the wrong type of object.
  341. <P></P>
  342. <LI><STRONG><A NAME="item_1_%2E%2E_11999">1 .. 11999</A></STRONG><BR>
  343.  
  344. A generic error has occurred and the Win32::GetLastError error message
  345. is returned.
  346. <P></P>
  347. <LI><STRONG><A NAME="item_12000_and_higher">12000 and higher</A></STRONG><BR>
  348.  
  349. An Internet error has occurred; the extended Win32 Internet API error
  350. message is returned.
  351. <P></P></UL>
  352. <P>See also <A HREF="#item_GetResponse"><CODE>GetResponse</CODE></A>.</P>
  353. <P>Example:</P>
  354. <PRE>
  355.     die $INET->Error(), qq(\n);
  356.     ($ErrNum, $ErrText) = $INET->Error();</PRE>
  357. <DT><STRONG><A NAME="item_FetchURL_URL">FetchURL URL</A></STRONG><BR>
  358. <DD>
  359. Fetch the content of an HTTP, FTP or GOPHER URL.  Returns the content
  360. of the file read (or <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> if there was an error and nothing was
  361. read).  See also <CODE>OpenURL</CODE> and <CODE>ReadFile</CODE>.
  362. <P>Example:</P>
  363. <PRE>
  364.     $file = $INET->FetchURL("<A HREF="http://www.yahoo.com/"">http://www.yahoo.com/"</A>;);
  365.     $file = $INET->FetchURL("<A HREF="ftp://www.activeware.com/contrib/internet.zip"">ftp://www.activeware.com/contrib/internet.zip"</A>;);</PRE>
  366. <P></P>
  367. <DT><STRONG><A NAME="item_FTP_ftpobject%2C_server%2C_username%2C_password%2C">FTP ftpobject, server, username, password, [port, pasv, context]</A></STRONG><BR>
  368. <DD>
  369. <DT><STRONG><A NAME="item_FTP_ftpobject%2C_hashref">FTP ftpobject, hashref</A></STRONG><BR>
  370. <DD>
  371. Opens an FTP connection to server logging in with the given
  372. <EM>username</EM> and <EM>password</EM>.
  373. <P>The parameters and their values are:</P>
  374. <UL>
  375. <LI><STRONG><A NAME="item_server">server</A></STRONG><BR>
  376.  
  377. The server to connect to.  Default: <EM>none</EM>.
  378. <P></P>
  379. <LI><STRONG><A NAME="item_username">username</A></STRONG><BR>
  380.  
  381. The username used to login to the server.  Default: anonymous.
  382. <P></P>
  383. <LI><STRONG><A NAME="item_password">password</A></STRONG><BR>
  384.  
  385. The password used to login to the server.  Default: <EM>none</EM>.
  386. <P></P>
  387. <LI><STRONG><A NAME="item_port">port</A></STRONG><BR>
  388.  
  389. The port of the FTP service on the server.  Default: 21.
  390. <P></P>
  391. <LI><STRONG><A NAME="item_pasv">pasv</A></STRONG><BR>
  392.  
  393. If it is a value other than 0, use passive transfer mode.  Default is
  394. taken from the parent Internet connection object; you can set this
  395. value with the <CODE>Pasv</CODE> method.
  396. <P></P>
  397. <LI><STRONG><A NAME="item_context">context</A></STRONG><BR>
  398.  
  399. A number to identify this operation if it is asynchronous.  See
  400. <A HREF="#item_SetStatusCallback"><CODE>SetStatusCallback</CODE></A> and <CODE>GetStatusCallback</CODE> for more info on
  401. asynchronous operations.  Default: <EM>none</EM>.
  402. <P></P></UL>
  403. <P>If you pass <EM>hashref</EM> (a reference to an hash array), the following
  404. values are taken from the array:</P>
  405. <PRE>
  406.     %hash=(
  407.       "server"   => "server",
  408.       "username" => "username",
  409.       "password" => "password",
  410.       "port"     => port,
  411.       "pasv"     => pasv,
  412.       "context"  => context,
  413.     );</PRE>
  414. <P>This method returns <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> if the connection failed, a number
  415. otherwise.  You can then call any of the <A HREF="#ftp functions">FTP functions</A> as methods
  416. of the newly created <EM>ftpobject</EM>.</P>
  417. <P>Example:</P>
  418. <PRE>
  419.     $result = $INET->FTP($FTP, "ftp.activeware.com", "anonymous", "dada\@divinf.it");
  420.     # and then for example...
  421.     $FTP->Cd("/ntperl/perl5.001m/CurrentBuild");</PRE>
  422. <PRE>
  423.     $params{"server"} = "ftp.activeware.com";
  424.     $params{"password"} = "dada\@divinf.it";
  425.     $params{"pasv"} = 0;
  426.     $result = $INET->FTP($FTP,\%params);</PRE>
  427. <DT><STRONG><A NAME="item_GetResponse">GetResponse</A></STRONG><BR>
  428. <DD>
  429. Returns the text sent by a remote server in response to the last
  430. function executed.  It applies on any Win32::Internet object,
  431. particularly of course on <A HREF="#ftp functions">FTP sessions</A>.  See also
  432. the <A HREF="#item_Error"><CODE>Error</CODE></A> function.
  433. <P>Example:</P>
  434. <PRE>
  435.     print $INET->GetResponse();
  436.     $INET->FTP($FTP, "ftp.activeware.com", "anonymous", "dada\@divinf.it");
  437.     print $FTP->GetResponse();</PRE>
  438. <P></P>
  439. <DT><STRONG><A NAME="item_GetStatusCallback_context">GetStatusCallback context</A></STRONG><BR>
  440. <DD>
  441. Returns information about the progress of the asynchronous operation
  442. identified by <EM>context</EM>; those informations consist of two values: a
  443. status code (one of the INTERNET_STATUS_* <A HREF="#constants">Constants</A>) and an
  444. additional value depending on the status code; for example, if the
  445. status code returned is INTERNET_STATUS_HANDLE_CREATED, the second
  446. value will hold the handle just created.  For more informations on
  447. those values, please refer to the <A HREF="#microsoft win32 internet functions">Microsoft Win32 Internet Functions</A> documentation.  See also <A HREF="#item_SetStatusCallback"><CODE>SetStatusCallback</CODE></A>.
  448. <P>Example:</P>
  449. <PRE>
  450.     ($status, $info) = $INET->GetStatusCallback(1);</PRE>
  451. <P></P>
  452. <DT><STRONG><A NAME="item_HTTP_httpobject%2C_server%2C_username%2C_password%">HTTP httpobject, server, username, password, [port, flags, context]</A></STRONG><BR>
  453. <DD>
  454. <DT><STRONG><A NAME="item_HTTP_httpobject%2C_hashref">HTTP httpobject, hashref</A></STRONG><BR>
  455. <DD>
  456. Opens an HTTP connection to <EM>server</EM> logging in with the given
  457. <EM>username</EM> and <EM>password</EM>.
  458. <P>The parameters and their values are:</P>
  459. <UL>
  460. <LI><STRONG>server</STRONG><BR>
  461.  
  462. The server to connect to.  Default: <EM>none</EM>.
  463. <P></P>
  464. <LI><STRONG>username</STRONG><BR>
  465.  
  466. The username used to login to the server.  Default: anonymous.
  467. <P></P>
  468. <LI><STRONG>password</STRONG><BR>
  469.  
  470. The password used to login to the server.  Default: <EM>none</EM>.
  471. <P></P>
  472. <LI><STRONG>port</STRONG><BR>
  473.  
  474. The port of the HTTP service on the server.  Default: 80.
  475. <P></P>
  476. <LI><STRONG><A NAME="item_flags">flags</A></STRONG><BR>
  477.  
  478. Additional flags affecting the behavior of the function.  Default:
  479. <EM>none</EM>.
  480. <P></P>
  481. <LI><STRONG>context</STRONG><BR>
  482.  
  483. A number to identify this operation if it is asynchronous.  See
  484. <A HREF="#item_SetStatusCallback"><CODE>SetStatusCallback</CODE></A> and <CODE>GetStatusCallback</CODE> for more info on
  485. asynchronous operations.  Default: <EM>none</EM>.
  486. <P></P></UL>
  487. <P>Refer to the <A HREF="#microsoft win32 internet functions">Microsoft Win32 Internet Functions</A> documentation for
  488. more details on those parameters.</P>
  489. <P>If you pass <EM>hashref</EM> (a reference to an hash array), the following
  490. values are taken from the array:</P>
  491. <PRE>
  492.     %hash=(
  493.       "server"   => "server",
  494.       "username" => "username",
  495.       "password" => "password",
  496.       "port"     => port,
  497.       "flags"    => flags,
  498.       "context"  => context,
  499.     );</PRE>
  500. <P>This method returns <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> if the connection failed, a number
  501. otherwise.  You can then call any of the <A HREF="#http functions">HTTP functions</A> as
  502. methods of the newly created <EM>httpobject</EM>.</P>
  503. <P>Example:</P>
  504. <PRE>
  505.     $result = $INET->HTTP($HTTP,"www.activeware.com","anonymous","dada\@divinf.it");
  506.     # and then for example...
  507.     ($statuscode, $headers, $file) = $HTTP->Request("/gifs/camel.gif");</PRE>
  508. <PRE>
  509.     $params{"server"} = "www.activeware.com";
  510.     $params{"password"} = "dada\@divinf.it";
  511.     $params{"flags"} = INTERNET_FLAG_RELOAD;
  512.     $result = $INET->HTTP($HTTP,\%params);</PRE>
  513. <DT><STRONG><A NAME="item_new_Win32%3A%3AInternet_%5Buseragent%2C_opentype%2">new Win32::Internet [useragent, opentype, proxy, proxybypass, flags]</A></STRONG><BR>
  514. <DD>
  515. <DT><STRONG><A NAME="item_new_Win32%3A%3AInternet_%5Bhashref%5D">new Win32::Internet [hashref]</A></STRONG><BR>
  516. <DD>
  517. Creates a new Internet object and initializes the use of the Internet
  518. functions; this is required before any of the functions of this
  519. package can be used.  Returns <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> if the connection fails, a number
  520. otherwise.  The parameters and their values are:
  521. <UL>
  522. <LI><STRONG><A NAME="item_useragent">useragent</A></STRONG><BR>
  523.  
  524. The user agent passed to HTTP requests.  See <CODE>OpenRequest</CODE>.  Default:
  525. Perl-Win32::Internet/<EM>version</EM>.
  526. <P></P>
  527. <LI><STRONG><A NAME="item_opentype">opentype</A></STRONG><BR>
  528.  
  529. How to access to the Internet (eg. directly or using a proxy).
  530. Default: INTERNET_OPEN_TYPE_DIRECT.
  531. <P></P>
  532. <LI><STRONG><A NAME="item_proxy">proxy</A></STRONG><BR>
  533.  
  534. Name of the proxy server (or servers) to use.  Default: <EM>none</EM>.
  535. <P></P>
  536. <LI><STRONG><A NAME="item_proxybypass">proxybypass</A></STRONG><BR>
  537.  
  538. Optional list of host names or IP addresses, or both, that are known
  539. locally.  Default: <EM>none</EM>.
  540. <P></P>
  541. <LI><STRONG>flags</STRONG><BR>
  542.  
  543. Additional flags affecting the behavior of the function.  Default:
  544. <EM>none</EM>.
  545. <P></P></UL>
  546. <P>Refer to the <A HREF="#microsoft win32 internet functions">Microsoft Win32 Internet Functions</A> documentation for
  547. more details on those parameters.  If you pass <EM>hashref</EM> (a reference to
  548. an hash array), the following values are taken from the array:</P>
  549. <PRE>
  550.     %hash=(
  551.       "useragent"   => "useragent",
  552.       "opentype"    => "opentype",
  553.       "proxy"       => "proxy",
  554.       "proxybypass" => "proxybypass",
  555.       "flags"       => flags,
  556.     );</PRE>
  557. <P>Example:</P>
  558. <PRE>
  559.     $INET = new Win32::Internet();
  560.     die qq(Cannot connect to Internet...\n) if ! $INET;</PRE>
  561. <PRE>
  562.     $INET = new Win32::Internet("Mozilla/3.0", INTERNET_OPEN_TYPE_PROXY, "www.microsoft.com", "");</PRE>
  563. <PRE>
  564.     $params{"flags"} = INTERNET_FLAG_ASYNC;
  565.     $INET = new Win32::Internet(\%params);</PRE>
  566. <DT><STRONG><A NAME="item_OpenURL_urlobject%2C_URL">OpenURL urlobject, URL</A></STRONG><BR>
  567. <DD>
  568. Opens a connection to an HTTP, FTP or GOPHER Uniform Resource Location
  569. (URL).  Returns <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> on errors or a number if the connection was
  570. succesful.  You can then retrieve the URL content by applying the
  571. methods <A HREF="#item_QueryDataAvailable"><CODE>QueryDataAvailable</CODE></A> and <CODE>ReadFile</CODE> on the newly created
  572. <EM>urlobject</EM>.  See also <CODE>FetchURL</CODE>.
  573. <P>Example:</P>
  574. <PRE>
  575.     $INET->OpenURL($URL, "<A HREF="http://www.yahoo.com/"">http://www.yahoo.com/"</A>;);
  576.     $bytes = $URL->QueryDataAvailable();
  577.     $file = $URL->ReadEntireFile();
  578.     $URL->Close();</PRE>
  579. <P></P>
  580. <DT><STRONG><A NAME="item_Password_%5Bpassword%5D">Password [password]</A></STRONG><BR>
  581. <DD>
  582. Reads or sets the password used for an <CODE>FTP</CODE> or <CODE>HTTP</CODE> connection.
  583. If no <EM>password</EM> parameter is specified, the current value is
  584. returned; otherwise, the password is set to <EM>password</EM>.  See also
  585. <CODE>Username</CODE>, <CODE>QueryOption</CODE> and <CODE>SetOption</CODE>.
  586. <P>Example:</P>
  587. <PRE>
  588.     $HTTP->Password("splurfgnagbxam");
  589.     $password = $HTTP->Password();</PRE>
  590. <P></P>
  591. <DT><STRONG><A NAME="item_QueryDataAvailable">QueryDataAvailable</A></STRONG><BR>
  592. <DD>
  593. Returns the number of bytes of data that are available to be read
  594. immediately by a subsequent call to <CODE>ReadFile</CODE> (or <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> on
  595. errors).  Can be applied to URL or HTTP request objects.  See
  596. <CODE>OpenURL</CODE> or <CODE>OpenRequest</CODE>.
  597. <P>Example:</P>
  598. <PRE>
  599.     $INET->OpenURL($URL, "<A HREF="http://www.yahoo.com/"">http://www.yahoo.com/"</A>;);
  600.     $bytes = $URL->QueryDataAvailable();</PRE>
  601. <P></P>
  602. <DT><STRONG><A NAME="item_QueryOption_option">QueryOption option</A></STRONG><BR>
  603. <DD>
  604. Queries an Internet option.  For the possible values of <EM>option</EM>,
  605. refer to the <A HREF="#microsoft win32 internet functions">Microsoft Win32 Internet Functions</A> document.  See
  606. also <CODE>SetOption</CODE>.
  607. <P>Example:</P>
  608. <PRE>
  609.     $value = $INET->QueryOption(INTERNET_OPTION_CONNECT_TIMEOUT);
  610.     $value = $HTTP->QueryOption(INTERNET_OPTION_USERNAME);</PRE>
  611. <P></P>
  612. <DT><STRONG><A NAME="item_ReadEntireFile">ReadEntireFile</A></STRONG><BR>
  613. <DD>
  614. Reads all the data available from an opened URL or HTTP request
  615. object.  Returns what have been read or <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> on errors.  See also
  616. <CODE>OpenURL</CODE>, <CODE>OpenRequest</CODE> and <CODE>ReadFile</CODE>.
  617. <P>Example:</P>
  618. <PRE>
  619.     $INET->OpenURL($URL, "<A HREF="http://www.yahoo.com/"">http://www.yahoo.com/"</A>;);
  620.     $file = $URL->ReadEntireFile();</PRE>
  621. <P></P>
  622. <DT><STRONG><A NAME="item_ReadFile_bytes">ReadFile bytes</A></STRONG><BR>
  623. <DD>
  624. Reads <EM>bytes</EM> bytes of data from an opened URL or HTTP request
  625. object.  Returns what have been read or <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> on errors.  See also
  626. <CODE>OpenURL</CODE>, <CODE>OpenRequest</CODE>, <A HREF="#item_QueryDataAvailable"><CODE>QueryDataAvailable</CODE></A> and
  627. <A HREF="#item_ReadEntireFile"><CODE>ReadEntireFile</CODE></A>.
  628. <P><STRONG>Note:</STRONG> be careful to keep <EM>bytes</EM> to an acceptable value (eg.  don't
  629. tell him to swallow megabytes at once...).  <A HREF="#item_ReadEntireFile"><CODE>ReadEntireFile</CODE></A> in fact
  630. uses <A HREF="#item_QueryDataAvailable"><CODE>QueryDataAvailable</CODE></A> and <CODE>ReadFile</CODE> in a loop to read no more
  631. than 16k at a time.</P>
  632. <P>Example:</P>
  633. <PRE>
  634.     $INET->OpenURL($URL, "<A HREF="http://www.yahoo.com/"">http://www.yahoo.com/"</A>;);
  635.     $chunk = $URL->ReadFile(16000);</PRE>
  636. <P></P>
  637. <DT><STRONG><A NAME="item_SetOption_option%2C_value">SetOption option, value</A></STRONG><BR>
  638. <DD>
  639. Sets an Internet option.  For the possible values of <EM>option</EM>, refer to
  640. the <A HREF="#microsoft win32 internet functions">Microsoft Win32 Internet Functions</A> document.  See also
  641. <CODE>QueryOption</CODE>.
  642. <P>Example:</P>
  643. <PRE>
  644.     $INET->SetOption(INTERNET_OPTION_CONNECT_TIMEOUT,10000);
  645.     $HTTP->SetOption(INTERNET_OPTION_USERNAME,"dada");</PRE>
  646. <P></P>
  647. <DT><STRONG><A NAME="item_SetStatusCallback">SetStatusCallback</A></STRONG><BR>
  648. <DD>
  649. Initializes the callback routine used to return data about the
  650. progress of an asynchronous operation.
  651. <P>Example:</P>
  652. <PRE>
  653.     $INET->SetStatusCallback();</PRE>
  654. <P>This is one of the step required to perform asynchronous operations;
  655. the complete procedure is:</P>
  656. <PRE>
  657.     # use the INTERNET_FLAG_ASYNC when initializing
  658.     $params{'flags'}=INTERNET_FLAG_ASYNC;
  659.     $INET = new Win32::Internet(\%params);</PRE>
  660. <PRE>
  661.     # initialize the callback routine
  662.     $INET->SetStatusCallback();</PRE>
  663. <PRE>
  664.     # specify the context parameter (the last 1 in this case)
  665.     $INET->HTTP($HTTP, "www.yahoo.com", "anonymous", "dada\@divinf.it", 80, 0, 1);</PRE>
  666. <P>At this point, control returns immediately to Perl and $INET-><A HREF="#item_Error"><CODE>Error()</CODE></A>
  667. will return 997, which means an asynchronous I/O operation is
  668. pending.  Now, you can call</P>
  669. <PRE>
  670.     $HTTP->GetStatusCallback(1);</PRE>
  671. <P>in a loop to verify what's happening; see also <CODE>GetStatusCallback</CODE>.</P>
  672. <P></P>
  673. <DT><STRONG><A NAME="item_TimeConvert_time">TimeConvert time</A></STRONG><BR>
  674. <DD>
  675. <DT><STRONG><A NAME="item_TimeConvert_seconds%2C_minute%2C_hours%2C_day%2C_m">TimeConvert seconds, minute, hours, day, month, year,
  676.                   day_of_week, RFC</A></STRONG><BR>
  677. <DD>
  678. The first form takes a HTTP date/time string and returns the date/time
  679. converted in the following array: <EM>seconds, minute, hours, day,
  680. month, year, day_of_week</EM>.
  681. <P>The second form does the opposite (or at least it should, because
  682. actually seems to be malfunctioning): it takes the values and returns
  683. an HTTP date/time string, in the RFC format specified by the <EM>RFC</EM>
  684. parameter (OK, I didn't find yet any accepted value in the range
  685. 0..2000, let me know if you have more luck with it).</P>
  686. <P>Example:</P>
  687. <PRE>
  688.     ($sec, $min, $hour, $day, $mday, $year, $wday) =
  689.        $INET->TimeConvert("Sun, 26 Jan 1997 20:01:52 GMT");</PRE>
  690. <PRE>
  691.     # the opposite DOESN'T WORK! which value should $RFC have???
  692.     $time = $INET->TimeConvert(52, 1, 20, 26, 1, 1997, 0, $RFC);</PRE>
  693. <P></P>
  694. <DT><STRONG><A NAME="item_UserAgent_%5Bname%5D">UserAgent [name]</A></STRONG><BR>
  695. <DD>
  696. Reads or sets the user agent used for HTTP requests.  If no <EM>name</EM>
  697. parameter is specified, the current value is returned; otherwise, the
  698. user agent is set to <EM>name</EM>.  See also <CODE>QueryOption</CODE> and
  699. <CODE>SetOption</CODE>.
  700. <P>Example:</P>
  701. <PRE>
  702.     $INET->UserAgent("Mozilla/3.0");
  703.     $useragent = $INET->UserAgent();</PRE>
  704. <P></P>
  705. <DT><STRONG><A NAME="item_Username_%5Bname%5D">Username [name]</A></STRONG><BR>
  706. <DD>
  707. Reads or sets the username used for an <CODE>FTP</CODE> or <CODE>HTTP</CODE> connection.
  708. If no <EM>name</EM> parameter is specified, the current value is returned;
  709. otherwise, the username is set to <EM>name</EM>.  See also <CODE>Password</CODE>,
  710. <CODE>QueryOption</CODE> and SetOption.
  711. <P>Example:</P>
  712. <PRE>
  713.     $HTTP->Username("dada");
  714.     $username = $HTTP->Username();</PRE>
  715. <P></P>
  716. <DT><STRONG><A NAME="item_Version">Version</A></STRONG><BR>
  717. <DD>
  718. Returns the version numbers for the Win32::Internet package and the
  719. WININET.DLL version, as an array or string, depending on the context.
  720. The string returned will contain ``package_version/DLL_version'', while
  721. the array will contain: ``package_version'', ``DLL_version''.
  722. <P>Example:</P>
  723. <PRE>
  724.     $version = $INET->Version(); # should return "0.06/4.70.1215"
  725.     @version = $INET->Version(); # should return ("0.06", "4.70.1215")</PRE>
  726. <P></P></DL>
  727. <P>
  728. <H2><A NAME="ftp functions">FTP Functions</A></H2>
  729. <P><STRONG>General Note</STRONG></P>
  730. <P>All methods assume that you have the following lines:</P>
  731. <PRE>
  732.     use Win32::Internet;
  733.     $INET = new Win32::Internet();
  734.     $INET->FTP($FTP, "hostname", "username", "password");</PRE>
  735. <P>somewhere before the method calls; in other words, we assume that you
  736. have an Internet object called $INET and an open FTP session called
  737. $FTP.</P>
  738. <P>See <CODE>new</CODE> and <CODE>FTP</CODE> for more information.</P>
  739. <P><STRONG>Methods</STRONG></P>
  740. <DL>
  741. <DT><STRONG><A NAME="item_Ascii">Ascii</A></STRONG><BR>
  742. <DD>
  743. <DT><STRONG><A NAME="item_Asc">Asc</A></STRONG><BR>
  744. <DD>
  745. Sets the ASCII transfer mode for this FTP session.  It will be applied
  746. to the subsequent <CODE>Get</CODE> functions.  See also the <A HREF="#item_Binary"><CODE>Binary</CODE></A> and
  747. <CODE>Mode</CODE> function.
  748. <P>Example:</P>
  749. <PRE>
  750.     $FTP->Ascii();</PRE>
  751. <P></P>
  752. <DT><STRONG><A NAME="item_Binary">Binary</A></STRONG><BR>
  753. <DD>
  754. <DT><STRONG><A NAME="item_Bin">Bin</A></STRONG><BR>
  755. <DD>
  756. Sets the binary transfer mode for this FTP session.  It will be
  757. applied to the subsequent <CODE>Get</CODE> functions.  See also the <A HREF="#item_Ascii"><CODE>Ascii</CODE></A> and
  758. <CODE>Mode</CODE> function.
  759. <P>Example:</P>
  760. <PRE>
  761.     $FTP->Binary();</PRE>
  762. <P></P>
  763. <DT><STRONG><A NAME="item_Cd_path">Cd path</A></STRONG><BR>
  764. <DD>
  765. <DT><STRONG><A NAME="item_Cwd_path">Cwd path</A></STRONG><BR>
  766. <DD>
  767. <DT><STRONG><A NAME="item_Chdir_path">Chdir path</A></STRONG><BR>
  768. <DD>
  769. Changes the current directory on the FTP remote host.  Returns <EM>path</EM>
  770. or <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> on error.
  771. <P>Example:</P>
  772. <PRE>
  773.     $FTP->Cd("/pub");</PRE>
  774. <P></P>
  775. <DT><STRONG><A NAME="item_Delete_file">Delete file</A></STRONG><BR>
  776. <DD>
  777. <DT><STRONG><A NAME="item_Del_file">Del file</A></STRONG><BR>
  778. <DD>
  779. Deletes a file on the FTP remote host.  Returns <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> on error.
  780. <P>Example:</P>
  781. <PRE>
  782.     $FTP->Delete("110-i86.zip");</PRE>
  783. <P></P>
  784. <DT><STRONG><A NAME="item_Get_remote%2C_%5Blocal%2C_overwrite%2C_flags%2C_co">Get remote, [local, overwrite, flags, context]</A></STRONG><BR>
  785. <DD>
  786. Gets the <EM>remote</EM> FTP file and saves it locally in <EM>local</EM>.  If
  787. <EM>local</EM> is not specified, it will be the same name as <EM>remote</EM>.
  788. Returns <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> on error.  The parameters and their values are:
  789. <UL>
  790. <LI><STRONG><A NAME="item_remote">remote</A></STRONG><BR>
  791.  
  792. The name of the remote file on the FTP server.  Default: <EM>none</EM>.
  793. <P></P>
  794. <LI><STRONG><A NAME="item_local">local</A></STRONG><BR>
  795.  
  796. The name of the local file to create.  Default: remote.
  797. <P></P>
  798. <LI><STRONG><A NAME="item_overwrite">overwrite</A></STRONG><BR>
  799.  
  800. If 0, overwrites <EM>local</EM> if it exists; with any other value, the
  801. function fails if the <EM>local</EM> file already exists.  Default: 0.
  802. <P></P>
  803. <LI><STRONG>flags</STRONG><BR>
  804.  
  805. Additional flags affecting the behavior of the function.  Default:
  806. <EM>none</EM>.
  807. <P></P>
  808. <LI><STRONG>context</STRONG><BR>
  809.  
  810. A number to identify this operation if it is asynchronous.  See
  811. <A HREF="#item_SetStatusCallback"><CODE>SetStatusCallback</CODE></A> and <CODE>GetStatusCallback</CODE> for more info on
  812. asynchronous operations.  Default: <EM>none</EM>.
  813. <P></P></UL>
  814. <P>Refer to the <A HREF="#microsoft win32 internet functions">Microsoft Win32 Internet Functions</A> documentation for
  815. more details on those parameters.</P>
  816. <P>Example:</P>
  817. <PRE>
  818.     $FTP->Get("110-i86.zip");
  819.     $FTP->Get("/pub/perl/languages/CPAN/00index.html", "CPAN_index.html");</PRE>
  820. <DT><STRONG><A NAME="item_List_%5Bpattern%2C_listmode%5D">List [pattern, listmode]</A></STRONG><BR>
  821. <DD>
  822. <DT><STRONG><A NAME="item_Ls_%5Bpattern%2C_listmode%5D">Ls [pattern, listmode]</A></STRONG><BR>
  823. <DD>
  824. <DT><STRONG><A NAME="item_Dir_%5Bpattern%2C_listmode%5D">Dir [pattern, listmode]</A></STRONG><BR>
  825. <DD>
  826. Returns a list containing the files found in this directory,
  827. eventually matching the given <EM>pattern</EM> (which, if omitted, is
  828. considered ``*.*'').  The content of the returned list depends on the
  829. <EM>listmode</EM> parameter, which can have the following values:
  830. <UL>
  831. <LI><STRONG><A NAME="item_1">listmode=1 (or omitted)</A></STRONG><BR>
  832.  
  833. the list contains the names of the files found.  Example:
  834. <PRE>
  835.     @files = $FTP->List();
  836.     @textfiles = $FTP->List("*.txt");
  837.     foreach $file (@textfiles) {
  838.       print "Name: ", $file, "\n";
  839.     }</PRE>
  840. <P></P>
  841. <LI><STRONG><A NAME="item_listmode%3D2">listmode=2</A></STRONG><BR>
  842.  
  843. the list contains 7 values for each file, which respectively are:
  844. <UL>
  845. <LI><STRONG><A NAME="item_the_file_name">the file name</A></STRONG><BR>
  846.  
  847. <LI><STRONG><A NAME="item_the_DOS_short_file_name%2C_aka_8%2E3">the DOS short file name, aka 8.3</A></STRONG><BR>
  848.  
  849. <LI><STRONG><A NAME="item_the_size">the size</A></STRONG><BR>
  850.  
  851. <LI><STRONG><A NAME="item_the_attributes">the attributes</A></STRONG><BR>
  852.  
  853. <LI><STRONG><A NAME="item_the_creation_time">the creation time</A></STRONG><BR>
  854.  
  855. <LI><STRONG><A NAME="item_the_last_access_time">the last access time</A></STRONG><BR>
  856.  
  857. <LI><STRONG><A NAME="item_the_last_modified_time">the last modified time</A></STRONG><BR>
  858.  
  859. </UL>
  860. <P>Example:</P>
  861. <PRE>
  862.     @files = $FTP->List("*.*", 2);
  863.     for($i=0; $i<=$#files; $i+=7) {
  864.       print "Name: ", @files[$i], "\n";
  865.       print "Size: ", @files[$i+2], "\n";
  866.       print "Attr: ", @files[$i+3], "\n";
  867.     }</PRE>
  868. <LI><STRONG><A NAME="item_listmode%3D3">listmode=3</A></STRONG><BR>
  869.  
  870. the list contains a reference to an hash array for each found file;
  871. each hash contains:
  872. <UL>
  873. <LI><STRONG><A NAME="item_name_%3D%3E_the_file_name">name => the file name</A></STRONG><BR>
  874.  
  875. <LI><STRONG><A NAME="item_altname_%3D%3E_the_DOS_short_file_name%2C_aka_8%2E">altname => the DOS short file name, aka 8.3</A></STRONG><BR>
  876.  
  877. <LI><STRONG><A NAME="item_size_%3D%3E_the_size">size => the size</A></STRONG><BR>
  878.  
  879. <LI><STRONG><A NAME="item_attr_%3D%3E_the_attributes">attr => the attributes</A></STRONG><BR>
  880.  
  881. <LI><STRONG><A NAME="item_ctime_%3D%3E_the_creation_time">ctime => the creation time</A></STRONG><BR>
  882.  
  883. <LI><STRONG><A NAME="item_atime_%3D%3E_the_last_access_time">atime => the last access time</A></STRONG><BR>
  884.  
  885. <LI><STRONG><A NAME="item_mtime_%3D%3E_the_last_modified_time">mtime => the last modified time</A></STRONG><BR>
  886.  
  887. </UL>
  888. <P>Example:</P>
  889. <PRE>
  890.     @files = $FTP->List("*.*", 3);
  891.     foreach $file (@files) {
  892.       print $file->{'name'}, " ", $file->{'size'}, " ", $file->{'attr'}, "\n";
  893.     }</PRE>
  894. <P><STRONG>Note:</STRONG> all times are reported as strings of the following format:
  895. <EM>second, hour, minute, day, month, year</EM>.</P>
  896. <P>Example:</P>
  897. <PRE>
  898.     $file->{'mtime'} == "0,10,58,9,12,1996" stands for 09 Dec 1996 at 10:58:00</PRE>
  899. </UL>
  900. <DT><STRONG><A NAME="item_Mkdir_name">Mkdir name</A></STRONG><BR>
  901. <DD>
  902. <DT><STRONG><A NAME="item_Md_name">Md name</A></STRONG><BR>
  903. <DD>
  904. Creates a directory on the FTP remote host.  Returns <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> on error.
  905. <P>Example:</P>
  906. <PRE>
  907.     $FTP->Mkdir("NextBuild");</PRE>
  908. <P></P>
  909. <DT><STRONG><A NAME="item_Mode_%5Bmode%5D">Mode [mode]</A></STRONG><BR>
  910. <DD>
  911. If called with no arguments, returns the current transfer mode for
  912. this FTP session (``asc'' for ASCII or ``bin'' for binary).  The <EM>mode</EM>
  913. argument can be ``asc'' or ``bin'', in which case the appropriate transfer
  914. mode is selected.  See also the Ascii and Binary functions.  Returns
  915. <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> on errors.
  916. <P>Example:</P>
  917. <PRE>
  918.     print "Current mode is: ", $FTP->Mode();
  919.     $FTP->Mode("asc"); # ...  same as $FTP->Ascii();</PRE>
  920. <P></P>
  921. <DT><STRONG><A NAME="item_Pasv_%5Bmode%5D">Pasv [mode]</A></STRONG><BR>
  922. <DD>
  923. If called with no arguments, returns 1 if the current FTP session has
  924. passive transfer mode enabled, 0 if not.
  925. <P>You can call it with a <EM>mode</EM> parameter (0/1) only as a method of a
  926. Internet object (see <CODE>new</CODE>), in which case it will set the default
  927. value for the next <CODE>FTP</CODE> objects you create (read: set it before,
  928. because you can't change this value once you opened the FTP session).</P>
  929. <P>Example:</P>
  930. <PRE>
  931.     print "Pasv is: ", $FTP->Pasv();</PRE>
  932. <PRE>
  933.     $INET->Pasv(1);
  934.     $INET->FTP($FTP,"ftp.activeware.com", "anonymous", "dada\@divinf.it");
  935.     $FTP->Pasv(0); # this will be ignored...</PRE>
  936. <P></P>
  937. <DT><STRONG><A NAME="item_Put_local%2C_%5Bremote%2C_context%5D">Put local, [remote, context]</A></STRONG><BR>
  938. <DD>
  939. Upload the <EM>local</EM> file to the FTP server saving it under the name
  940. <EM>remote</EM>, which if if omitted is the same name as <EM>local</EM>.  Returns
  941. <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> on error.
  942. <P><EM>context</EM> is a number to identify this operation if it is asynchronous.
  943. See <A HREF="#item_SetStatusCallback"><CODE>SetStatusCallback</CODE></A> and <CODE>GetStatusCallback</CODE> for more info on
  944. asynchronous operations.</P>
  945. <P>Example:</P>
  946. <PRE>
  947.     $FTP->Put("internet.zip");
  948.     $FTP->Put("d:/users/dada/temp.zip", "/temp/dada.zip");</PRE>
  949. <P></P>
  950. <DT><STRONG><A NAME="item_Pwd">Pwd</A></STRONG><BR>
  951. <DD>
  952. Returns the current directory on the FTP server or <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> on errors.
  953. <P>Example:</P>
  954. <PRE>
  955.     $path = $FTP->Pwd();</PRE>
  956. <P></P>
  957. <DT><STRONG><A NAME="item_Rename_oldfile%2C_newfile">Rename oldfile, newfile</A></STRONG><BR>
  958. <DD>
  959. <DT><STRONG><A NAME="item_Ren_oldfile%2C_newfile">Ren oldfile, newfile</A></STRONG><BR>
  960. <DD>
  961. Renames a file on the FTP remote host.  Returns <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> on error.
  962. <P>Example:</P>
  963. <PRE>
  964.     $FTP->Rename("110-i86.zip", "68i-011.zip");</PRE>
  965. <P></P>
  966. <DT><STRONG><A NAME="item_Rmdir_name">Rmdir name</A></STRONG><BR>
  967. <DD>
  968. <DT><STRONG><A NAME="item_Rd_name">Rd name</A></STRONG><BR>
  969. <DD>
  970. Removes a directory on the FTP remote host.  Returns <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> on error.
  971. <P>Example:</P>
  972. <PRE>
  973.     $FTP->Rmdir("CurrentBuild");</PRE>
  974. <P></P></DL>
  975. <P>
  976. <H2><A NAME="http functions">HTTP Functions</A></H2>
  977. <P><STRONG>General Note</STRONG></P>
  978. <P>All methods assume that you have the following lines:</P>
  979. <PRE>
  980.     use Win32::Internet;
  981.     $INET = new Win32::Internet();
  982.     $INET->HTTP($HTTP, "hostname", "username", "password");</PRE>
  983. <P>somewhere before the method calls; in other words, we assume that you
  984. have an Internet object called $INET and an open HTTP session called
  985. $HTTP.</P>
  986. <P>See <CODE>new</CODE> and <CODE>HTTP</CODE> for more information.</P>
  987. <P><STRONG>Methods</STRONG></P>
  988. <DL>
  989. <DT><STRONG><A NAME="item_AddHeader_header%2C_%5Bflags%5D">AddHeader header, [flags]</A></STRONG><BR>
  990. <DD>
  991. Adds HTTP request headers to an HTTP request object created with
  992. <CODE>OpenRequest</CODE>.  For the possible values of <EM>flags</EM> refer to the
  993. <A HREF="#microsoft win32 internet functions">Microsoft Win32 Internet Functions</A> document.
  994. <P>Example:</P>
  995. <PRE>
  996.     $HTTP->OpenRequest($REQUEST,"/index.html");
  997.     $REQUEST->AddHeader("If-Modified-Since:  Sunday, 17-Nov-96 11:40:03 GMT");
  998.     $REQUEST->AddHeader("Accept: text/html\r\n", HTTP_ADDREQ_FLAG_REPLACE);</PRE>
  999. <P></P>
  1000. <DT><STRONG><A NAME="item_OpenRequest_requestobject%2C_%5Bpath%2C_method%2C_">OpenRequest requestobject, [path, method, version, referer, accept, flags, context]</A></STRONG><BR>
  1001. <DD>
  1002. <DT><STRONG><A NAME="item_OpenRequest_requestobject%2C_hashref">OpenRequest requestobject, hashref</A></STRONG><BR>
  1003. <DD>
  1004. Opens an HTTP request.  Returns <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> on errors or a number if the
  1005. connection was succesful.  You can then use one of the <CODE>AddHeader</CODE>,
  1006. <CODE>SendRequest</CODE>, <CODE>QueryInfo</CODE>, <A HREF="#item_QueryDataAvailable"><CODE>QueryDataAvailable</CODE></A> and <CODE>ReadFile</CODE>
  1007. methods on the newly created <EM>requestobject</EM>.  The parameters and
  1008. their values are:
  1009. <UL>
  1010. <LI><STRONG><A NAME="item_path">path</A></STRONG><BR>
  1011.  
  1012. The object to request.  This is generally a file name, an executable
  1013. module, etc.  Default: /
  1014. <P></P>
  1015. <LI><STRONG><A NAME="item_method">method</A></STRONG><BR>
  1016.  
  1017. The method to use; can actually be GET, POST, HEAD or PUT.  Default:
  1018. GET
  1019. <P></P>
  1020. <LI><STRONG><A NAME="item_version">version</A></STRONG><BR>
  1021.  
  1022. The HTTP version.  Default: HTTP/1.0
  1023. <P></P>
  1024. <LI><STRONG><A NAME="item_referer">referer</A></STRONG><BR>
  1025.  
  1026. The URL of the document from which the URL in the request was
  1027. obtained.  Default: <EM>none</EM>
  1028. <P></P>
  1029. <LI><STRONG><A NAME="item_accept">accept</A></STRONG><BR>
  1030.  
  1031. The content types accepted.  They must be separated by a ``\0'' (ASCII
  1032. zero).  Default: text/* image/gif image/jpeg
  1033. <P></P>
  1034. <LI><STRONG>flags</STRONG><BR>
  1035.  
  1036. Additional flags affecting the behavior of the function.  Default:
  1037. <EM>none</EM>
  1038. <P></P>
  1039. <LI><STRONG>context</STRONG><BR>
  1040.  
  1041. A number to identify this operation if it is asynchronous.  See
  1042. <A HREF="#item_SetStatusCallback"><CODE>SetStatusCallback</CODE></A> and <CODE>GetStatusCallback</CODE> for more info on
  1043. asynchronous operations.  Default: <EM>none</EM>
  1044. <P></P></UL>
  1045. <P>Refer to the <A HREF="#microsoft win32 internet functions">Microsoft Win32 Internet Functions</A> documentation for
  1046. more details on those parameters.  If you pass <EM>hashref</EM> (a reference to
  1047. an hash array), the following values are taken from the array:</P>
  1048. <PRE>
  1049.     %hash=(
  1050.       "path"        => "path",
  1051.       "method"      => "method",
  1052.       "version"     => "version",
  1053.       "referer"     => "referer",
  1054.       "accept"      => "accept",
  1055.       "flags"       => flags,
  1056.       "context"     => context,
  1057.     );</PRE>
  1058. <P>See also <CODE>Request</CODE>.</P>
  1059. <P>Example:</P>
  1060. <PRE>
  1061.     $HTTP->OpenRequest($REQUEST, "/index.html");
  1062.     $HTTP->OpenRequest($REQUEST, "/index.html", "GET", "HTTP/0.9");</PRE>
  1063. <PRE>
  1064.     $params{"path"} = "/index.html";
  1065.     $params{"flags"} = "
  1066.     $HTTP->OpenRequest($REQUEST, \%params);</PRE>
  1067. <DT><STRONG><A NAME="item_QueryInfo_header%2C_%5Bflags%5D">QueryInfo header, [flags]</A></STRONG><BR>
  1068. <DD>
  1069. Queries information about an HTTP request object created with
  1070. <CODE>OpenRequest</CODE>.  You can specify an <EM>header</EM> (for example,
  1071. ``Content-type'') and/or one or more <EM>flags</EM>.  If you don't specify
  1072. <EM>flags</EM>, HTTP_QUERY_CUSTOM will be used by default; this means that
  1073. <EM>header</EM> should contain a valid HTTP header name.  For the possible
  1074. values of <EM>flags</EM> refer to the <A HREF="#microsoft win32 internet functions">Microsoft Win32 Internet Functions</A> document.
  1075. <P>Example:</P>
  1076. <PRE>
  1077.     $HTTP->OpenRequest($REQUEST,"/index.html");
  1078.     $statuscode = $REQUEST->QueryInfo("", HTTP_QUERY_STATUS_CODE);
  1079.     $headers = $REQUEST->QueryInfo("", HTTP_QUERY_RAW_HEADERS_CRLF); # will get all the headers
  1080.     $length = $REQUEST->QueryInfo("Content-length");</PRE>
  1081. <P></P>
  1082. <DT><STRONG><A NAME="item_Request_%5Bpath%2C_method%2C_version%2C_referer%2C">Request [path, method, version, referer, accept, flags]</A></STRONG><BR>
  1083. <DD>
  1084. <DT><STRONG><A NAME="item_Request_hashref">Request hashref</A></STRONG><BR>
  1085. <DD>
  1086. Performs an HTTP request and returns an array containing the status
  1087. code, the headers and the content of the file.  It is a one-step
  1088. procedure that makes an <CODE>OpenRequest</CODE>, a <CODE>SendRequest</CODE>, some
  1089. <CODE>QueryInfo</CODE>, <CODE>ReadFile</CODE> and finally <A HREF="#item_Close"><CODE>Close</CODE></A>.  For a description of
  1090. the parameters, see <CODE>OpenRequest</CODE>.
  1091. <P>Example:</P>
  1092. <PRE>
  1093.     ($statuscode, $headers, $file) = $HTTP->Request("/index.html");
  1094.     ($s, $h, $f) = $HTTP->Request("/index.html", "GET", "HTTP/1.0");</PRE>
  1095. <P></P>
  1096. <DT><STRONG><A NAME="item_SendRequest_%5Bpostdata%5D">SendRequest [postdata]</A></STRONG><BR>
  1097. <DD>
  1098. Send an HTTP request to the destination server.  <EM>postdata</EM> are any
  1099. optional data to send immediately after the request header; this is
  1100. generally used for POST or PUT requests.  See also <CODE>OpenRequest</CODE>.
  1101. <P>Example:</P>
  1102. <PRE>
  1103.     $HTTP->OpenRequest($REQUEST, "/index.html");
  1104.     $REQUEST->SendRequest();</PRE>
  1105. <PRE>
  1106.     # A POST request...
  1107.     $HTTP->OpenRequest($REQUEST, "/cgi-bin/somescript.pl", "POST");</PRE>
  1108. <PRE>
  1109.     #This line is a must -> (thanks Philip :)
  1110.     $REQUEST->AddHeader("Content-Type: application/x-www-form-urlencoded");</PRE>
  1111. <PRE>
  1112.     $REQUEST->SendRequest("key1=value1&key2=value2&key3=value3");</PRE>
  1113. <P></P></DL>
  1114. <P>
  1115. <HR>
  1116. <H1><A NAME="appendix">APPENDIX</A></H1>
  1117. <P>
  1118. <H2><A NAME="microsoft win32 internet functions">Microsoft Win32 Internet Functions</A></H2>
  1119. <P>Complete documentation for the Microsoft Win32 Internet Functions can
  1120. be found, in both HTML and zipped Word format, at this address:</P>
  1121. <PRE>
  1122.     <A HREF="http://www.microsoft.com/intdev/sdk/docs/wininet/">http://www.microsoft.com/intdev/sdk/docs/wininet/</A></PRE>
  1123. <P>
  1124. <H2><A NAME="functions table">Functions Table</A></H2>
  1125. <P>This table reports the correspondence between the functions offered by
  1126. WININET.DLL and their implementation in the Win32::Internet
  1127. extension. Functions showing a ``---'' are not currently
  1128. implemented. Functions enclosed in parens ( ) aren't implemented
  1129. straightforwardly, but in a higher-level routine, eg. together with
  1130. other functions.</P>
  1131. <PRE>
  1132.     WININET.DLL                     Win32::Internet</PRE>
  1133. <PRE>
  1134.     InternetOpen                    new Win32::Internet
  1135.     InternetConnect                 FTP / HTTP
  1136.     InternetCloseHandle             Close
  1137.     InternetQueryOption             QueryOption
  1138.     InternetSetOption               SetOption
  1139.     InternetSetOptionEx             ---
  1140.     InternetSetStatusCallback       SetStatusCallback
  1141.     InternetStatusCallback          GetStatusCallback
  1142.     InternetConfirmZoneCrossing     ---
  1143.     InternetTimeFromSystemTime      TimeConvert
  1144.     InternetTimeToSystemTime        TimeConvert
  1145.     InternetAttemptConnect          ---
  1146.     InternetReadFile                ReadFile
  1147.     InternetSetFilePointer          ---
  1148.     InternetFindNextFile            (List)
  1149.     InternetQueryDataAvailable      QueryDataAvailable
  1150.     InternetGetLastResponseInfo     GetResponse
  1151.     InternetWriteFile               ---
  1152.     InternetCrackUrl                CrackURL
  1153.     InternetCreateUrl               CreateURL
  1154.     InternetCanonicalizeUrl         CanonicalizeURL
  1155.     InternetCombineUrl              CombineURL
  1156.     InternetOpenUrl                 OpenURL
  1157.     FtpFindFirstFile                (List)
  1158.     FtpGetFile                      Get
  1159.     FtpPutFile                      Put
  1160.     FtpDeleteFile                   Delete
  1161.     FtpRenameFile                   Rename
  1162.     FtpOpenFile                     ---
  1163.     FtpCreateDirectory              Mkdir
  1164.     FtpRemoveDirectory              Rmdir
  1165.     FtpSetCurrentDirectory          Cd
  1166.     FtpGetCurrentDirectory          Pwd
  1167.     HttpOpenRequest                 OpenRequest
  1168.     HttpAddRequestHeaders           AddHeader
  1169.     HttpSendRequest                 SendRequest
  1170.     HttpQueryInfo                   QueryInfo
  1171.     InternetErrorDlg                ---</PRE>
  1172. <P>Actually, I don't plan to add support for Gopher, Cookie and Cache
  1173. functions. I will if there will be consistent requests to do so.</P>
  1174. <P>There are a number of higher-level functions in the Win32::Internet
  1175. that simplify some usual procedures, calling more that one WININET API
  1176. function. This table reports those functions and the relative WININET
  1177. functions they use.</P>
  1178. <PRE>
  1179.     Win32::Internet                 WININET.DLL</PRE>
  1180. <PRE>
  1181.     FetchURL                        InternetOpenUrl
  1182.                                     InternetQueryDataAvailable
  1183.                                     InternetReadFile
  1184.                                     InternetCloseHandle</PRE>
  1185. <PRE>
  1186.     ReadEntireFile                  InternetQueryDataAvailable
  1187.                                     InternetReadFile</PRE>
  1188. <PRE>
  1189.     Request                         HttpOpenRequest
  1190.                                     HttpSendRequest
  1191.                                     HttpQueryInfo
  1192.                                     InternetQueryDataAvailable
  1193.                                     InternetReadFile
  1194.                                     InternetCloseHandle</PRE>
  1195. <PRE>
  1196.     List                            FtpFindFirstFile
  1197.                                     InternetFindNextFile</PRE>
  1198. <P>
  1199. <H2><A NAME="constants">Constants</A></H2>
  1200. <P>Those are the constants exported by the package in the main namespace
  1201. (eg. you can use them in your scripts); for their meaning and proper
  1202. use, refer to the Microsoft Win32 Internet Functions document.</P>
  1203. <PRE>
  1204.     HTTP_ADDREQ_FLAG_ADD
  1205.     HTTP_ADDREQ_FLAG_REPLACE
  1206.     HTTP_QUERY_ALLOW
  1207.     HTTP_QUERY_CONTENT_DESCRIPTION
  1208.     HTTP_QUERY_CONTENT_ID
  1209.     HTTP_QUERY_CONTENT_LENGTH
  1210.     HTTP_QUERY_CONTENT_TRANSFER_ENCODING
  1211.     HTTP_QUERY_CONTENT_TYPE
  1212.     HTTP_QUERY_COST
  1213.     HTTP_QUERY_CUSTOM
  1214.     HTTP_QUERY_DATE
  1215.     HTTP_QUERY_DERIVED_FROM
  1216.     HTTP_QUERY_EXPIRES
  1217.     HTTP_QUERY_FLAG_REQUEST_HEADERS
  1218.     HTTP_QUERY_FLAG_SYSTEMTIME
  1219.     HTTP_QUERY_LANGUAGE
  1220.     HTTP_QUERY_LAST_MODIFIED
  1221.     HTTP_QUERY_MESSAGE_ID
  1222.     HTTP_QUERY_MIME_VERSION
  1223.     HTTP_QUERY_PRAGMA
  1224.     HTTP_QUERY_PUBLIC
  1225.     HTTP_QUERY_RAW_HEADERS
  1226.     HTTP_QUERY_RAW_HEADERS_CRLF
  1227.     HTTP_QUERY_REQUEST_METHOD
  1228.     HTTP_QUERY_SERVER
  1229.     HTTP_QUERY_STATUS_CODE
  1230.     HTTP_QUERY_STATUS_TEXT
  1231.     HTTP_QUERY_URI
  1232.     HTTP_QUERY_USER_AGENT
  1233.     HTTP_QUERY_VERSION
  1234.     HTTP_QUERY_WWW_LINK
  1235.     ICU_BROWSER_MODE
  1236.     ICU_DECODE
  1237.     ICU_ENCODE_SPACES_ONLY
  1238.     ICU_ESCAPE
  1239.     ICU_NO_ENCODE
  1240.     ICU_NO_META
  1241.     ICU_USERNAME
  1242.     INTERNET_CONNECT_FLAG_PASSIVE
  1243.     INTERNET_FLAG_ASYNC
  1244.     INTERNET_FLAG_HYPERLINK
  1245.     INTERNET_FLAG_KEEP_CONNECTION
  1246.     INTERNET_FLAG_MAKE_PERSISTENT
  1247.     INTERNET_FLAG_NO_AUTH
  1248.     INTERNET_FLAG_NO_AUTO_REDIRECT
  1249.     INTERNET_FLAG_NO_CACHE_WRITE
  1250.     INTERNET_FLAG_NO_COOKIES
  1251.     INTERNET_FLAG_READ_PREFETCH
  1252.     INTERNET_FLAG_RELOAD
  1253.     INTERNET_FLAG_RESYNCHRONIZE
  1254.     INTERNET_FLAG_TRANSFER_ASCII
  1255.     INTERNET_FLAG_TRANSFER_BINARY
  1256.     INTERNET_INVALID_PORT_NUMBER
  1257.     INTERNET_INVALID_STATUS_CALLBACK
  1258.     INTERNET_OPEN_TYPE_DIRECT
  1259.     INTERNET_OPEN_TYPE_PROXY
  1260.     INTERNET_OPEN_TYPE_PROXY_PRECONFIG
  1261.     INTERNET_OPTION_CONNECT_BACKOFF
  1262.     INTERNET_OPTION_CONNECT_RETRIES
  1263.     INTERNET_OPTION_CONNECT_TIMEOUT
  1264.     INTERNET_OPTION_CONTROL_SEND_TIMEOUT
  1265.     INTERNET_OPTION_CONTROL_RECEIVE_TIMEOUT
  1266.     INTERNET_OPTION_DATA_SEND_TIMEOUT
  1267.     INTERNET_OPTION_DATA_RECEIVE_TIMEOUT
  1268.     INTERNET_OPTION_HANDLE_TYPE
  1269.     INTERNET_OPTION_LISTEN_TIMEOUT
  1270.     INTERNET_OPTION_PASSWORD
  1271.     INTERNET_OPTION_READ_BUFFER_SIZE
  1272.     INTERNET_OPTION_USER_AGENT
  1273.     INTERNET_OPTION_USERNAME
  1274.     INTERNET_OPTION_VERSION
  1275.     INTERNET_OPTION_WRITE_BUFFER_SIZE
  1276.     INTERNET_SERVICE_FTP
  1277.     INTERNET_SERVICE_GOPHER
  1278.     INTERNET_SERVICE_HTTP
  1279.     INTERNET_STATUS_CLOSING_CONNECTION
  1280.     INTERNET_STATUS_CONNECTED_TO_SERVER
  1281.     INTERNET_STATUS_CONNECTING_TO_SERVER
  1282.     INTERNET_STATUS_CONNECTION_CLOSED
  1283.     INTERNET_STATUS_HANDLE_CLOSING
  1284.     INTERNET_STATUS_HANDLE_CREATED
  1285.     INTERNET_STATUS_NAME_RESOLVED
  1286.     INTERNET_STATUS_RECEIVING_RESPONSE
  1287.     INTERNET_STATUS_REDIRECT
  1288.     INTERNET_STATUS_REQUEST_COMPLETE
  1289.     INTERNET_STATUS_REQUEST_SENT
  1290.     INTERNET_STATUS_RESOLVING_NAME
  1291.     INTERNET_STATUS_RESPONSE_RECEIVED
  1292.     INTERNET_STATUS_SENDING_REQUEST</PRE>
  1293. <P>
  1294. <HR>
  1295. <H1><A NAME="version history">VERSION HISTORY</A></H1>
  1296. <UL>
  1297. <LI><STRONG><A NAME="item_081">0.081 (25 Sep 1999)</A></STRONG><BR>
  1298.  
  1299. <UL>
  1300. <LI>
  1301. Documentation converted to pod format by Jan Dubois <<A HREF="mailto:jand@activestate.com">jand@activestate.com</A>>.
  1302. <P></P>
  1303. <LI>
  1304. Minor changes from Perl 5.005xx compatibility.
  1305. <P></P></UL>
  1306. <LI><STRONG><A NAME="item_08">0.08 (14 Feb 1997)</A></STRONG><BR>
  1307.  
  1308. <UL>
  1309. <LI>
  1310. fixed 2 more bugs in <CODE>Option(s)</CODE> related subs (thanks to Brian
  1311. Helterline!).
  1312. <P></P>
  1313. <LI>
  1314. <A HREF="#item_Error"><CODE>Error()</CODE></A> now gets error messages directly from WININET.DLL.
  1315. <P></P>
  1316. <LI>
  1317. The PLL file now comes in 2 versions, one for Perl version 5.001
  1318. (build 100) and one for Perl version 5.003 (build 300 and
  1319. higher). Everybody should be happy now :)
  1320. <P></P>
  1321. <LI>
  1322. added an installation program.
  1323. <P></P></UL>
  1324. <LI><STRONG><A NAME="item_07">0.07 (10 Feb 1997)</A></STRONG><BR>
  1325.  
  1326. <UL>
  1327. <LI>
  1328. fixed a bug in <A HREF="#item_Version"><CODE>Version()</CODE></A> introduced with 0.06...
  1329. <P></P>
  1330. <LI>
  1331. completely reworked PM file, fixed *lots* of minor bugs, and removed
  1332. almost all the warnings with ``perl -w''.
  1333. <P></P></UL>
  1334. <LI><STRONG><A NAME="item_06">0.06 (26 Jan 1997)</A></STRONG><BR>
  1335.  
  1336. <UL>
  1337. <LI>
  1338. fixed another hideous bug in ``new'' (the 'class' parameter was still
  1339. missing).
  1340. <P></P>
  1341. <LI>
  1342. added support for asynchronous operations (work still in embryo).
  1343. <P></P>
  1344. <LI>
  1345. removed the ending \0 (ASCII zero) from the DLL version returned by
  1346. ``Version''.
  1347. <P></P>
  1348. <LI>
  1349. added a lot of constants.
  1350. <P></P>
  1351. <LI>
  1352. added <CODE>safefree()</CODE> after every <CODE>safemalloc()</CODE> in C... wonder why I didn't
  1353. it before :)
  1354. <P></P>
  1355. <LI>
  1356. added TimeConvert, which actually works one way only.
  1357. <P></P></UL>
  1358. <LI><STRONG><A NAME="item_05f">0.05f (29 Nov 1996)</A></STRONG><BR>
  1359.  
  1360. <UL>
  1361. <LI>
  1362. fixed a bug in ``new'' (parameters passed were simply ignored).
  1363. <P></P>
  1364. <LI>
  1365. fixed another bug: ``Chdir'' and ``Cwd'' were aliases of RMDIR instead of
  1366. CD..
  1367. <P></P></UL>
  1368. <LI><STRONG><A NAME="item_05">0.05 (29 Nov 1996)</A></STRONG><BR>
  1369.  
  1370. <UL>
  1371. <LI>
  1372. added ``CrackURL'' and ``CreateURL''.
  1373. <P></P>
  1374. <LI>
  1375. corrected an error in TEST.PL (there was a GetUserAgent instead of
  1376. UserAgent).
  1377. <P></P></UL>
  1378. <LI><STRONG><A NAME="item_04">0.04 (25 Nov 1996)</A></STRONG><BR>
  1379.  
  1380. <UL>
  1381. <LI>
  1382. added ``Version'' to retrieve package and DLL versions.
  1383. <P></P>
  1384. <LI>
  1385. added proxies and other options to ``new''.
  1386. <P></P>
  1387. <LI>
  1388. changed ``OpenRequest'' and ``Request'' to read parameters from a hash.
  1389. <P></P>
  1390. <LI>
  1391. added ``SetOption/QueryOption'' and a lot of relative functions
  1392. (connect, username, password, useragent, etc.).
  1393. <P></P>
  1394. <LI>
  1395. added ``CanonicalizeURL'' and ``CombineURL''.
  1396. <P></P>
  1397. <LI>
  1398. ``Error'' covers a wider spectrum of errors.
  1399. <P></P></UL>
  1400. <LI><STRONG><A NAME="item_02">0.02 (18 Nov 1996)</A></STRONG><BR>
  1401.  
  1402. <UL>
  1403. <LI>
  1404. added support for HTTP sessions and requests.
  1405. <P></P></UL>
  1406. <LI><STRONG><A NAME="item_01">0.01 (11 Nov 1996)</A></STRONG><BR>
  1407.  
  1408. <UL>
  1409. <LI>
  1410. fetching of HTTP, FTP and GOPHER URLs.
  1411. <P></P>
  1412. <LI>
  1413. complete set of commands to manage an FTP session.
  1414. <P></P></UL>
  1415. </UL>
  1416. <P>
  1417. <HR>
  1418. <H1><A NAME="author">AUTHOR</A></H1>
  1419. <P>Version 0.08 (14 Feb 1997) by Aldo Calpini <<A HREF="mailto:a.calpini@romagiubileo.it">a.calpini@romagiubileo.it</A>></P>
  1420. <P>
  1421. <HR>
  1422. <H1><A NAME="credits">CREDITS</A></H1>
  1423. <P>Win32::Internet is based on the Win32::Registry code written by Jesse
  1424. Dougherty.</P>
  1425. <P>Additional thanks to: Carl Tichler for his help in the initial
  1426. development; Tore Haraldsen, Brian Helterline for the bugfixes; Dave
  1427. Roth for his great source code examples.</P>
  1428. <P>
  1429. <HR>
  1430. <H1><A NAME="disclaimer">DISCLAIMER</A></H1>
  1431. <P>This program is FREE; you can redistribute, modify, disassemble, or
  1432. even reverse engineer this software at your will. Keep in mind,
  1433. however, that NOTHING IS GUARANTEED to work and everything you do is
  1434. AT YOUR OWN RISK - I will not take responsability for any damage, loss
  1435. of money and/or health that may arise from the use of this program!</P>
  1436. <P>This is distributed under the terms of Larry Wall's Artistic License.</P>
  1437. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  1438. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  1439. <STRONG><P CLASS=block> Win32::Internet - Access to WININET.DLL functions</P></STRONG>
  1440. </TD></TR>
  1441. </TABLE>
  1442.  
  1443. </BODY>
  1444.  
  1445. </HTML>
  1446.