DownloadManager Class Reference

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={})
int	startAsyncDownload (juce::URL url, juce::File target, std::function< void(DownloadResult)> completionCallback, std::function< void(juce::int64, juce::int64, juce::int64)> progressCallback=nullptr, juce::String extraHeaders={})
	Starts a download straight into a file, written block by block as it arrives, so its size is not limited by memory.
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/3]

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/3]

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 = {} )

startAsyncDownload() [3/3]

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

Starts a download straight into a file, written block by block as it arrives, so its size is not limited by memory.

The file is replaced; it is deleted again when the download fails or is cancelled. The result's data stays empty, result.file names the file.

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