Unit CastleDownload

Description

Read and write stream contents from URLs.

Uses

Overview

Classes, Interfaces, Objects and Records

Name Description
Class EDownloadError  
Class ESaveError  
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.

Functions and Procedures

function Download(const URL: string; const Options: TStreamOptions = []): TStream;
function Download(const URL: string; const Options: TStreamOptions; out MimeType: string): TStream;
function URLSaveStream(const URL: string; const Options: TSaveStreamOptions = []): TStream;
function CreateReadFileStream(const URL: string): TStream; deprecated;
procedure StreamSaveToFile(Stream: TStream; const URL: string);

Types

TStreamOption = (...);
TStreamOptions = set of TStreamOption;
TSaveStreamOption = (...);
TSaveStreamOptions = set of TSaveStreamOption;

Constants

DefaultEnableNetwork = false;

Variables

EnableNetwork: boolean = DefaultEnableNetwork;
LogAllLoading: boolean = false;

Description

Functions and Procedures

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

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.

A local file URL is always supported, without using any networking library. URL without any protocol is always treated like a local filename (absolute or relative to current dir), so this function can be a drop-in replacement for normal file reading. The MIME type for local files is guessed based on their extension.

A data URI scheme (http://en.wikipedia.org/wiki/Data_URI_scheme) is also always supported. The MIME type for such content is specified explicitly in URI. TODO: right now, soGzip is ignored for data URIs, we never filter them through gunzip.

It also automatically supports protocols to embed script contents: ecmascript, javascript (see VRML and X3D specifications), castlescript, kambiscript (see https://castle-engine.io/castle_script.php), compiled (https://castle-engine.io/x3d_extensions.php#section_ext_script_compiled). The MIME type for these is implied by the protocol (like "application/javascript" for ecmascript/javascript), and the returned stream simply contains script code.

Set EnableNetwork to True to have also support for network protocols. Right now this means only http, handled by FpHttpClient. The MIME type for such content is usually reported by the http server (but if the server doesn't report MIME type, we still try to guess it, looking at URL using URIMimeType).

On Android, URLs that indicate assets (files packaged inside .apk) are also supported, as assets:/my_file.png.

Note if you use a network URL (like http://...) and you read from this stream that you make a synchronous downloader. Which means that your application will wait until the data arrives from the Internet. This is why http:// support is disabled here by default (see EnableNetwork). 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). But often you may want to instead use asynchronous downloading – we plan to implement it by the class TDownload (see comments in CastleDownload code), but it's not ready yet!

Exceptions raised
EDownloadError
In case of problems loading from this URL.
EFOpenError
If case opening the underlying file fails, raised in case of file:// URLs.
EStreamError
If case reading the stream fails, raised in case of file:// URLs.
Exception
Various TStream classes (used internally by this function) may raise various exceptions in case the stream cannot be created for reading. Right now, we simply let these exceptions to "pass through" from this function (instead of catching and re-raising). So, to be really safe, be ready that this function may raise any Exception class.
function Download(const URL: string; const Options: TStreamOptions; out MimeType: string): TStream;
 
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 URLs, and the only advantage it has over manually creating TFileStream is that this accepts URLs.

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;

Warning: this symbol is deprecated.

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 CastleDownload.Download with LocalFileInMemory.

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

Save the contents of given Stream to an URL.

Types

TStreamOption = (...);

Options for the Download function.

Values
  • soForceMemoryStream: Force result to be a TMemoryStream, 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 TMemoryStream 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;
 
TSaveStreamOption = (...);

Options for the URLSaveStream function.

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

Constants

DefaultEnableNetwork = false;
 

Variables

EnableNetwork: boolean = DefaultEnableNetwork;

Can Download actually use the network. As all the downloading is blocking for now, this is initially False. If you want to really use the network, change it to True.

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


Generated by PasDoc 0.15.0.