Home     Products      Support      Corporate     Sign In 
Support Knowledge Base, Article 1158
Product
XFile
Version
2.2.3 and higher (SAXFile.dll v2.2.3, XFileEE.dll 2.2.3)
Title
How to use XFile's Transfer Events in an Upload
Problem
Prior to version 2.2.3 of XFile all events available to XFile reflected client-side activity. With the introduction of the TransferStatusChange event, one has the ability to connect to events that occur after the client (XFile) has finished sending the request. This article will compare and contrast existing events with the TransferStatusChange event. Use of this new event will be demonstrated with the XFRequest object (transfer engine, non-visual) and the AXFFile object (GUI, visual).
Solution
What Transfer Events Are Available, and When Do They Occur?
  1. Events Available Prior to Version 2.2.3
    These events only represent client-side activity, meaning from the time XFile begins to send the Request, to when the Request has completely been sent by XFile. These events do not represent server-side events.

    Object Name Event Name Occurs
    XFRequest TransferStart When the data transfer is initiated
      TransferProgress
    • After the transfer of each 16 kilobytes or the value of the BufferSize property
    • At the beginning of the transfer of each file
      TransferComplete After the Request has completely left the client
      TransferError If an error occurs client-side while the Request is being made
    AXFFile OnTransferComplete After the Request has completely left the client
      OnTransferError If an error occurs client-side while the Request is being made

     

  2. The TransferStatusChange Event
    This event was introduced in version 2.2.3 and encompasses the round-trip, from client to server back to the client.

    Object Name Code Enumerator Message
    XFRequest      
      0 Initializing XFile is initializing
      1 TransferStarting Transfer is Starting
      3 RequestStarting A Request is being sent to the server
      4 RequestComplete Finished sending Request to the server
      5 RetrievingResponse Retrieving Response from the server
      6 ResponseRetrieved Response retrieved from the server
      7 TransferComplete Transfer is complete
      8 TransferCancelled Transfer has been cancelled
      9 TransferError An error occurred
      10 TransferTimedOut Transfer has timed out
      11 TransferDataStarting Transfering Form Elements to Server Starting
      12 TransferDataComplete Transfering Form Elements to Server Complete
      13 TransferFilesStarting Upload of the Files is Starting
      14 TransferFilesComplete Upload of the Files is Complete
      15 TransferFileStarting Upload of the File is Starting
      16 TransferFileComplete Upload of the File is Complete
      17 Connecting Connecting to server
    AXFFILE Requires a routine to link to the XFRequest object's TransferStatusChange event.
      same codes as above same enums as above same messages as above


In What Order do the Events Occur?

The following table is generated by recording all of the events that are triggered by uploading two files with the XFRequest object. The table can be used to compare when the different events occur and in what order. The code for generating this table is available as an attachment to this article. A similar code sample is provided for the AXFFile object.

Round Trip Event Handlers Client Side Events
TransferStatusChange Event Code: 0, XFile is initializing    
TransferStatusChange Event Code: 1, Transfer is Starting    
TransferStatusChange Event Code: 17, Connecting to server    
    TransferStart Event POST 2 Files
TransferStatusChange Event Code: 3, A Request is being sent to the server    
TransferStatusChange Event Code: 13, Upload of the Files is Starting    
TransferStatusChange Event Code: 15, Upload of the File is Starting    
    TransferProgress Event
Current File: C:\test1.txt
Bytes Transferred From This File: 0
Total Bytes of This File: 1436
Total Bytes Transferred: 156
Total Bytes: 3523
    TransferProgress Event
Current File: C:\test1.txt
Bytes Transferred From This File: 1436
Total Bytes of This File: 1436
Total Bytes Transferred: 1592
Total Bytes: 3523
TransferStatusChange Event Code: 16, Upload of the File is Complete    
TransferStatusChange Event Code: 15, Upload of the File is Starting    
    TransferProgress Event
Current File: c:\test2.txt
Bytes Transferred From This File: 0
Total Bytes of This File: 1719
Total Bytes Transferred: 1750
Total Bytes: 3523
    TransferProgress Event
Current File: c:\test2.txt
Bytes Transferred From This File: 1719
Total Bytes of This File: 1719
Total Bytes Transferred: 3469
Total Bytes: 3523
TransferStatusChange Event Code: 16, Upload of the File is Complete    
TransferStatusChange Event Code: 14, Upload of the Files is Complete    
    TransferProgress Event
Current File: c:\test2.txt
Bytes Transferred From This File: 1719
Total Bytes of This File: 1719
Total Bytes Transferred: 3523
Total Bytes: 3523
    TransferProgress Event
Current File: c:\test2.txt
Bytes Transferred From This File: 1719
Total Bytes of This File: 1719
Total Bytes Transferred: 3523
Total Bytes: 3523
TransferStatusChange Event Code: 4, Finished sending Request to the server    
    TransferComplete Event Indicates that the Request has completely left the client.
TransferStatusChange Event Code: 5, Retrieving Response from the server    
TransferStatusChange Event Code: 6, Response retrieved from the server    
TransferStatusChange Event Code: 7, Transfer is complete    


How are the Events used?

The events are placed into your client-script in the following manner:


 <SCRIPT language='vbs'>
  Sub [XFile object name]_[Name of Event]([parameters])
    ...your code here ...
  End Sub
 </SCRIPT>

  • Demonstration: Use the TransferStatusChange Event to notify the User when the complete transfer is finished. XFile object used: Transfer-Engine only (XFRequest).

    Instantiate the XFRequest object in the <BODY> tag of your HTML code. <OBJECT CLASSID="clsid:C3A57B60-C117-11D2-BD9B-00105A0A7E89"
         codebase="http://DomainName/XFileApplicationDirectory/SAXFile.cab"
         ID="XFILE">
    </OBJECT>

    In a <SCRIPT> tag, provide the event handler for the TransferStatusChange event. Note, than since ID attribute of XFile's object tag has the value of "XFILE", your event handler will be pre-pended with "XFILE_".

     <SCRIPT language = 'vbs'>
     Sub XFILE_TransferStatusChange( ByVal code, ByVal Message )
       If code = 7 then
         msgbox Message
       End if
     </SCRIPT>
     End Sub

    In the above code snippet, if the TransferStatusChange event handler receives a status code of "7", it will display the associated message, "Transfer is complete" in a pop-up message box.

  • Demonstration: Use the StatusTransferChange Event to notify the User when the complete transfer is finished. XFile object used: Visual Upload Control/GUI (AXFFile).

    The TransferStatusChange event represents work done by the Transfer Engine (the XFRequest object). XFile's visual control does not have direct access to this event, so you must call a method to add the event handler and create a subroutine that matches the signature of
    TransferStatusChange(Code As Integer, Message As String)
    that will be called by the XFRequest object when a TransferStatusChange event occurs.

    Instantiate the AXFFILE object in the <BODY> tag of your HTML code.

     <OBJECT classid="CLSID:230C3D02-DA27-11D2-8612-00A0C93EEA3C"
         height="200"
         codebase="http://DomainName/XFileApplicationDirectory/SAXFile.cab"
         id="GUI_XFILE"
         style="HEIGHT: 200px; LEFT: 0px; TOP: 0px; WIDTH: 400px"
         width="400"
         VIEWASTEXT>

        <!-- DISABLE the upload button so that we can create our own and run code off of it -->

         <PARAM NAME="EnableUploadButton" VALUE="0">
     </OBJECT>

     <INPUT Type=Button Name="UploadButton" value="Start Upload">

    Create a subroutine that will function as an event handler. It can be named as you choose, but it must be able to accept two parameters to accomodate the event code and event message.

    
    
      <SCRIPT language='vbs'>
         '--- This is the sub we will use to handle the XFRequest object's TransferStatusChange events.
         '--- This sub needs to be able to handle 
         '--- the same parameters as that event it is linked to: 
         '--- the code and the message returned from the XFRequest's
         '--- TransferStatusChange event
    
         Sub DisplayTheStatusChanges(code,message)
    	  If code = 7 then
                   msgbox message
               End if			
         End Sub
      </SCRIPT>
    
    
    
    

    Call the AddTransferStatusChangeEventHandler method of the XFRequest object. Pass it the name of the subroutine that will handle the events. By doing so, the events can now be reported even though the Start method is being called on the AXFFile object.

    
      <SCRIPT language = 'vbs'>
         Sub UploadButton_onClick()
    
            '--- Set the URL where we want to send the data by
            '--- using the CurrentURL property
    
             Dim XFILE
    	Set XFILE = GUI_XFILE.XFRequest
             XFILE.AddTransferStatusChangeEventHandler(GetRef("DisplayTheStatusChanges"))
             
             ...other xfile code
    
             GUI_XFILE.Start
         End Sub
      </SCRIPT>
    
    

Attachments
Attachments/KB1158_Samples.zip
Created : 7/29/2005 5:42:02 PM (last modified : 1/25/2006 2:00:31 PM)
Rate this article!
 
Comments