Class TCastleDownload

Unit

CastleDownload

Declaration

type TCastleDownload = class(TComponent)

Description

Download an URL (possibly making an HTTP(S) request) 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.

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 (making a request) using HTTP, this is a handful of additional features, to support downloading from modern web servers and using REST APIs:

  • First of all, we support both HTTP and HTTPS on all platforms and compilers, through various backend (FpHttpClient, Indy, Delphi Net Client).

  • You can provide arbitrary HTTP headers using HttpHeader. For example, various REST APIs require you to provide some key to authenticate through a custom HTTP header.

  • You can specify any HttpMethod, like GET, POST, PUT and more. Default is naturally GET which is the standard method to just download the data.

  • For HTTP POST method, you can provide form data as HttpPostData.

  • You can provide input data for any request using HttpRequestBody. The most common use case is to provide a body for PUT requests, but it can be used for any request, e.g. to provide POST body overriding the HttpPostData.

  • Once the download finishes, you can read HttpResponseCode and HttpResponseHeaders.

  • By default, we follow HTTP/HTTPS redirects.

See examples:

• asynchronous_download to download resources asynchronously, downloading a few URLs and at the same time displaying an animation and progress bar.

• remote_logging to send logs to a remote server, using HTTP POST.

• put_data to send HTTP PUT request.

• And other examples in examples/network subdirectory.

Usage:

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

Source: files/castledownload_asynchronous.inc (line 96).

Hierarchy

• TObject
• TPersistent
• TComponent
• TCastleDownload

---

Generated by PasDoc 0.17.0.snapshot.