compile insert rti_HTTP_Download_Equates
/*
   ** Copyright (C) 2013-2019 Revelation Software Inc. All Rights Reserved **
   
   Author   : Mr C
   Date     : June 2019
   Purpose  : Equates for use with the RTI_HTTP_DOWNLOAD stored procedure
   
   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/required **] 
                  
                      Callback token for the download to return to the parent 
                      window's ENDDIALOG event as the AsyncID parameter. 
                      
                  <4> CallbackProc [optional/required **] 
                  
                      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.  See "Callback details" below for more info.
                   
                  <6> Loading 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.
                     
                     
              ** Note: If you don't specify EndDialogAsyncID or 
                 CallbackProc in uiParams you will not be notified 
                 of the result of the download.

                   
   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) "uiParams" has been added so we can specify UI information.
         
      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 via the parent window's ENDDIALOG event or the 
         specified callback proc, unless a responseFile name was specified,
         in which case the contents are writtent there instead.
         
      4) This routine returns a simple boolean value. There is no 
         "ResponseText" property as such, and because this is asynchronous 
         the actual response content is returned directly via the parent 
         window's ENDDIALOG event or the specified callback proc.
         
       
   Amended  Date        Reason
   =======  ====        ======

*/
///////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////
#ifndef _RTI_HTTP_DOWNLOAD_EQUATES_
#define _RTI_HTTP_DOWNLOAD_EQUATES_
///////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////

   declare function rti_HTTP_Download

///////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////
/*
   Example for using with the ENDDIALOG event on a parent window:
   
   
      url      = "https://www.revelation.com"
      method   = "GET"
      
      // AsyncID is just a string you set that is passed back with the response 
      // so that you can recognize it easily in the ENDDIALOG event.  it can 
      // be anything you wish - for example we're just using the URL along 
      // with a "$HTTPRESPONSE:" prefix here.
      
      asyncID  = "$HTTPRESPONSE:: "url"
      
      uiParams = ""
      uiParams<HDL_UIPARAM_POS_PARENTWIN$>         = @window
      uiParams<HDL_UIPARAM_POS_MODAL$>             = TRUE$
      uiParams<HDL_UIPARAM_POS_ENDDIALOGASYNCID$>  = asyncID
      uiParams<HDL_UIPARAM_POS_DOWNLOADTEXT$>      = "Getting Rev homepage"
      uiParams<HDL_UIPARAM_POS_SYNCPROGRESS$>      = TRUE$
      
      call rti_HTTP_Download( uiParams, url, method )
      
      
    Example for using a stored procedure callback - in this case 
    
      url      = "https://www.revelation.com"
      method   = "GET"
      
      // CallBackID is just a string you set that is passed back with the  
      // response so that you can recognize it easily in the ENDDIALOG event. 
      // It canbe anything you wish - for example we're just using the URL  
      // along with a "$HTTPRESPONSE:" prefix here:
      
      callBackID  = "$HTTPRESPONSE:: "url"
      
      uiParams = ""
      uiParams<HDL_UIPARAM_POS_PARENTWIN$>         = @window
      uiParams<HDL_UIPARAM_POS_MODAL$>             = TRUE$
      uiParams<HDL_UIPARAM_POS_CALLBACKPROC$>      = "MY_HTTP_RESPONSE_HANDLER"
      uiParams<HDL_UIPARAM_POS_CALLBACKID$>        = callBackID
      uiParams<HDL_UIPARAM_POS_DOWNLOADTEXT$>      = "Getting Rev homepage"
      uiParams<HDL_UIPARAM_POS_SYNCPROGRESS$>      = TRUE$
      
      call rti_HTTP_Download( uiParams, url, method )
*/
///////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////

   // uiParams constants
   //
   // <1> ParentWin
   // <2> Modal Flag
   // <3> EndDialogAsyncID
   // <4> CallbackProc
   // <5> CallbackID
   // <6> Download Text
   // <7> SyncProgress
   // <8> Hide UI
   
   equ HDL_UIPARAM_POS_PARENTWIN$        to 1
   equ HDL_UIPARAM_POS_MODAL$            to 2
   equ HDL_UIPARAM_POS_ENDDIALOGASYNCID$ to 3
   equ HDL_UIPARAM_POS_CALLBACKPROC$     to 4
   equ HDL_UIPARAM_POS_CALLBACKID$       to 5
   equ HDL_UIPARAM_POS_DOWNLOADTEXT$     to 6
   equ HDL_UIPARAM_POS_SYNCPROGRESS$     to 7
   equ HDL_UIPARAM_POS_HIDEUI$           to 8
   
   // credentials constants
   
   equ HDL_CRED_POS_USERNAME$            to 1
   equ HDL_CRED_POS_PASSWORD$            to 2
   
   // headers constants 
   
   equ HDL_HDR_POS_NAMES$                to 1
   equ HDL_HDR_POS_VALUES$               to 2
   
///////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////

   // Callback details
   // =================
   //
   // When the download dialog calls back to the target event or proc it 
   // passes two items of infomation:
   //
   //    1) The response content
   //    2) An array of response information:
   //
   //          <1> AsyncID or CallBackID
   //          <2> Response Status Code
   //          <3> Response Status Text
   //          <4> Content Length
   //          <5> Response Headers
   //          <6> Bytes Received
   //
   //
   // If calling back to the ENDDIALOG event the response content is passed  
   // in the "dialogValue" parameter, and the response info is passed in the 
   // "asyncID" parameter
   //
   //    call post_Event( parentID, "ENDDIALOG", @window, responseContent, responseInfo )
   //
   // If calling back to a stored procedure the responseInfo is passed as the
   // first parameter, and the responseContent as the second:
   //
   //    call @procID( responseInfo, responseContent )
   
   equ HDL_RSPINFO_POS_ID$              to 1
   equ HDL_RSPINFO_POS_STATUSCODE$      to 2
   equ HDL_RSPINFO_POS_STATUSTEXT$      to 3
   equ HDL_RSPINFO_POS_CONTENTLEN$      to 4
   equ HDL_RSPINFO_POS_HEADERS$         to 5
   equ HDL_RSPINFO_POS_BYTESRECEIVED$   to 6
   
///////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////
#endif
///////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////