|
How to manage download sessions |
  
|
|
How to manage download sessions |
|
Inside the How to play Internet streams and radio stations tutorial we have seen that the component gives the possibility to connect to a remote server in order to start playback of a remote file through its URL: there are situations which could require downloading the full remote file locally before starting playback in order to avoid buffering issues in case of slow or intermittent connections or to allow the storage of the remote file for future uses; the downloading task can be achieved through the Downloader COM object accessible through the Downloader property.
The Downloader COM object, which is intended for download of remote files only (so downloading from broadcasting streaming servers or radio stations is not supported), can be instanced and started through the Downloader.Create method and exposes the following features:
| • | downloading a remote file and storing its contents inside a local file through the Downloader.SessionStartToFile method. |
| • | downloading a remote file and storing its contents inside a local memory buffer through the Downloader.SessionStartToMemory method: the size of the buffer, whose allocation is responsibility of the container application, can be determined through the Downloader.SessionDataSizeGet method. |
| • | downloading a remote media file and loading its contents into an instanced player directly through the Downloader.SessionStartToPlayer method. This method is equivalent to calling the Downloader.SessionStartToFile method followed by a call to the LoadSound, LoadEncryptedSound (in case of sound files encrypted through our CryptSound™ application) or VideoPlayer.Load methods. Apart from the automatic loading of the downloaded media file, the difference respect to the Downloader.SessionStartToFile method is the fact that the remote file will be stored locally inside a temporary file that will be automatically deleted when the CloseSound or VideoPlayer.Close methods are invoked or when a new media file is loaded inside the same player: this means that the container application won't have to worry about the existence of the downloaded file when no more needed. |
All of the mentioned methods allow starting the downloading session and, in case of success, a session's unique identifier is returned: through this identifier you have the possibility to interrupt the same downloading session through the Downloader.SessionStop method.
During the download session, the container application is notified about the advancement through the CallbackForDownloaderEvents delegate which is invoked with the nEvent parameter set to one of the following values:
- the EV_DOWNLOADER_SESSION_STARTED event reports that the downloading session is started
- the EV_DOWNLOADER_SESSION_PROGRESS event informs about the download advancement expressed in percentage
- the EV_DOWNLOADER_SESSION_COMPLETED event reports that the downloading session is completed successfully
- the EV_DOWNLOADER_SESSION_FAILED event reports that the connection to the remote server or the access to the remote file failed
- the EV_DOWNLOADER_SESSION_STOPPED event reports that the downloading session has been stopped by the user manually through a call to the Downloader.SessionStop method
When the downloading session has been started through the Downloader.SessionStartToPlayer method and the same has been reported as successful through the EV_DOWNLOADER_SESSION_COMPLETED event, a further couple of events may be generated:
- the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_SOUND_LOADED reporting that the downloaded media file belongs to a supported format and that the automatic loading into the player has been successful: after receiving this event the downloaded file could be put in playback through the usual PlaySound or VideoPlayer.Play methods.
- the CallbackForDownloaderEvents delegate is invoked with the nEvent parameter set to EV_DOWNLOADER_INVALID_FILE reporting that the remote file belongs to an unsupported format and that the automatic loading into the player failed.
When invoking the Downloader.Create method you can specify timeouts checked during the connection to the remote server and during data downloading: these timeouts can be modified at any time through the Downloader.SetTimeouts method.
In order to avoid download speed throttling by certain types of server, by default the downloader performs parallel downloads of different chunks of the same file: this option can be disabled through the Downloader.EnableParallelDownload method.
A sample of usage the downloader in Visual C# and Visual Basic.NET can be found inside the following sample installed with the product's setup package:
- Downloader
