- Creating Visual Basic Components for the Web
- Making a Web-Aware ActiveX Custom Control
- Understanding Custom Controls and Asynchronous Transfer
- Working with UserControl.AsyncRead
- Downloading a Graphic
- Understanding Properties in Terms of AsyncRead
- Working with the FileSystemObject
- Compiling the Custom Control
- Packing the Custom Control
- Deploying the Custom Control with a Sample Page
- Updating the Custom Control
- Conclusion
Understanding Properties in Terms of AsyncRead
So, what are "properties" anyway? Well, in the case of using the AsyncRead method, they are a little different from what you are accustomed to with regard to programming a form in Visual Basic. Remember that the essence of asynchronous data retrieval is that distinct outgoing calls for particular pieces of data are made from the control, and that the data is returned in one continuous, mixed-up data stream. Figure 2 illustrates this point.
){kind=link}
Figure 2: Identify each call to data on the Internet with a property name.
The trick to understanding properties when using the AsyncRead method is to conceptualize a property name as an identifier for each distinct data call. Thus, if you are using three AyncRead calls to retrieve three graphics from the Internet, you could assign each call a property name, such as PropPicOne, PropPicTwo, and PropPicThree, for example. If you were using AsyncRead to get text for a headline, you could assign the property name PropHeadLine to that data call. Remember that the property names are strings and must be enclosed in quotation marks when used in the AsyncRead method.
So now we know how to assign property names to data calls in the outgoing stream, but how do we use them to sort out data in the incoming stream? This is where the UserControl_AsyncReadProgress and UserControl_AsyncReadComplete events come into play.
Working with the UserControl_AsyncReadProgress Event
The UserControl object has smarts that allow it respond to incoming data generated from AysncRead method calls by firing events that are dependent on what's going on with a particular data transmission. Incoming data can be in one of two states — either it is in the process of being downloaded, or it is downloaded and cached on the client machine. When data is in the process of being downloaded, the UserControl fires one or many AsyncReadProgress events. It's sort of like saying, "Hey, I have some data coming in, and right now its status is that I am creating a name for the cache file into which I will store the data on the hard disk." Or, the UserControl might fire the AsyncReadProgress event and say, "Hey, I am connecting to the URL you have indicated." Every time a status event occurs, an AsyncReadProgress event is fired.
The UserControl_AsyncReadProgress event procedure captures the firing of the AsyncReadProgress event. You can program this event procedure to find out which status events are being fired for each data call to which you have associated a property name. The syntax of the UserControl_AsyncReadProgress is as follows:
Private Sub UserControl_AsyncReadProgress
(AsyncProp As AsyncProperty) End Sub
The AsyncProperty Object
Notice that the event procedure passes a parameter of type AsyncProperty. The AsyncProperty object encapsulates the data associated with a given data call invoked using the AsyncRead method. The AsyncProperty object contains the following properties:
-
AsyncType is the constant that indicates the type of data transfer (vbAsyncTypePicture, for example). You read about this earlier.
-
BytesMax is the estimated number of bytes to be downloaded during the transfer.
-
BytesRead is the number of bytes that have been read at the time the event was fired.
-
PropertyName is the name of the property.
-
Status is information that the UserControl wants to communicate to you. It is dependent on the value of the StatusCode property. For example, if the StatusCode is vbAsyncStatusCodeCacheFileNameAvailable, the value of the Status property will be a string that indicates the name of the cache file that was created to store the downloaded data.
-
StatusCode is a constant value that reports a particular status. For example, vbAsyncStatusCodeError indicates that an error has occurred during the download. (Refer to your copy of Visual Basic for complete listing of the StatusCode constants.)
-
Target indicates the URL from which the data was retrieved.
-
Value is the data of default property in force.
You query the different properties of the AsyncProperty object to maintain control over the various AsyncRead calls going on in your program. The following code snippet in Listing 1 shows the UserControl_AsyncReadProgress event procedure from the program I developed for this article. The code checks to see that file names have been created for incoming data. If they have, the file names are assigned to member variables for the custom control.
Listing 1: The AsyncReadProgress Event Procedure Monitors the State of Data in the Process of Asynchronous Download
Private Sub UserControl_AsyncReadProgress
(AsyncProp As AsyncProperty)
'Check to see if a file name has been
assigned to the StatusCode
'property
If AsyncProp.StatusCode =
vbAsyncStatusCodeCacheFileNameAvailable Then
'Now check to make sure that the PropertyName for the
'AsyncProp object is the one for the poem data.
Select Case AsyncProp.PropertyName
Case PROP_POEM:
'If it is, get the name of the cache file
'that contains the poem data.
mPoemFileName = AsyncProp.Status
Case PROP_PIC:
mPicFileName = AsyncProp.Status
Case Else
'You fill in default behavior for other
'properties here
End Select
End If
End Sub
Working with the UserControl_AsyncReadComplete Event
So where are we? Well, we've used the AsyncRead method to make two requests back to an Internet server. One request asks for some text data (a poem), and the other request asks for some graphic data (my company's attractive logo). We've programmed the UserControl_AsyncReadProgress event procedure to watch for file name assignments by the UserControl. These file names are assigned to member variables of the UserControl.
So when and how do we display the data? The mechanics of displaying data take place in the UserControl_AsyncReadComplete event procedure. This event procedure captures the firing of an AysncReadComplete event. AsyncReadComplete is fired when all the data made by a particular AysncRead method call is finished being downloaded. It's as if the UserControl is saying, "Hey, I've got all the data, now what?"
We implement data display in the Control_AsyncReadComplete event procedure in two ways. The first way is to display text to use the FileSystemObject to open the temporary cache file that contains the downloaded data, and then to assign the text within the file to a Textbox control. The second way is to use the LoadPicture function to display the data from the temporary graphics file. Let's look at how to use the FileSystemObject first.