AsyncGetFile Method  
 

Download a file from the server to the local system in the background.

Syntax

object.AsyncGetFile( LocalFile, RemoteFile, [Options], [Offset] )

Parameters

LocalFile
A string that specifies the file on the local system that will be created, overwritten or appended to. The file pathing and name conventions must be that of the local host.
RemoteFile
A string that specifies the file on the server that will be transferred to the local system. The file pathing and name conventions must be that of the server.
Options
A numeric bitmask which specifies one or more options. This argument may be any one of the following values:
Value Constant Description
0 ftpTransferDefault This option specifies that the default transfer mode should be used. If the local file exists, it will be overwritten with the contents of the remote file. If the Options argument is omitted, this is the transfer mode which will be used.
1 ftpTransferAppend This option specifies that if the local file exists, the contents of file on the server is appended to the local file. If the local file does not exist, it is created.
Offset
A byte offset which specifies where the file transfer should begin. The default value of zero specifies that the file transfer should start at the beginning of the file. A value greater than zero is typically used to restart a transfer that has not completed successfully. Note that specifying a non-zero offset requires that the server support the REST command to restart transfers.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

Remarks

The AsyncGetFile method will download the contents of a remote file to a file on the local system. It is similar to the GetFile method, however it retrieves the file using a background worker thread and does not block the current working thread. This enables the application to continue to perform other operations while the file is being downloaded from the server. This method requires that you explicitly establish a connection using the Connect method. All background tasks will duplicate the active connection and use it establish a secondary connection with the server to perform the file transfer. If you wish to perform multiple asynchronous file transfers from different servers, you must create an instance of the control for each server.

After this method is called, the OnTaskBegin event will be fired, indicating that the background task has begun the process of connecting to the server and performing the file transfer. As the file is downloaded, the control will periodically invoke the OnTaskRun event handler. When the transfer has completed, the OnTaskEnd event will be fired. It is not required that you implement handlers for these events.

To determine when a transfer has completed without implementing any event handlers, periodically call the TaskDone method. If you wish to block the current thread and wait for the transfer to complete, call the TaskWait method. To stop a background file transfer that is in progress, call the TaskAbort method. This will signal the background worker thread to cancel the transfer and terminate the session.

This method can be called multiple times to download more than one file in the background; however, most servers limit the number of simultaneous connections that can originate from a single IP address. The application should not make any assumptions about the sequence in which background transfers are performed or the order in which they may complete.

Example

' Establish a connection to the server
nError = FtpClient1.Connect(strHostName, 21, strUserName, strPassword)
    
If nError > 0 Then
    MsgBox FtpClient1.LastErrorString, vbExclamation
    Exit Sub
End If
    
' Download a file in the background
nError = FtpClient1.AsyncGetFile(strLocalFile, strRemoteFile)
    
If nError > 0 Then
    MsgBox FtpClient1.LastErrorString, vbExclamation
    Exit Sub
End If

See Also

TaskId Property, AsyncPutFile Method, TaskAbort Method, TaskDone Method, TaskWait Method, OnTaskBegin Event, OnTaskEnd Event, OnTaskRun Event