<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
  <refentry id="function.ftp-async-get">
   <refnamediv>
    <refname>ftp_async_get</refname>
    <refpurpose>Retrieves a file from the FTP server asynchronly and writes it to a local file</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>ftp_async_get</methodname>
      <methodparam><type>resource</type><parameter>ftp_stream</parameter></methodparam>
      <methodparam><type>string</type><parameter>local_file</parameter></methodparam>
      <methodparam><type>string</type><parameter>remote_file</parameter></methodparam>
      <methodparam><type>int</type><parameter>mode</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>resumepos</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>ftp_async_get</function> retrieves <parameter>remote_file</parameter>
     from the FTP server, and saves it to <parameter>local_file</parameter>
     locally. The transfer <parameter>mode</parameter> specified must
     be either <constant>FTP_ASCII</constant> or
     <constant>FTP_BINARY</constant>. The difference between
     <function>ftp_get</function> is that this function retrieves the file
     asyncronously, so you can do other things in your program while the
     file is downloaded.
    </para>
    <para>
     Returns &true; on success, &false; on error.
    </para>
    <para>
     <example>
      <title><function>ftp_async_get</function> example</title>
      <programlisting role="php">
<![CDATA[
// Initate the download
$ret = ftp_async_get($my_connection, "test", "README", FTP_BINARY);
while ($ret == FTP_MOREDATA) {
   
   // Do whatever you want
   echo ".";

   // Continue downloading...
   $ret = ftp_async_continue ($my_connection);
}
if ($ret != FTP_FINISHED) {
   echo "There was an error downloading the file...";
   exit(1);
}
]]>
      </programlisting>
     </example>
     <example>
      <title>Resuming a download with <function>ftp_async_get</function></title>
      <programlisting role="php">
<![CDATA[
// Initate 
$ret = ftp_async_get ($my_connection, "test", "README", FTP_BINARY, 
                      filesize("test"));
// OR: $ret = ftp_async_get ($my_connection, "test", "README", 
//                           FTP_BINARY, FTP_AUTORESUME);
while ($ret == FTP_MOREDATA) {
   
   // Do whatever you want
   echo ".";

   // Continue downloading...
   $ret = ftp_async_continue ($my_connection);
}
if ($ret != FTP_FINISHED) {
   echo "There was an error downloading the file...";
   exit(1);
}
]]>
      </programlisting>
     </example>
     <example>
      <title>
       Resuming a download at position 100 to a new
       file with <function>ftp_async_get</function>
      </title>
      <programlisting role="php">
<![CDATA[
// Disable Autoseek
ftp_set_option ($my_connection, FTP_AUTOSEEK, FALSE);

// Initiate
$ret = ftp_async_get ($my_connection, "newfile", "README", FTP_BINARY, 100);
while ($ret == FTP_MOREDATA) {

   ...
   
   // Continue downloading...
   $ret = ftp_async_continue ($my_connection);
}
]]>
      </programlisting>
     </example>
    </para>
    <para>
     In the example above, <filename>"newfile"</filename> is 100
     bytes smaller than <filename>"README"</filename> on the FTP
     server because we started reading at offset 100. If we have
     not have disabled <constant>FTP_AUTOSEEK</constant> the first
     100 bytes of newfile will be <literal>'\0'</literal>.
    </para>
    <para>
     See also <function>ftp_async_fget</function>, 
     <function>ftp_async_continue</function>,
     <function>ftp_get</function> and <function>ftp_fget</function>.
    </para>
   </refsect1>
  </refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->