compile function rti_HTTP_Download( uiParams, url, method, payload, credentials, headers, timeoutInfo, responseFile )
/*
   ** Copyright (C) 2013-2019 Revelation Software Inc. All Rights Reserved **
   
   Author   : Mr C
   Date     : June 2019
   Purpose  : Stored procedure to initiate an asynchronous HTTP download
   

   Parameters
   ==========
   
      uiParams    - [required] This is an @fm delimited array of UI info for the 
                    download process:
                  
                     <1> Parent Window [optional]
                     
                      ID of the parent window for the download dialog. If not 
                      specified the caller must provide a CallBackID to receive 
                      the returned response content.
                      
                     <2> Modal Flag [optional]. If TRUE then the parent window 
                         will be disabled for the duration of the download.
                         
                     <3> EndDialogAsyncID [optional] 
                     
                      Callback token for the download to return to the parent 
                      window's ENDDIALOG event as the AsyncID parameter. 
                         
                     <4> CallbackProc [optional] 
                     
                      Name of a stored procedure to call with the response data
                      if EndDialogAsyncID is not specified.  The Callback 
                      proc must support the following interface:
                      
                         proc( callbackID, responseContent )
                            
                     <5> CallbackID [optional, required for CallbackProc]
                      
                      If a CallBackProc is specified this field contains a 
                      token returned to the CallBackProc with the response
                      content
                      
                     <6> Info text [optional]
                     
                      Contains text to display in the dialog - defaults to 
                      the URL
                      
                     <7> Show Progress in Taskbar [optional]
                     
                      If TRUE$ then sync the progress bar to the parent
                      window's task bar icon.  Defaults to FALSE$.
                      
                     <8> Hide UI [optional]
                     
                      If TRUE$ then don't show the progress dialog.                          
                      
                      
      url         -  [required] Contains the URL to download from
      
      method      -  [optional] HTTP verb (GET,POST,HEAD,DELETE etc).  Defaults 
                     to "GET
                  
      payload     -  [optional] Content to send to the server as part of the 
                     request
      
      credentials -  [optional] Username and password to send to the server
                     
                        <1> Username
                        <2> Password>
                        
      headers     -  [optional] - Dynamic array of request headers to send to 
                     the server in the format:
                     
                        <1> @vm'd list of header names
                        <2> @vm'd list of header values
      
      timeoutInfo -  [optional] Timeout in milliseconds.
      
      responseFile-  [optional] Name of a file to download the response
                     content to
                      
   
   Returns
   =======
   
      TRUE$ if the download was started sucessfully, or FALSE$ otherwise.
      Error information is returned via Get/Set_Status().


   Comments
   ========
   
   This function is designed to mimic the existing OLE_GETWEBPAGE stored proc
   and provide an example of how to use the HTTPCLIENT control to provide 
   a UI for a download.  As such the arguments passed have been kept to the 
   same format as much as possible.
   
   Changes from OLE_GETWEBPAGE are:
   
      1) "parentID" has been added so we can specify a parent window for the 
         progress dialog
         
      2) "timeoutInfo" only supports a single value - the HTTPCLIENT control
         does not have separate timeout parameters for different states
         
      3) "responseBody" has been removed - the actual response  content is   
         returned directly from this this proc - there is no separate 
         responseText property as per the XMLHTTPRequest object
         
       
   Amended  Date       Reason
   =======  ====       ======
   Mr C     09 Mar 22  Implemented HDL_UIPARAM_POS_HIDEUI$ uiParam option

*/
   #pragma precomp event_precomp
   
   declare function get_Property, set_Property, exec_Method, get_Status
   declare function rti_UC, start_Window
   $insert rti_HTTP_Download_Equates
   $insert ps_HttpClient_Equates
   $insert msWin_ShowWindow_Equates
   $insert rti_Get_Proc_Info_Equates
   $insert rti_SSP_Equates
   $insert logical

   if assigned( uiParams )     else uiParams     = ""
   if assigned( url )          else url          = ""
   if assigned( method )       else method       = ""
   if assigned( payload )      else payload      = ""
   if assigned( credentials )  else credentials  = ""
   if assigned( headers )      else headers      = ""
   if assigned( timeoutInfo )  else timeoutInfo  = ""
   if assigned( responseFile ) else responseFile = ""
   
   if bLen( url ) else
      call set_Status( TRUE$, "No URL passed to the RTI_HTTP_DOWNLOAD procedure" )
      return FALSE$
   end
   
   if bLen( method ) else
      method = "GET"
   end
   
   parentID = uiParams<HDL_UIPARAM_POS_PARENTWIN$>
   if bLen( parentID ) then
      if get_Property( parentID, "HANDLE" ) else
         call set_Status( TRUE$, "Invalid parent ID " : quote( parentID ) : " passed to the RTI_HTTP_DOWNLOAD procedure" )
         return FALSE$
      end
   end
   
   procID = uiParams<HDL_UIPARAM_POS_CALLBACKPROC$>
   if blen( procID ) then
      procInfo = rti_Get_Proc_Info( procID )
      if get_Status() then
         return FALSE$
      end
      
      if ( procInfo<GPI_ARGCOUNT$> < 2 ) then
         call set_Status( TRUE$, "Invalid proc ID " : quote( procID ) : " passed to the RTI_HTTP_DOWNLOAD procedure [Invalid interface]" )
         return FALSE$
      end
      
   end
   
   call set_Status( FALSE$ )
   
   winID = start_Window( "RTI_HTTP_DOWNLOAD_UI", parentID, uiParams )
   if bLen( winID ) else
      // Error information is in SSP status
      return FALSE$
   end
   
   objxArray =        winID : ".HCL_DOWNLOAD"
   propArray =        "URL"
   dataArray =        url
   
   objxArray := @rm : winID : ".HCL_DOWNLOAD"
   propArray := @rm : "VERB"
   dataArray := @rm : rti_UC( method : "" )
   
   if bLen( credentials ) then
      objxArray := @rm : winID : ".HCL_DOWNLOAD"
      propArray := @rm : "USERNAME"
      dataArray := @rm : credentials<1>
      
      objxArray := @rm : winID : ".HCL_DOWNLOAD"
      propArray := @rm : "PASSWORD"
      dataArray := @rm : credentials<2>
   end
   
   if bLen( headers ) then
      // This is in "ARRAY" format - the control wants this in 
      // "LIST" format
      
      objxArray := @rm : winID : ".HCL_DOWNLOAD"
      propArray := @rm : "REQUESTHEADERS"
      dataArray := @rm : exec_Method( "SYSTEM", "ARRAY2LIST", headers )
      
   end
   
   if bLen( timeoutInfo ) then
      objxArray := @rm : winID : ".HCL_DOWNLOAD"
      propArray := @rm : "TIMEOUT"
      dataArray := @rm : timeoutInfo<1>
   end
   
   if bLen( responseFile ) then
      objxArray := @rm : winID : ".HCL_DOWNLOAD"
      propArray := @rm : "RESPONSEFILE"
      dataArray := @rm : responseFile
   end
   
   tmp = uiParams<HDL_UIPARAM_POS_DOWNLOADTEXT$>
   if blen( tmp ) else
      tmp = get_Property( winID : ".TXT_DOWNLOAD", "TEXT" )
   end
   swap "%1%" with url in tmp
   call set_Property_Only( winID : ".TXT_DOWNLOAD", "TEXT", tmp )
   
   if uiParams<HDL_UIPARAM_POS_HIDEUI$> else
      objxArray := @rm : winID
      propArray := @rm : "VISIBLE"
      dataArray := @rm : SW_SHOWNORMAL$
   end
   
   call set_Property( objxArray, propArray, dataArray )
   
   bVal = exec_Method( winID : ".HCL_DOWNLOAD", "OPEN" )
   if bVal else
      errorText = trim( get_Property( winID : ".HCL_DOWNLOAD", "ERRORTEXT" ) )
      
      call exec_Method( winID, "CLOSE" )
      
      if bLen( errorText ) else
         errorText = "Unknown HTTPCLIENT OPEN error"
      end
      
      call set_Status( TRUE$, errorText )
      return FALSE$
   end
   
   bVal = exec_Method( winID : ".HCL_DOWNLOAD", "SEND", payload )
   if bVal else
   
      errorText = trim( get_Property( winID : ".HCL_DOWNLOAD", "ERRORTEXT" ) )
      
      call exec_Method( winID, "CLOSE" )
      
      if bLen( errorText ) else
         errorText = "Unknown HTTPCLIENT SEND error"
      end
      
      call set_Status( TRUE$, errorText )
      return FALSE$
   end
   
return TRUE$

///////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////
