Castle Game Engine

Unit CastleDownload

Description
Uses
Classes, Interfaces, Objects and Records
Functions and Procedures
Types
Constants
Variables

Description

Read and write stream contents from URLs.

Uses

Overview

Classes, Interfaces, Objects and Records

Name Description
Class TUrlAsynchronousReader Implement this class, and pass to RegisterUrlProtocol, to read protocols asynchronously (such that TCastleDownload can read them asynchronously).
Class EProtocolAlreadyRegistered  
Class EDownloadError  
Class ESaveError  
Class TCastleDownload Download an URL asynchronously, without blocking the application.
Class TTextReaderWriter Common class for reading or writing a stream like a text file.
Class TTextReader Read any stream like a text file.
Class TTextWriter Write to a stream like to a text file.
Class TStringsHelper Copyright 2013-2020 Michalis Kamburelis.

Functions and Procedures

procedure RegisterUrlProtocol(const Protocol: String; const ReadEvent: TUrlReadEvent; const WriteEvent: TUrlWriteEvent; const AsynchronousReader: TUrlAsynchronousReaderClass = nil; const DetectMimeTypeFromExtension: Boolean = true);
function RegisteredUrlProtocol(const Protocol: String): Boolean;
procedure UnregisterUrlProtocol(const Protocol: String);
function Download(const Url: string; const Options: TStreamOptions = []): TStream; overload;
function Download(const Url: string; const Options: TStreamOptions; out MimeType: string): TStream; overload;
function GetEnableNetwork: Boolean; deprecated 'use EnableBlockingDownloads';
procedure SetEnableNetwork(const Value: Boolean); deprecated 'use EnableBlockingDownloads';
function URLSaveStream(const URL: string; const Options: TSaveStreamOptions = []): TStream;
function CreateReadFileStream(const URL: string): TStream; deprecated 'use Download(URL, [soForceMemoryStream])';
procedure StreamSaveToFile(Stream: TStream; const URL: string);

Types

TDownloadStatus = (...);
THttpMethod = (...);
TUrlAsynchronousReaderClass = class of TUrlAsynchronousReader;
TUrlReadEvent = function ( const Url: string; out MimeType: string): TStream of object;
TUrlWriteEvent = function(const Url: string): TStream of object;
TStreamOption = (...);
TStreamOptions = set of TStreamOption;
TDownloadFinishedEvent = procedure (const Sender: TCastleDownload; var FreeSender: Boolean) of object;
TSaveStreamOption = (...);
TSaveStreamOptions = set of TSaveStreamOption;

Variables

LogAllLoading: boolean = false;
EnableBlockingDownloads: boolean = false;
property EnableNetwork: Boolean read GetEnableNetwork write SetEnableNetwork;

Description

Functions and Procedures

procedure RegisterUrlProtocol(const Protocol: String; const ReadEvent: TUrlReadEvent; const WriteEvent: TUrlWriteEvent; const AsynchronousReader: TUrlAsynchronousReaderClass = nil; const DetectMimeTypeFromExtension: Boolean = true);

Register how we can load and/or save the URLs with given protocol. One (or even both) of given events (ReadEvent, WriteEvent) can be Nil.

Exceptions raised
EProtocolAlreadyRegistered
If the protocol handlers are already registered.
function RegisteredUrlProtocol(const Protocol: String): Boolean;

Is given protocol name registered with RegisterUrlProtocol.

procedure UnregisterUrlProtocol(const Protocol: String);

Unregister protocol, reverting the RegisterUrlProtocol.

function Download(const Url: string; const Options: TStreamOptions = []): TStream; overload;

Return a stream to read given URL. Returned stream is suitable only for reading, and the initial position is always at the beginning. Overloaded version also returns a MIME type (or '' if unknown).

Any errors are reported by raising exceptions.

All the supported URL protocols are documented in our manual: https://castle-engine.io/manual_network.php . They include:

This routine makes a synchronous (blocking) downloading. Which means that if you use a network URL (like http://...) then your application will wait until the data arrives from the Internet. There may be a timeout of the request (so your application will not hang indefinitely), but still your code (or user) have no way to cancel or watch the progress of this operation. This is why http/https support is disabled by default (see EnableBlockingDownloads). This is sometimes acceptable (e.g. if you're waiting during the "loading" process, and the data just has to be downloaded in order to continue), and it's really easy to use (you just download data exactly the same way like you open a local file).

You can use asynchronous downloading through the TCastleDownload class instead.

Exceptions raised
EDownloadError
In case of problems loading from this URL.

Any exceptions inside internal loading routines, like EFOpenError or EStreamError, are internally caught and changed to EDownloadError.

function Download(const Url: string; const Options: TStreamOptions; out MimeType: string): TStream; overload;
 
function GetEnableNetwork: Boolean; deprecated 'use EnableBlockingDownloads';

Warning: this symbol is deprecated: use EnableBlockingDownloads

 
procedure SetEnableNetwork(const Value: Boolean); deprecated 'use EnableBlockingDownloads';

Warning: this symbol is deprecated: use EnableBlockingDownloads

 
function URLSaveStream(const URL: string; const Options: TSaveStreamOptions = []): TStream;

Create a stream to save a given URL, for example create a TFileStream to save a file for a file URL. In other words, perform upload.

Right now, this only works for file and castle-data URLs, and (as all engine functions) can also accept simple filenames.

When saving to castle-data URL, remember that on some platforms the game data is read-only. Use this only during development on desktop, when you know that "data" is just your regular data directory.

On Android, you should use the "write_external_storage" service to be able to write storage files (e.g. to SD card). This means files accessed by the 'file' protocol. See https://castle-engine.io/android-Services .

Exceptions raised
ESaveError
In case of problems saving this URL.
Exception
Various TStream instances (used internally by this function) may raise exceptions in case the stream cannot be created for saving. Right now, we simply let these exceptions to "pass through" from this function (instead of catching and re-raising). So be ready that this function may raise any Exception class.
function CreateReadFileStream(const URL: string): TStream; deprecated 'use Download(URL, [soForceMemoryStream])';

Warning: this symbol is deprecated: use Download(URL, [soForceMemoryStream])

Open a proper stream to read a file, fast (with buffering) and with seeking. This gives you a stream most comfortable for reading (buffering means that you can read small, comfortable pieces of it; seeking means you can jump freely to various file positions, back and forward).

On different OSes or even compilers this may require a little different stream, so it's safest to just use this function. For example, traditional Classes.TFileStream doesn't do buffering. Although under Linux, the buffering of file handles is done at kernel level (so everything works fast), on Windows the slowdown is noticeable. This function will always create proper stream descendant, eventually wrapping some standard stream in a buffered stream with full seeking capability.

Instead of this, use Download with [soForceMemoryStream].

procedure StreamSaveToFile(Stream: TStream; const URL: string);

Save the contents of given Stream to an URL.

Types

TDownloadStatus = (...);

See TCastleDownload.Status.

Values
  • dsNotStarted
  • dsDownloading
  • dsError
  • dsSuccess
THttpMethod = (...);

See TCastleDownload.HttpMethod.

Values
  • hmGet
  • hmPost
  • hmPut
  • hmDelete
  • hmOptions
  • hmHead
TUrlAsynchronousReaderClass = class of TUrlAsynchronousReader;
 
TUrlReadEvent = function ( const Url: string; out MimeType: string): TStream of object;

Event called when Download function wants to download URL with this protocol. Use with RegisterUrlProtocol.

TUrlWriteEvent = function(const Url: string): TStream of object;

Event called when URLSaveStream function wants to save URL with this protocol. Use with RegisterUrlProtocol.

TStreamOption = (...);

Options for the Download function.

Values
  • soForceMemoryStream: Force result to be a TCustomMemoryStream, with contents fully loaded to the memory, and freely seekable (you can move back and forth within). Without this option, Download may return other streams, for example TFileStream (that may not have good buffering, depending on OS) or TBase64DecodingStream (that may not allow seeking).

    Using TCustomMemoryStream means that reading is fast and comfortable, but eats memory and doesn't allow to simultaneously read and process the contents (the file must be fully loaded, e.g. downloaded from the Internet, and ungzipped, before this function returns). So use this option only for files that aren't too big.

    For larger files, you usually don't want to use this option, instead wrap result in TBufferedReadStream.

  • soGzip: Filter the contents through gzip decompression.
TStreamOptions = set of TStreamOption;
 
TDownloadFinishedEvent = procedure (const Sender: TCastleDownload; var FreeSender: Boolean) of object;
 
TSaveStreamOption = (...);

Options for the URLSaveStream function.

Values
  • ssoGzip: Filter the contents through gzip compression.
TSaveStreamOptions = set of TSaveStreamOption;
 

Variables

LogAllLoading: boolean = false;

Log (through CastleLog) all loading, that is: all calls to Download. This allows to easily check e.g. whether the engine is not loading something during the game (which usually badly affects the performance).

EnableBlockingDownloads: boolean = false;

Does Download (synchronous downloading routine) support http and https protocol. This is by default disabled, as it means that a call to Download may block your application, for arbitrarily long time, and you have no way to interrupt it. It is recommended to use asynchronous downloading, using TCastleDownload, to download resources over the network.

property EnableNetwork: Boolean read GetEnableNetwork write SetEnableNetwork;
 
Generated by PasDoc 0.16.0.