Downloading Data Asynchronously

See Also

Asynchronous downloading is like the process of having a pizza delivered to your home. You first make a call to a pizza place and place an order. You then go about your business while others make the pizza. When the pizza is ready, a delivery person knocks on your door and informs you that your dinner has arrived.

With the UserDocument, the equivalent of the phone call is the AsyncRead method. Consequently, the AsyncReadComplete event is the equivalent of the pizza delivery person's knock on your door. This may be easier to understand in a simple scenario: loading a text file into a TextBox control.

To asynchronously load a Picture object into a PictureBox control

1. Press ctrl+n to begin a new project.
   
   
2. Click ActiveX Document DLL to start a new ActiveX DLL project.
   
   
3. In the Project Explorer window, double-click the UserDocument1 icon to open its designer.
   
   
4. On the Toolbox, click the TextBox control icon and draw a TextBox control on the designer. Set the MultiLine property to True.
   
   
5. Double-click the UserDocument designer to open its code window.
   
   
6. Add the following code to InitProperties event:

   Private Sub UserDocument_InitProperties()
   Dim strPath As String ' file path
   ' Change the path to a different text file if you
   ' wish. If you are on an intranet, you can
   ' also set the path to another computer on
   ' which you have access privileges.
   strPath = "c:\Windows\Readme.txt"
   ' Now invoke the AsyncRead method. Set the
   ' type to vbAsyncTypeFile (a file), and the
   ' name of the property to Pizza.
   UserDocument.AsyncRead strPath, _
   vbAsyncTypeFile,  "Pizza"
   End Sub
   

   The preceding code is the "Pizza call." We gave the third argument (the property name argument) a distinctive name.

7. Add the following code to the designer. This code is the "knock on the door." It informs you that your "pizza" has arrived, and you should deal with it:

   Private Sub UserDocument AsyncReadComplete _
   (AsyncProp As VB.AsyncProperty)
   Dim FileNum as Long
   
   ' Use a Select Case statement to determine which
   ' property is being delivered.
   Select Case AsyncProp.PropertyName
   Case "Pizza"
   
   ' Open the file and read the contents
   ' into the TextBox
   FileNum = FreeFile
   Open AsyncProp.Value For Input As FileNum
   Text1.Text  = Input(LOF(FileNum), FileNum)
   Close Filenum
   End Select
   End Sub
   

8. Press f5 to run the project.
   
   
9. Internet Explorer (or your default browser) will open and display your .vbd file. If you have used a file on your own computer, the call will happen too quickly for you to perceive any delay. However, if you have access to a larger file on a remote computer, the effect may be more noticeable.

To take our pizza delivery example one step further, imagine that there is a guarantee that the pizza will be delivered within 30 minutes or it’s free. In this case, you might be very interested in the progress of the pizza delivery person. You can check on the progress of your "pizza" by adding code to the AsyncReadProgress event:

Private Sub UserDocument AsyncReadProgress _
(AsyncProp As VB.AsyncProperty)
   ' Use a Select Case statement to read the StatusCode
   Select Case AsynchProp.StatusCode
      Case vbAsynchStatusCodeSendingRequest
         MsgBox "Attempting to connect"
      Case vbAsynchStatusCodeEndDownloadData
         MsgBox "Download complete"
      Case vbAsynchStatusCodeError
         MsgBox "Error – aborting transfer"
         CancelAsynchRead "Pizza"
   End Select
End Sub

Now when you run the project, the code in the AsyncReadProgress event will display two message boxes: first when an attempt is made to connect to the file, and then when the transfer is complete. If you set a breakpoint on the Select Case statement and step through the code, you’ll notice that the vbAsynchStatusEndDownloadData status code is returned before the AsyncReadComplete event is fired. This gives you one last chance to cancel or redirect the file (akin to refusing to answer the door when your "Pizza" arrives).

If an error occurs during the transfer (for example, losing a network connection) the vbAsyncStatusCodeError status code is returned, allowing you to call the CancelAsyncRead method to cancel the transfer and avoid a run time error.

To see a list of possible status codes returned by the AsyncReadProgress event, look at the AsyncStatusCodeConstants in the Object Browser.

For More Information   For an in-depth look at the AsyncRead method and the AsyncReadComplete and AsyncReadProgress events, see "Adding Internet Features to Controls" in "Building ActiveX Controls." Although the topic covers the UserControl object, the mechanics are identical.