Class TCastleDownload

Note that this may destroy our own instance. So never access our own fields / virtual methods after calling this.

This item has no description.

This item has no description.

Get the data. This starts downloading. Be sure to set Url and other necessary properties before calling this.

Wait until status is no longer dsDownloading.

Form data to send when HttpMethod = hmPost. Initially empty. Use the TStrings name/value mechanism to set the form, like

// Advised:
Download.HttpPostData.Values['my-form-key'] := 'my-form-value';
// This also works, it is equivalent to above if key didn't already exist
Download.HttpPostData.Append('my-form-key-2=my-form-value-2');

Warning: this symbol is deprecated: use HttpPostData

This item has no description.

Request body to send along with the request. Most useful with PUT (to send data to save on the server side). May also be useful with POST (only when the HttpPostData key-value is not flexible enough) or other requests.

You can use various TStream methods to set the stream, like TStream.CopyFrom. The CastleClassUtils also has various helpers for stream, e.g. to write a String (AnsiString, UTF-8 encoding) to a stream use WriteStr(Download.HttpRequestBody, 'My content').

Example usage:

program put_data;

{ Send PUT request with JSON body.
  Note: to send non-trivial JSON, better create it with proper JSON library
  like FpJson. }

{$apptype console}

uses
  {$ifdef UNIX} CThreads, {$endif} // necessary to have asynchronous downloading on Unix
  SysUtils,
  {$ifdef FPC} OpenSSLSockets, {$endif} // support HTTPS
  CastleUtils, CastleDownload, CastleClassUtils;

var
  D: TCastleDownload;
begin
  D := TCastleDownload.Create(nil);
  try
    D.Url := 'https://castle-engine.io/miscella/test_put.php';
    D.HttpMethod := hmPut;
    WriteStr(D.HttpRequestBody, '{ "test": "value" }');
    D.Start;
    D.WaitForFinish;
    case D.Status of
      dsError: Writeln('Error: ', D.ErrorMessage);
      dsSuccess: Writeln('Success');
      else raise EInternalError.Create('Unexpected status');
    end;
    Writeln('Response code: ', D.HttpResponseCode);
    Writeln('Response body: ', ReadGrowingStreamToDefaultString(D.Contents));
  finally FreeAndNil(D) end;
end.

Note: For some requests you may want to add HTTP headers like Content-Type etc. Do this using HttpHeader.

In case of POST requests, when this stream has non-empty contents (stream size > 0), it overrules the HttpPostData. That is, HttpPostData is completely ignored in this case. Reason: Internally, HttpPostData is just an alternative way to set HttpRequestBody.

TODO: We may change this behavior in the future, to make it such that using HttpPostData will automatically set also HttpRequestBody contents to represent the given POST data, immediately. This way the "overriding" will be "whatever is set last, wins". For now, never use both HttpPostData and HttpRequestBody at the same time.

TODO: For now this is supported only when using FPC (not Delphi), on desktop or Android platforms (not iOS yet). It should be trivial to make it work in other cases too, just let us know ( https://castle-engine.io/talk.php ).

Add additional HTTP headers, e.g. User-Agent.

Warning: this symbol is deprecated: use HttpHeader

This item has no description.

URL to read or write. Supports all protocols, like file, http, https, castle-data and other documented on https://castle-engine.io/manual_network.php .

Can only change when there is no download in progress (Status is dsNotStarted or dsSuccess).

When the download has finished (with success or error), this is updated to "final" URL, after resolving HTTP/HTTPS redirects and castle-data:/ protocol.

Options that configure the output stream. See TStreamOption for details.

In case of HTTP and HTTPS protocols, choose the http request method (verb). See https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods and https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods for description.

Can only change when there is no download in progress (Status is not dsDownloading).

Event called when we finish downloading.

Can only change when there is no download in progress (Status is not dsDownloading).

Whether we finished the download (and if yes, was it an error or success).

If the Status is dsError, this contains a detailed error message.

The downloaded contents.

If the Status is dsSuccess, this is always set (never Nil). In case of some protocols and some failures, the contents may be available (not Nil) even when error occurred, that is when Status is dsError. E.g. when HTTP server returns an error, like 404, it also still sends the response contents.

This stream is owned by default (if OwnsContents) by this TCastleDownload instance, so it will become invalid when the TCastleDownload instance is freed.

Is the Contents owned by this TCastleDownload instance. Set this to False to be able to free this TCastleDownload instance and still keep the stream reference. It is your responsibility then to keep and free the Contents stream whenever you want.

How many bytes were downloaded. Together with TotalBytes, you can use it e.g. to show a progress bar when downloading. This is always >= 0.

How many bytes are expected to be downloaded, in total. -1 if unknown. Depending on the server answer, this may be known fairly quickly after starting the download, or if may not be known at all (until we finish the download). It's guaranteed that this is known (not -1) when Status = dsSuccess, in all other cases always be prepared that this may be equal -1.

As soon as the MIME type of the downloaded contents is known, this is set. It is guaranteed to be set when Status is dsSuccess, it *may* be determined earlier (when dsDownloading).

When Status is dsSuccess or dsError, and request was using HTTP or HTTPS, this contains the HTTP status code. It is always 200 on success.

When Status is dsSuccess or dsError, and request was using HTTP or HTTPS, this contains the HTTP response headers. The NameValueSeparator is set to ':' which means you can use TStrings name/value mechanism to read the data, like this:

LastModified := Download.HttpResponseHeaders.Values['Last-Modified'];

Note that it is Nil in case of non-HTTP/HTTPS requests.