| |
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
- An optional numeric bitmask which specifies one or more options. This
argument may be any one of the following values:
| Value |
Description |
| httpTransferDefault |
This option specifies 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. |
| httpTransferConvert |
If the resource being downloaded from the server is
textual, the data is automatically converted so that the end of
line character sequence is compatible with the Windows
platform. Individual carriage return or linefeed characters are
converted to carriage return/linefeed character sequences. |
| httpTransferCompress |
This option informs the server that the client is willing
to accept compressed data. If the server supports compression
for the specified resource, then the data will be automatically
expanded before being returned to the caller. This option is
selected by default if compression has been enabled by setting
the Compression property to True. This option is ignored
if the Offset parameter is non-zero. |
- Offset
- An optional 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.
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 = HttpClient1.Connect(strHostName, 80)
If nError > 0 Then
MsgBox HttpClient1.LastErrorString, vbExclamation
Exit Sub
End If
' Download a file in the background
nError = HttpClient1.AsyncGetFile(strLocalFile, strRemoteFile)
If nError > 0 Then
MsgBox HttpClient1.LastErrorString, vbExclamation
Exit Sub
End If
See Also
TaskId Property,
AsyncPutFile Method,
TaskAbort Method,
TaskDone Method,
TaskWait Method,
OnTaskBegin Event,
OnTaskEnd Event,
OnTaskRun Event
|
|