Asynchronous HTTP download manager with queue and progress tracking. More...

#include <gin_downloadmanager.h>

Classes
struct	DownloadResult
	Result of a completed or failed download. More...

Public Member Functions
	DownloadManager (int connectTimeout=30 1000, int shutdownTimeout=30 1000)

	~DownloadManager ()

void	setQueueFinishedCallback (std::function< void()> callback)
	This callback is called every time all downloads are finished.

void	setConnectTimeout (int timeout)
	How long connecting is given before it times out.

void	setRetryLimit (int limit)
	If a download fails, how long many times it should retry.

void	setRetryDelay (double seconds)
	If a download fails, how long to wait until trying again.

void	setConcurrentDownloadLimit (int l)
	Maximum number of downloads to allow at once.

int	getNumberOfDownloads ()
	Number of items in download queue.

void	setThreadPriority (juce::Thread::Priority p)
	Set download thread priority.

void	setProgressInterval (int ms)
	Sets minimum time between download progress callbacks in milliseconds.

void	setDownloadBlockSize (int bs)
	Sets the block size of chunks to download.

int	getNumDownloadsInQueue ()

void	enableGzipDeflate (bool e)
	If enabled, will request the server sends the data compressed This only has effect on windows.

void	pauseDownloads (bool)
	Pause / resume all downloads.

int	startAsyncDownload (juce::String url, juce::String postData, std::function< void(DownloadResult)> completionCallback, std::function< void(juce::int64, juce::int64, juce::int64)> progressCallback=nullptr, juce::String extraHeaders={})
	Starts a download and returns the download id which can be used to cancel the download.

int	startAsyncDownload (juce::URL url, std::function< void(DownloadResult)> completionCallback, std::function< void(juce::int64, juce::int64, juce::int64)> progressCallback=nullptr, juce::String extraHeaders={})

void	cancelAllDownloads ()
	Cancels all downloads.

void	cancelDownload (int downloadId)
	Cancels a download with a given id.

DownloadResult	blockingDownload (juce::String url, juce::String postData, juce::String extraHeaders={})

DownloadResult	blockingDownload (juce::URL url, juce::String extraHeaders={})

Detailed Description

Asynchronous HTTP download manager with queue and progress tracking.

DownloadManager provides a robust system for downloading files without blocking the message thread. Unlike juce::URL::downloadToFile which blocks during HTTP connection establishment, DownloadManager performs all network operations on background threads and delivers results via callbacks on the message thread.

Key Features:

Non-blocking HTTP downloads
Concurrent download queue with limit control
Automatic retry on failure with configurable delays
Progress tracking with adjustable callback intervals
Download pause/resume support
GZIP compression support
Thread priority control
Blocking and async download modes
Safe cancellation of in-progress downloads

The manager maintains a queue of downloads, executes them on background threads, and calls completion callbacks on the message thread. This ensures UI remains responsive during large downloads or slow connections.

Usage:

DownloadManager manager;
manager.setConnectTimeout(10000);  // 10 second timeout
manager.setRetryLimit(3);          // Retry up to 3 times
manager.setConcurrentDownloadLimit(2);  // Max 2 at once
 
// Start async download with progress
int downloadId = manager.startAsyncDownload(
    "https://example.com/file.zip",
    "",  // No POST data
    [](DownloadManager::DownloadResult result) {
        if (result.ok)
            result.saveToFile(File("downloaded.zip"));
        else
            DBG("Download failed: " + String(result.httpCode));
    },
    [](int64 current, int64 total, int64 delta) {
        DBG("Progress: " + String(current) + " / " + String(total));
    }
);
 
// Cancel if needed
manager.cancelDownload(downloadId);
 
// Or block until complete
auto result = manager.blockingDownload("https://example.com/data.json");
if (result.ok)
    processJSON(result.data.toString());

Thread Safety:

All public methods are thread-safe
Callbacks are always executed on the message thread
Safe to cancel downloads from any thread

See also: DownloadResult, juce::URL

Constructor & Destructor Documentation

◆ DownloadManager()

DownloadManager::DownloadManager	(	int	connectTimeout = `30 *1000`,
		int	shutdownTimeout = `30 *1000`
	)

◆ ~DownloadManager()

DownloadManager::~DownloadManager ( )

Member Function Documentation

◆ setQueueFinishedCallback()

void DownloadManager::setQueueFinishedCallback ( std::function< void()> callback )

This callback is called every time all downloads are finished.

◆ setConnectTimeout()

void DownloadManager::setConnectTimeout ( int timeout )

How long connecting is given before it times out.

◆ setRetryLimit()

void DownloadManager::setRetryLimit ( int limit )

If a download fails, how long many times it should retry.

◆ setRetryDelay()

void DownloadManager::setRetryDelay ( double seconds )

If a download fails, how long to wait until trying again.

◆ setConcurrentDownloadLimit()

void DownloadManager::setConcurrentDownloadLimit ( int l )

Maximum number of downloads to allow at once.

◆ getNumberOfDownloads()

int DownloadManager::getNumberOfDownloads ( )

Number of items in download queue.

◆ setThreadPriority()

void DownloadManager::setThreadPriority ( juce::Thread::Priority p )

Set download thread priority.

Does not affect priority of already running threads

◆ setProgressInterval()

void DownloadManager::setProgressInterval ( int ms )

Sets minimum time between download progress callbacks in milliseconds.

◆ setDownloadBlockSize()

void DownloadManager::setDownloadBlockSize ( int bs )

Sets the block size of chunks to download.

Progress callbacks and cancelling downloads can only happen between these blocks. Max size is 128 KB

◆ getNumDownloadsInQueue()

int DownloadManager::getNumDownloadsInQueue ( )

◆ enableGzipDeflate()

void DownloadManager::enableGzipDeflate ( bool e )

If enabled, will request the server sends the data compressed This only has effect on windows.

On macOS it is handled by the system libraries and is always on.

◆ pauseDownloads()

void DownloadManager::pauseDownloads ( bool )

Pause / resume all downloads.

This actually stops any running downloads and then restarts them when unpaused. You will loose some downloaded data that will need to be redownloaded.

◆ startAsyncDownload() [1/2]

int DownloadManager::startAsyncDownload	(	juce::String	url,
		juce::String	postData,
		std::function< void(DownloadResult)>	completionCallback,
		std::function< void(juce::int64, juce::int64, juce::int64)>	progressCallback = `nullptr`,
		juce::String	extraHeaders = `{}`
	)

Starts a download and returns the download id which can be used to cancel the download.

progressCallback returns current amount downloaded, total amount to download, and amount downloaded since last callback. Note that for http chunk encoding total size is unknown and will be maximum int64 value.

◆ startAsyncDownload() [2/2]

int DownloadManager::startAsyncDownload	(	juce::URL	url,
		std::function< void(DownloadResult)>	completionCallback,
		std::function< void(juce::int64, juce::int64, juce::int64)>	progressCallback = `nullptr`,
		juce::String	extraHeaders = `{}`
	)

◆ cancelAllDownloads()

void DownloadManager::cancelAllDownloads ( )

Cancels all downloads.

◆ cancelDownload()

void DownloadManager::cancelDownload ( int downloadId )

Cancels a download with a given id.

◆ blockingDownload() [1/2]

DownloadResult DownloadManager::blockingDownload	(	juce::String	url,
		juce::String	postData,
		juce::String	extraHeaders = `{}`
	)

◆ blockingDownload() [2/2]

DownloadResult DownloadManager::blockingDownload	(	juce::URL	url,
		juce::String	extraHeaders = `{}`
	)

The documentation for this class was generated from the following file:

gin_downloadmanager.h

Classes

Public Member Functions