Manage Downloads

Use this section to manage the download tasks and installed regions. It covers how to pause, resume, cancel, or delete regional map downloads along with suggested UI states for corresponding foreground app behavior.

Managing Download Tasks

To pause a download task:

1
NGLRegionalOffline.controlDownload(forRegionId: regionId, action: .pause)

To resume a download task:

1
NGLRegionalOffline.controlDownload(forRegionId: regionId, action: .resume)

To cancel (stop) a download task:

1
NGLRegionalOffline.controlDownload(forRegionId: regionId, action: .cancel)

To delete a download task and the installed data for a region:

1
NGLRegionalOffline.controlDownload(forRegionId: regionId, action: .delete)

Download States

The following table lists down some download states, what they indicate and suggestions around how they can be complemented using relevant actions on application UI.

Swift state	Meaning	Recommended UI Behavior
`.queued`	The task is queued	Show progress, pause, and cancel actions
`.downloadingPackage`	A regional package is being downloaded or installed	Show progress, pause, and cancel actions
`.pausedUser`	Paused by the user	Show resume and delete actions
`.pausedNetwork`	Paused because of network state	Show resume and delete actions
`.failedStorage`	Filesystem, storage, or installation-related failure	Prioritize storage recovery guidance
`.failed`	Other terminal failure	Show the detailed error and a retry action
`.completed`	Regional packages and validated Preview resources are ready in the map engine (100%)	Show downloaded, focus, or delete actions
`.cancelled`	The task was cancelled	Show retry or delete actions

Concurrency, threading, and background behavior

Packages within one map region are downloaded and installed sequentially.
Different regional tasks may run concurrently. There is currently no public maximum-concurrency setting.
To limit network, storage I/O, and peak memory, allow no more than one or two regional downloads at a time in the application layer.
Public completions and listeners are delivered on the main queue and can update UIKit directly.
Regional downloads use a normal URLSession, not a background URLSession.

Do not assume that a download continues while the application is suspended or terminated. Check task state after returning to the foreground and allow the user to retry or resume.