OnRead callback function

OnRead callback function:

You can use the OnRead parameter to specify a callback procedure when you make the DwinsHs_ReadRemoteURL function call. The callback procedure will be executed when a data block is read by the DwinsHs_ReadRemoteURL function.

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

Parameters:

URL: AnsiString
Contains 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:password@www.mywebsite.com:8080/images/file.jpg
https://www.mywebsite.com/license/verify.php?license_key=xxx-xxx-xxx-xxx&license_type=2
ftp://username:password@www.mywebsite.com:2121/images/file.jpg
Agent: AnsiString
Contains 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
Contains the HTTP methods for an "http" or "https" download request. Or contains 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.
Index: Int64(for UNICODE) / LognInt(for ANSI)
Contains the index of data block. The index 0 denotes that current data block is first block of current remote file.
TotalSize: Int64(for UNICODE) / LognInt(for ANSI)
Contains the size of current remote file, in bytes. It can be used to calculate the download progress.
ReadSize: Int64(for UNICODE) / LognInt(for ANSI)
Contains the size of the remote file has been downloaded, in bytes. It can be used to calculate the download progress.
CurrentSize: Int64(for UNICODE) / LognInt(for ANSI)
Contains the size of current data block which read by the DwinsHs_ReadRemoteURL function, in bytes.
ReadStr: AnsiString
Contains the content of current data block which read by the DwinsHs_ReadRemoteURL function.
All of the data blocks in each callback will be concatenated as a single string (the entire content of the remote file). After the download completes and the DwinsHs_ReadRemoteURL function returns, the single string will be returned in the Response parameter of the DwinsHs_ReadRemoteURL function. If the SaveFilename parameter of DwinsHs_ReadRemoteURL function isn't set to empty, the single string will be saved as a local file which specified by the SaveFilename parameter, too.
You can change the value of the parameter, the new value will be used to concatenated to the single string. After the download completes and the DwinsHs_ReadRemoteURL function returns, the single string will be returned in the Response parameter of the DwinsHs_ReadRemoteURL function. If the SaveFilename parameter of DwinsHs_ReadRemoteURL function isn't set to empty, the single string concatenated using original strings will be saved as a local file which specified by the SaveFilename parameter. In other words, the original remote file will be saved.

Return:

Returns true to continue to download the remote file. Retunrs false to terminate the download operation, the DwinsHs_ReadRemoteURL function will return immediately, and the error code READ_ERROR_CANCELED (9) will be returned by it.

Examples:

You can use the callback procedure to save the remote file:

var
  Response: AnsiString;
  Size: {#BIG_INT};
...
function OnRead(URL, Agent: AnsiString; Method: TReadMethod; Index, TotalSize, ReadSize,
  CurrentSize: {#BIG_INT}; varReadStr: 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);

The callback function can be used to update the progress indicator, for example:

var
  ProgressBar: TNewProgressBar;
  Response: AnsiString;
  Size: {#BIG_INT};
...
function OnRead(URL, Agent: AnsiString; Method: TReadMethod; Index, TotalSize, ReadSize,
  CurrentSize: {#BIG_INT}; varReadStr: AnsiString): Boolean;
begin
  ProgressBar.Position := (ReadSize div TotalSize) * 100;
  Result := True;
end;
...
ProgressBar := TNewProgressBar.Create(...);
ProgressBar.Min := 0;
ProgressBar.Max := 100;
ProgressBar.Position := 0;
DwinsHs_ReadRemoteURL('http://.....', 'My_Setup', rmGet, Response, Size,
  ExpandConstant('{tmp}/local_filename'), @OnRead);

It can be used to encrypt or decrypt file content or response text too, for example:

var
  Response: AnsiString;
  Size: {#BIG_INT};
...
function OnRead(URL, Agent: AnsiString; Method: TReadMethod; Index, TotalSize, ReadSize,
  CurrentSize: {#BIG_INT}; varReadStr: AnsiString): Boolean;
var
  i: Integer;
begin
  // Simple to encrype the file content
  for i := 1 to ReadSize do ReadStr[i] := Chr(Ord(ReadStr[i]) xor $55);
  Result := True;
end;
...
if DwinsHs_ReadRemoteURL( 'http://.....', 'My_Setup', rmGet, Response, Size, '', @OnReaded )
      = READ_OK then
  SaveStringToFile( ExpandConstant('{tmp}/local_filename'), Response, False );

Also, it can be used to check whether the user terminates the download operation, for example:

var
  Response: AnsiString;
  Size: {#BIG_INT};
  Canceled: Boolean;
...
function BackButtonClick(CurPageID: Integer): Boolean;
begin
  Result := True;
  // Terminates download operation when user clicks on the "Back" button
  Canceled := True;
end;
...
function OnReaded(URL, Agent: AnsiString; Method: TReadMethod; Index, TotalSize, ReadSize,
  CurrentSize: {#BIG_INT}; varReadedStr: AnsiString): Boolean;
begin
  Result := not Canceled;
end;
...
Canceled := False;
DwinsHs_ReadRemoteURL('http://.....', 'My_Setup', rmGet, Response, Size,
  ExpandConstant('{tmp}/local_filename'), @OnReaded);
...