DwinsHs_ReadRemoteURL function

DwinsHs_ReadRemoteURL function:

Downloads the given file or fetch the response immediately. Returns once the file has been downloaded, or the response has been received. The Setup window will not be frozen during downloading. If you click on the "Cancel" button or click on the window's Close button to exit the Setup wizard, the download operation will be terminated automatically.

Declaration:

type
  TReadMethod = (rmGet, rmPost, rmActive, rmPassive);
  #ifdef UNICODE// For UNICODE Inno Setup
  TOnRead = function (URL, Agent: AnsiString; Method: TReadMethod;
    Index, TotalSize, ReadSize, CurrentSize: Int64; var ReadStr: AnsiString): Boolean;
  #else // For ANSI Inno Setup
  TOnRead = function (URL, Agent: AnsiString; Method: TReadMethod;
    Index, TotalSize, ReadSize, CurrentSize: LongInt; var ReadStr: AnsiString): Boolean;
  #endif
#ifdef UNICODE // For UNICODE Inno Setup
function DwinsHs_ReadRemoteURL(URL, Agent: AnsiString; Method: TReadMethod; var Response:
  AnsiString; var Size: Int64; SaveFilename: string; OnRead: TOnRead): Integer;
#else // For ANSI Inno Setup
function DwinsHs_ReadRemoteURL(URL, Agent: AnsiString; Method: TReadMethod; var Response:
  AnsiString; var Size: LongInt; SaveFilename: string; OnRead: TOnRead): Integer;
#endif

Parameters:

URL: AnsiString
The full address of the file to download, or the address of server script to fetch its response. the "http", "https" and "ftp" schemes are supported. Optional username, password and port number can be included. For "http" and "https" schemes, an optional parameters string can be included too.
Format:
[<scheme>://][<username>[:<password>]@]<host>[:<port>] [/<path>][?<parameters>]
For example:
http://username:[email protected]:8080/images/file.jpg
https://www.mywebsite.com/license/verify.php?license_key=xxx-xxx-xxx-xxx&license_type=2
ftp://username:[email protected]:2121/images/file.jpg
Agent: AnsiString
Specifies an user agent string. Your server can use the string to determine whether the download request is sent by your installation package, or determine which installation package sends the request, etc.
Method: TReadMethod
Specifies the HTTP methods for an "http" or "https" download request. Or specifies the transfer mode for an "ftp" download request. It can be one of the following values:
- rmGet: Use the GET method, only for "http" or "https" request.
- rmPost: Use the POST method, only for "http" or "https" request.
- rmActive: Use the active FTP mode, only for "ftp" request.
- rmPassive: Use the passive FTP mode, only for "ftp" request.
Response: AnsiString
If the OnRead parameter is set to nil, or even if it is set to an OnRead callback function, but the ReadStr parameter of the callback function isn't changed in the callback function, the Response parameter returns entire file content as string. You can use the SaveStringToFile function to save it into a local file.
Size: Int64(for UNICODE) / LognInt(for ANSI)
The parameter returns size of the file or length of response at the given URL, in bytes. If you want fetch the length of response at the given URL, the Content-Length entity-header field is required on response from your server.
SaveFilename: string
Specifies a local file path and file name in order to save the remote file content or the response text into it automatically. If the parameter is set to an empty string, the file content or the response text will not be saved automatically.
Also, you can use the SaveStringToFile function to save the value of Response parameter into a local file. For example:
var
  Response: AnsiString;
  Size: {#BIG_INT};
...
if DwinsHs_ReadRemoteURL( 'http://.....', 'My_Setup', rmGet, Response, Size, '', nil )
      = READ_OK then
  SaveStringToFile( ExpandConstant('{tmp}/local_filename'), Response, False );
Or you can use the SaveStringToFile function to save all of the ReadStr parameter values of the OnRead callback function into a local file if you specify the callback function in the OnRead parameter. For example:
var
  Response: AnsiString;
  Size: {#BIG_INT};
...
function OnRead(URL, Agent: AnsiString; Method: TReadMethod; Index, TotalSize, ReadSize,
  CurrentSize: LongInt; var ReadStr: AnsiString): Boolean;
begin
  if Index = 0 then
    // Create local file and write first data block
    SaveStringToFile( ExpandConstant('{tmp}/local_filename'), ReadStr, False )
  else
    // Append subsequent data blocks to the local file
    SaveStringToFile( ExpandConstant('{tmp}/local_filename'), ReadStr, Ture );
  ReadStr := ''; // Optional, change to empty string for freeing up memory space
  Result := True; // Continue to download
end;
...
DwinsHs_ReadRemoteURL( 'http://.....', 'My_Setup', rmGet, Response, Size, '', @OnRead );
OnRead: TOnRead
You can use the parameter to specify a callback function when you make the DwinsHs_ReadRemoteURL function call, it will be executed when a data block is read from remote server. See also the OnRead callback function. If the callback function is not required, please set it to nil.

Return:

Returns the error code in integer, it can be one of the following values:

READ_OK (0): The download completes successfully.
CONNECT_ERROR_NETWORK (1): There is no Internet connection, or if all possible Internet connections are not currently active.
CONNECT_ERROR_OFFLINE (2): The computer is in offline mode.
CONNECT_ERROR_INITIALIZE (3): Failed to initialize the installation package for accessing Internet.
CONNECT_ERROR_OPENSESSION (4): Failed to open the FTP or HTTP session.
CONNECT_ERROR_CREATEREQUEST (5): Failed to create an HTTP request handle.
CONNECT_ERROR_SENDREQUEST (6): Failed to send request to the HTTP server.
READ_ERROR_DELETEFILE (7): The local file exists, and failed to delete it.
READ_ERROR_SAVEFILE (8): Failed to save data to the local file.
READ_ERROR_CANCELED (9): The download operation is terminated by user (the OnRead callback function returns false, or user clicks on the "Cancel" button or clicks on the window's Close button to exit the Setup wizard).
READ_ERROR_READDATA (10): Failed to read data from the remote URL.
Greater than or equal to 400: The HTTP status code.

If the error code is between 1 and 10, you can call the DllGetLastError function to retrieve a specific error message.

Note:

If you click on the "Cancel" button or click on the window's Close button to exit the Setup wizard, or change the value of global variable DwinsHs_CancelDownload to cdExit or cdBack, the download operation will be terminated automatically, and the function will returns the error code READ_ERROR_CANCELED (9).