Class TCastleDownload

Description

Hierarchy

Fields

Methods

Properties

Unit

CastleDownload

Declaration

type TCastleDownload = class(TComponent)

Description

Download an URL asynchronously, without blocking the application. You can register a callback OnFinish or watch when the Status property changes from dsDownloading to dsError or dsSuccess to detect when this finished downloading.

See the example https://github.com/castle-engine/castle-engine/blob/master/examples/network/asynchronous_download/ .

Features:

The download can be observed (looking at Status, DownloadedBytes, TotalBytes).
When the downlad is finished, look at Contents (if success) or ErrorMessage (if error, that is Status = dsError).
We can read MIME type from server (can be used throughout our engine to designate file type).
For downloading over HTTP, this is a way to make a full-featured HTTP(S) web request. You can specify HttpMethod, like GET, POST, PUT etc. For POST, you can provide form data as PostData. Arbitrary HTTP headers can be specified using AddHeader.

The download starts when you call Start. Be sure to configure the properties, including OnFinish, before calling Start, because in case of some protocols Start may immediately read everything and finish. When the download ends, the OnFinish is called and Status changes.

You can always just free an instance of this class, this will break the download immediately, if it's still in-progress.

The download continues while your application is running, because we use ApplicationProperties.OnUpdate mechanism. If your application uses TCastleWindow or TCastleControl, then this just works. Note that if you just want to wait for download to finish, you can use WaitForFinish method or just call simpler Download routine.

Do not worry whether this uses threads (or not) internally. All the methods and properties of this class should be accessed from the main thread, the same thread you use for all Castle Game Engine functions. And the OnFinish is called in the main thread, so you can handle it without worrying about threading.

Hierarchy

TObject
TPersistent
TComponent
TCastleDownload

Overview

Methods

	`procedure DoFinish; virtual;`
	`destructor Destroy; override;`
	`procedure Start;`
	`procedure WaitForFinish;`
	`function HttpPostData: TStrings;`
	`function PostData: TStrings; deprecated 'use HttpPostData';`
	`procedure HttpHeader(const AKey, AValue: String);`
	`procedure AddHeader(const AKey, AValue: String); deprecated 'use HttpHeader';`

Properties

	`property Url: String read FUrl write SetUrl;`
	`property FinalUrl: String read FFinalUrl;`
	`property Options: TStreamOptions read FOptions write SetOptions;`
	`property HttpMethod: THttpMethod read FHttpMethod write SetHttpMethod default hmGet;`
	`property OnFinish: TDownloadFinishedEvent read FOnFinish write SetOnFinish;`
	`property Status: TDownloadStatus read FStatus;`
	`property ErrorMessage: String read FErrorMessage;`
	`property Contents: TStream read FContents;`
	`property OwnsContents: boolean read FOwnsContents write FOwnsContents;`
	`property DownloadedBytes: Int64 read FDownloadedBytes;`
	`property TotalBytes: Int64 read FTotalBytes;`
	`property MimeType: String read FMimeType;`
	`property HttpResponseCode: Integer read FHttpResponseCode;`
	`property HttpResponseHeaders: TStrings read FHttpResponseHeaders;`

Description

Methods

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

	`destructor Destroy; override;`

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

	`procedure WaitForFinish;`
Wait until status is no longer dsDownloading.

function HttpPostData: TStrings;

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');

	`function PostData: TStrings; deprecated 'use HttpPostData';`
Warning: this symbol is deprecated: use HttpPostData

	`procedure HttpHeader(const AKey, AValue: String);`
Add additional HTTP headers, e.g. User-Agent.

	`procedure AddHeader(const AKey, AValue: String); deprecated 'use HttpHeader';`
Warning: this symbol is deprecated: use HttpHeader

Properties

property Url: String read FUrl write SetUrl;

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).

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

	`property Options: TStreamOptions read FOptions write SetOptions;`
`Options` that configure the output stream. See TStreamOption for details.

property HttpMethod: THttpMethod read FHttpMethod write SetHttpMethod default hmGet;

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).

property OnFinish: TDownloadFinishedEvent read FOnFinish write SetOnFinish;

Event called when we finish downloading.

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

	`property Status: TDownloadStatus read FStatus;`
Whether we finished the download (and if yes, was it an error or success).

	`property ErrorMessage: String read FErrorMessage;`
If the Status is dsError, this contains a detailed error message.

property Contents: TStream read FContents;

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.

	`property OwnsContents: boolean read FOwnsContents write FOwnsContents;`
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.

	`property DownloadedBytes: Int64 read FDownloadedBytes;`
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.

	`property TotalBytes: Int64 read FTotalBytes;`
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.

	`property MimeType: String read FMimeType;`
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).

	`property HttpResponseCode: Integer read FHttpResponseCode;`
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.

property HttpResponseHeaders: TStrings read FHttpResponseHeaders;

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.

Generated by PasDoc 0.16.0.