Visual Basic Reference

Visual Studio 6.0

AsyncRead Method

See Also    Example    Applies To

Initiates the asynchronous reading of data from a file or URL by a container, control, or ActiveX component.


object.AsyncRead Target, AsyncType [, PropertyName], [AsyncReadOptions]

The AsyncRead method syntax has these parts:

Part Description
object An object expression that evaluates to an object in the Applies To list.
Target A string expression specifying the location of the data. This can be a path or a URL.
AsyncType An integer expression specifying how the data is presented, as described in Settings.
PropertyName An optional string expression specifying the name of the property to be loaded. Required for differentiating between simultaneous downloads.
AsyncReadOptions An optional string expression specifying additional options for AsyncRead as described in Settings.


The settings for AsyncType are:

Setting Description
vbAsyncTypeFile The data is provided in a file created by Visual Basic.
vbAsyncTypeByteArray The data is provided as a byte array that contains the retrieved data. It is assumed that the component author knows how to handle the data.
vbAsyncTypePicture The data is provided in a Picture object.

The settings for AsyncReadOptions are:

Constant Setting Description
vbAsyncReadSynchronousDownload 1 AsyncRead doesn't return until the AsyncReadComplete event has occurred.
vbAsyncReadOfflineOperation 8 AsyncRead uses only the locally cached resource.
vbAsyncReadForceUpdate 16 AsyncRead forces a download of the resource from the server, ignoring a locally cached copy.
vbAsyncReadResynchronize 512 AsyncRead updates the locally cached copy only if the server version is newer.
vbAsyncReadGetFromCacheIfNetFail 524288 AsyncRead uses the cached copy if the server connection is unsuccessful.


The progress of a download that is requested by the AsyncRead method can be tracked by the AsyncReadProgress event. Once the data is available, the AsyncReadComplete event is raised in the object. The asynchronous read can be canceled before it is completed by calling the CancelAsyncRead method.

The PropertyName parameter is a tag, meaning that it can be any arbitrary string, since its only function is to act as an identifier for this particular data request. The value in PropertyName is used to identify the particular asynchronous read to cancel in the CancelAsyncRead method, and the value in PropertyName is also used to identify the particular asynchronous read that has completed in the AsyncReadComplete event. Only one AsyncRead event with a given PropertyName can be active at one time.

The AsyncRead method initiates an asynchronous download. The AsyncRead events fire synchronously (before this method returns) if the data is already available on the client machine. AsyncRead can raise some errors synchronously (such as "bad parameter", "unknown protocol", "UrlMon.dll missing", and so forth), so it's a good idea to have appropriate error handling code before calling AsyncRead. If the data is not available locally, then AsyncRead returns immediately and the AsyncRead events occur later.