Class TCastleDownload

Unit

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.

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 TCastleWindowBase or TCastleControlBase, 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

  • TComponent
  • TCastleDownload

Overview

Methods

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

Properties

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

Description

Methods

Protected procedure DoFinish; virtual;

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

Public destructor Destroy; override;
 
Public procedure Start;

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

Public procedure WaitForFinish;

Wait until status is no longer dsDownloading.

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

Public function PostData: TStrings; deprecated 'use HttpPostData';

Warning: this symbol is deprecated: use HttpPostData

 
Public procedure HttpHeader(const AKey, AValue: String);

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

Public procedure AddHeader(const AKey, AValue: String); deprecated 'use HttpHeader';

Warning: this symbol is deprecated: use HttpHeader

 

Properties

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

Public property Options: TStreamOptions read FOptions write SetOptions;

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

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

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

Public property Status: TDownloadStatus read FStatus;

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

Public property ErrorMessage: String read FErrorMessage;

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

Public 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 ContentOwned) by this TCastleDownload instance, so it will become invalid when the TCastleDownload instance is freed.

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

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

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

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

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

Public 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'];


Generated by PasDoc 0.15.0.