File Downloads

Table of Contents

• Downloads support
• Download events
• Download control
• Example

Downloads support

Coherent UI allows for clients to download files. Downloads can be initiated during navigation - by navigating to a URL whose MIME type is not one that Coherent UI can render, or directly initiated by the client with the Coherent::UI::View::DownloadUrl method.

Coherent UI does not save files on disk, it'll pass the downloaded data blob to the client.

Warning

The default implementation of Coherent::UI::EventListener::OnDownloadStarted returns false, so all downloads are disabled.

Download events

When a download is initiated, the client is notified via the Coherent::UI::EventListener::OnDownloadStarted event. The Coherent::UI::Download class encapsulates all information regarding the download. At this point the client must decide if the download task should continue or be stopped by returning either true or false. If the download is to continue (return true) than the client must also save the pointer to the Coherent::UI::Download object and call Destroy on it when he is done with it - either when the download is complete, cancelled or failed. If the user returns false she implicitly cancels the task and the Coherent::UI::Download object should not be used as it is automatically destroyed by the view context.

The Coherent::UI::EventListener::OnDownloadComplete event is called as soon as the download task has completed. You can safely call Destroy on the download task from here. If some error occurs during a download the Coherent::UI::EventListener::OnDownloadFailed event will be called with further details.

Download control

The progress of a download task can be monitored through the Coherent::UI::Download class. The Coherent::UI::Download::GetDownloadedBytesSoFar can be used to monitor progress. Keep in mind that downloads are performed on worker threads so this counter is not always up-to-date, it shows that at least so much bytes have already been downloaded. Tasks can be cancelled via the Coherent::UI::Download::Cancel method. Even after a download has completed, has been cancelled or has failed, the Coherent::UI::Download object remains valid. The user must call the Coherent::UI::Download::Destroy method as soon as she doesn't need it anymore in order to free the resources bound to the download task.

Warning

The downloaded data are available only in the Coherent::UI::EventListener::OnDownloadComplete method, after that they are destroyed.

Downloads are committed to memory and than passesd to the client. Avoid downloading huge files as they might not fit into memory and will fail.

Example

class UIEventListener : public Coherent::UI::EventListener
{
public:
    // ... omitted for brevity

    // Download all files
    virtual bool OnDownloadStarted(Coherent::UI::Download* downloadItem) override
    {
        // We could save the downloadItem object in order to monitor progress or cancel the task later
        return true;
    }

    virtual void OnDownloadComplete(Coherent::UI::Download* downloadItem, const char* data, unsigned size) override
    {
        // Convert the filename to UTF8 so that we can use std::ofstream
        size_t length = std::wcstombs(nullptr, downloadItem->GetFilename(), 0);
        std::string fn;

        if (length == size_t(-1) || length == 0)
        {
            assert(false && "Conversion from widechar to multi-byte string failed!");
        }
        else
        {
            fn.resize(length);
            std::wcstombs(&fn[0], downloadItem->GetFilename(), length);
            // Write the file to disk with the name from the URL
            std::ofstream fout(fn.c_str(), std::ios::binary);
            fout.write(data, size);
        }
        // Destroy the download item - we should do this for all downloads we have agreed to start
        downloadItem->Destroy();
    }

    virtual void OnDownloadFailed(Coherent::UI::Download* downloadItem, DownloadErrorType error) override
    {
        assert(false && "Download task failed!");
    }
};