ArcGIS Runtime SDK for iOS: AGSOfflineMapTask Class Reference
ArcGIS Runtime SDK for iOS  100.15
AGSOfflineMapTask Class Reference

Description

A task to take a map offline.

Taking a map offline involves downloading an online map and its data, including all the supported layers, tables, renderers, web map configuration etc. so that it can be used offline without a network connection.

There are two workflows available for taking maps offline:

  • The ahead-of-time workflow (also sometimes referred to as the preplanned workflow)
  • The on-demand workflow

Ahead-of-time workflow:

In this workflow the author of a web map defines geographical areas (offline map areas) to take offline. ArcGIS Online, or ArcGIS Enterprise, uses these to prepare offline map content that is stored online. ArcGIS Runtime apps download the offline map content to a device using the AGSDownloadPreplannedOfflineMapJob. Note that ArcGIS Runtime APIs refer to an offline map area as an AGSPreplannedMapArea. For more information about authoring offline map areas, see Take web maps offline.

On-demand workflow:

Here the app passes a specific area of interest to an AGSGenerateOfflineMapJob object to generate and download the map content to the device. Using this workflow, you can choose to keep online only services (e.g. those that require a network connection) in your offline map. Be aware that an offline map which uses online only services will require a network connection and may require authentication.

Since
100.1
Inheritance diagram for AGSOfflineMapTask:
AGSLoadableBase AGSObject <AGSLoadable>

Instance Methods

(void) - cancelLoad
 
(id< AGSCancelable >) - defaultDownloadPreplannedOfflineMapParametersWithArea:completion:
 
(id< AGSCancelable >) - defaultGenerateOfflineMapParametersWithAreaOfInterest:completion:
 
(id< AGSCancelable >) - defaultGenerateOfflineMapParametersWithAreaOfInterest:minScale:maxScale:completion:
 
(void) - doCancelLoading
 
(void) - doStartLoading:
 
(AGSDownloadPreplannedOfflineMapJob *) - downloadPreplannedOfflineMapJobWithArea:downloadDirectory:
 
(AGSDownloadPreplannedOfflineMapJob *) - downloadPreplannedOfflineMapJobWithArea:downloadDirectory:excludeBasemap:
 
(AGSDownloadPreplannedOfflineMapJob *) - downloadPreplannedOfflineMapJobWithParameters:downloadDirectory:
 
(AGSGenerateOfflineMapJob *) - generateOfflineMapJobWithParameters:downloadDirectory:
 
(AGSGenerateOfflineMapJob *) - generateOfflineMapJobWithParameters:parameterOverrides:downloadDirectory:
 
(id< AGSCancelable >) - generateOfflineMapParameterOverridesWithParameters:completion:
 
(id< AGSCancelable >) - getOfflineMapCapabilitiesWithParameters:completion:
 
(id< AGSCancelable >) - getPreplannedMapAreasWithCompletion:
 
(instancetype) - initWithOnlineMap:
 
(instancetype) - initWithPortalItem:
 
(void) - loadDidFinishWithError:
 
(void) - loadWithCompletion:
 
(void) - onLoadStatusChanged
 
(void) - retryLoadWithCompletion:
 

Class Methods

(instancetype) + offlineMapTaskWithOnlineMap:
 
(instancetype) + offlineMapTaskWithPortalItem:
 

Properties

NSError * loadError
 
AGSLoadStatus loadStatus
 
AGSMaponlineMap
 
AGSPortalItemportalItem
 

Method Documentation

◆ cancelLoad

- (void) cancelLoad
requiredinherited

Cancels loading if it is in progress, otherwise it does nothing. This should be called carefully because other objects could be waiting for loadWithCompletion: or retryLoadWithCompletion: to complete and this will call them all back with the error of NSUserCancelledError

Since
100

◆ defaultDownloadPreplannedOfflineMapParametersWithArea:completion:

- (id<AGSCancelable>) defaultDownloadPreplannedOfflineMapParametersWithArea: (AGSPreplannedMapArea *)  preplannedMapArea
completion: (void(^)(AGSDownloadPreplannedOfflineMapParameters *__nullable params, NSError *__nullable error))  completion 

A convenience method to create the AGSDownloadPreplannedOfflineMapParameters with default values, appropriate for taking the specified map area offline. The default parameters will be populated using the values in the online map's offline settings (if present).

Parameters
preplannedMapAreaThe offline map area that is to be downloaded from the online map.
completionA block that is invoked with the initialized params if the method succeeds, or an error if it fails.
Returns
An operation that can be canceled.
Since
100.5

◆ defaultGenerateOfflineMapParametersWithAreaOfInterest:completion:

- (id<AGSCancelable>) defaultGenerateOfflineMapParametersWithAreaOfInterest: (AGSGeometry *)  areaOfInterest
completion: (void(^)(AGSGenerateOfflineMapParameters *__nullable params, NSError *__nullable error))  completion 

A convenience method to get properly initialized parameters for generating an offline map.

This will populate the parameters with values matching what the service supports. For example if the service does not support AGSSyncModelLayer then AGSSyncModelGeodatabase will be used. All layers from the service will be included. The extent will be the service's full extent. Attachments are included by default, but related tables/layers are not included.

The returned parameter's min scale and max scale are zero and that'll include tiles for the full range of scales the tiled layers support when taking the map offline. The itemInfo property of the parameter is initialized based this task's portal item, if that is set, and will include the item's thumbnail.

Parameters
areaOfInterestAn AGSPolygon or AGSEnvelope geometry that defines the geographic area for which the map data should be taken offline.
completionA block that is invoked with the initialized params if the method succeeds, or an error if it fails.
Returns
An operation that can be canceled.
Since
100.1

◆ defaultGenerateOfflineMapParametersWithAreaOfInterest:minScale:maxScale:completion:

- (id<AGSCancelable>) defaultGenerateOfflineMapParametersWithAreaOfInterest: (AGSGeometry *)  areaOfInterest
minScale: (double)  minScale
maxScale: (double)  maxScale
completion: (void(^)(AGSGenerateOfflineMapParameters *__nullable params, NSError *__nullable error))  completion 

Provides parameters to generate an offline map with the specified area of interest, min scale and max scale.

Note
The area of interest must have a spatial reference. The returned AGSGenerateOfflineMapParameters has its itemInfo property initialized from the offline map task's portal item, if that is set. The itemInfo's thumbnail will be copied from the portal item's thumbnail.
Parameters
areaOfInterestAn AGSPolygon or AGSEnvelope geometry that defines the geographic area for which the map data should be taken offline.
minScaleThe minimum scale for offline tile caches. Use 0 for all far out levels. See the property AGSGenerateOfflineMapParameters::minScale.
maxScaleThe maximum scale for offline tile caches. Use 0 for closer in detailed levels. Sets the property AGSGenerateOfflineMapParameters::maxScale.
completionA block that is invoked with the initialized params if the method succeeds, or an error if it fails.
Returns
An operation that can be canceled.
Since
100.4

◆ doCancelLoading

- (void) doCancelLoading

Never call this method directly. The framework calls this method on a background thread when cancelLoad (AGSLoadable-p) is called. It is meant to be overriden by subclasses. Subclasses should override this method to cancel loading their data and call loadDidFinishWithError: (AGSLoadableBase(ForSubclassEyesOnly)) at the end passing in an error representing NSUserCancelledError.

Since
100

Provided by category AGSLoadableBase(ForSubclassEyesOnly).

◆ doStartLoading:

- (void) doStartLoading: (BOOL)  retrying

Never call this method directly. The framework calls this method on a background thread when loadWithCompletion: (AGSLoadable-p) or retryLoadWithCompletion: (AGSLoadable-p) is called. It is meant to be overriden by subclasses. Subclasses should override this method to load their data and call loadDidFinishWithError: (AGSLoadableBase(ForSubclassEyesOnly)) upon completion, passing in the error if any.

Parameters
retryingflag that is true if this method was called from retryLoadWithCompletion: (AGSLoadable-p).
Since
100

Provided by category AGSLoadableBase(ForSubclassEyesOnly).

◆ downloadPreplannedOfflineMapJobWithArea:downloadDirectory:

- (AGSDownloadPreplannedOfflineMapJob *) downloadPreplannedOfflineMapJobWithArea: (AGSPreplannedMapArea *)  preplannedMapArea
downloadDirectory: (NSURL *)  downloadDirectory 

Creates a job that is used to download the specified preplanned map area of an online map. The job that is returned is dormant and needs to be explicitly started. The job will fail if the last directory in the download directory path cannot be created or is not empty.

Parameters
preplannedMapAreaSpecifies the preplanned map area to be downloaded.
downloadDirectoryThe path to a folder where the map content is stored on the device. For example, to create a new mobile map package "my_mobile_map_package" in a parent directory "[my root path]/my_mobile_maps", this property would be "[my root path]/my_mobile_maps/my_mobile_map_package".
Returns
An AGSDownloadPreplannedOfflineMapJob to download a preplanned map area.
Since
100.2
Deprecated:
100.10.0. Please use downloadPreplannedOfflineMapJobWithParameters:downloadDirectory:. This method does not support the scheduled updates workflow and will default to use AGSPreplannedUpdateModeSyncWithFeatureServices. An instance of AGSDownloadPreplannedOfflineMapParameters can be created and populated as required. Alternatively the recommended workflow is to use AGSOfflineMapTask::createDefaultDownloadPreplannedOfflineMapParametersWithPreplannedMapArea:completion: and then make any adjustments. This will determine if scheduled updates are present and update the property AGSDownloadPreplannedOfflineMapParameters::updateMode appropriately.

Provided by category AGSOfflineMapTask(AGSDeprecated).

◆ downloadPreplannedOfflineMapJobWithArea:downloadDirectory:excludeBasemap:

- (AGSDownloadPreplannedOfflineMapJob *) downloadPreplannedOfflineMapJobWithArea: (AGSPreplannedMapArea *)  preplannedMapArea
downloadDirectory: (NSURL *)  downloadDirectory
excludeBasemap: (BOOL)  excludeBasemap 

Creates a job that is used to download the specified preplanned map area of an online map but excludes the map's basemap.

If you exclude the map's basemap from the download, the offline map's size will be smaller and consequently the download process will be faster. If you already have a basemap stored locally on your device, you can add that to the offline map.

The job that is returned is dormant and needs to be explicitly started. The job will fail if the last directory in the downloadDirectory cannot be created or is not empty. Specifying excludeBasemap to YES will override the authored settings of preplanned map area and always exclude the basemap content.

Parameters
preplannedMapAreaSpecifies the preplanned map area to be downloaded.
downloadDirectoryThe path to a folder where the map content is stored on the device. For example, to create a new mobile map package "my_mobile_map_package" in a parent directory "[my root path]/my_mobile_maps", this property would be "[my root path]/my_mobile_maps/my_mobile_map_package".
excludeBasemapA boolean to exclude the basemap from the offline map.
Returns
An AGSDownloadPreplannedOfflineMapJob object to download a preplanned map area.
Since
100.2
Deprecated:
100.10.0. This method has been replaced by downloadPreplannedOfflineMapJobWithParameters:downloadDirectory:. Use AGSDownloadPreplannedOfflineMapParameters::includeBasemap to set basemap inclusion. Note reversal of logic from 'exclude basemap' to 'include basemap'.

Provided by category AGSOfflineMapTask(AGSDeprecated).

◆ downloadPreplannedOfflineMapJobWithParameters:downloadDirectory:

- (AGSDownloadPreplannedOfflineMapJob*) downloadPreplannedOfflineMapJobWithParameters: (AGSDownloadPreplannedOfflineMapParameters *)  parameters
downloadDirectory: (NSURL *)  downloadDirectory 

Creates a job which can be used to download an offline map for an offline map area using the specified parameters. The result of the job will be of type AGSDownloadPreplannedOfflineMapResult.

Note
The job is dormant and needs to be explicitly started using startWithStatusHandler:completion: (AGSGenerateOfflineMapJob).
Parameters
parametersAGSDownloadPreplannedOfflineMapParameters specify how to take a map offline. For example, specify the area of interest, min and max scale, layer attachment options.
downloadDirectorydirectory to download the offline map and its contents to.
Returns
A new job to download the offline map. The job will fail if download directory cannot be created or is not empty.
Since
100.4
See also
- getPreplannedMapAreasWithCompletion: to get a list of preplanned map areas for the map this task's onlineMap property.

◆ generateOfflineMapJobWithParameters:downloadDirectory:

- (AGSGenerateOfflineMapJob *) generateOfflineMapJobWithParameters: (AGSGenerateOfflineMapParameters *)  parameters
downloadDirectory: (NSURL *)  downloadDirectory 

Creates a job which can be used to generate an offline map using the specified parameters. The result of the job will be of type AGSGenerateOfflineMapResult.

Note
The job is dormant and needs to be explicitly started using startWithStatusHandler:completion: (AGSGenerateOfflineMapJob)
Parameters
parametersspecifying how to take a map offline.
downloadDirectorywhere the offline map should be saved on disk. If the directory exists it should be empty otherwise the operation will fail. If the directory doesn't exist, it will be created by the job.
Returns
A new job to generate an offline map. The result of the job will be of type AGSGenerateOfflineMapResult. The job will fail if download directory cannot be created or is not empty.
Since
100.1

◆ generateOfflineMapJobWithParameters:parameterOverrides:downloadDirectory:

- (AGSGenerateOfflineMapJob *) generateOfflineMapJobWithParameters: (AGSGenerateOfflineMapParameters *)  parameters
parameterOverrides: (AGSGenerateOfflineMapParameterOverrides *)  parameterOverrides
downloadDirectory: (NSURL *)  downloadDirectory 

Creates a job that is used to generate an offline map using the specified parameters and overrides.

Note
The job that is returned is dormant and needs to be explicitly started. The job will fail if the last directory in the download directory path cannot be created or is not empty. The AGSGenerateOfflineMapParameterOverrides allows more control over the extracted data. To create an instance AGSGenerateOfflineMapParameterOverrides use generateOfflineMapParameterOverridesWithParameters:completion:.

Some properties on AGSGenerateOfflineMapParameters will be ignored when using AGSGenerateOfflineMapParameterOverrides and replaced with equivalent properties for each service.

The overridden properties are:

Parameters
parametersThe parameters specifying how to take a map offline. For example, specify the area of interest, min and max scale, layer attachment options.
parameterOverridesThe overrides to the parameters.
downloadDirectoryThe download directory where the offline map should be saved on disk. If the directory exists it should be empty otherwise the operation will fail. If the directory doesn't exist, it will be created by the job.
Returns
A new job to generate an offline map. The result of the job will be of type AGSGenerateOfflineMapResult. The job will fail if download directory cannot be created or is not empty.
Since
100.4

◆ generateOfflineMapParameterOverridesWithParameters:completion:

- (id<AGSCancelable>) generateOfflineMapParameterOverridesWithParameters: (AGSGenerateOfflineMapParameters *)  parameters
completion: (void(^)(AGSGenerateOfflineMapParameterOverrides *__nullable parameterOverrides, NSError *__nullable error))  completion 

Provides overrides for AGSGenerateOfflineMapParameters. Upon successful completion, a AGSGenerateOfflineMapParameterOverrides instance will be populated reflecting the values in the AGSGenerateOfflineMapParameters parameters. The overrides may be inspected and modified to change the offline data before creating a job with generateOfflineMapJobWithParameters:parameterOverrides:downloadDirectory:.

If there are errors with loading individual layers or tables, or they cannot be taken offline due to service settings, the outcome depends on the value of AGSGenerateOfflineMapParameters::continueOnErrors. If true, the overrides correspond to the remaining layers and tables that can go offline. The resulting offline map will not contain the layers or tables which had errors. If AGSGenerateOfflineMapParameters::continueOnErrors is false, the task will fail immediately with an exception from the failed layer or table. To check upfront which layers or tables are valid for taking offline see AGSOfflineMapTask::getOfflineMapCapabilitiesWithParameters.

Since
100.4

◆ getOfflineMapCapabilitiesWithParameters:completion:

- (id<AGSCancelable>) getOfflineMapCapabilitiesWithParameters: (AGSGenerateOfflineMapParameters *)  parameters
completion: (void(^)(AGSOfflineMapCapabilities *__nullable params, NSError *__nullable error))  completion 

Provides information about offline capabilities of the map, such as which layers will be included in an offline map.

Parameters
parametersspecifying how to take the map offline.
completionblock that is invoked with offline capabilities of the map if the operation succeeds, or an error if it fails.
Returns
An operation that can be canceled.
Since
100.1

◆ getPreplannedMapAreasWithCompletion:

- (id<AGSCancelable>) getPreplannedMapAreasWithCompletion: (void(^)(NSArray< AGSPreplannedMapArea * > *__nullable preplannedMapAreas, NSError *__nullable error))  completion

Get a list of preplanned map areas that are available for this task's onlineMap. Preplanned map areas already have the map data packaged and staged for download which speeds up taking a map offline.

Note
Calling this method will load the AGSOfflineMapTask if it is not already loaded.
Parameters
completionA block that is invoked with the list of preplanned map areas if the operation succeeds, or an error if it fails.
Returns
An operation that can be canceled.
Since
100.2

◆ initWithOnlineMap:

- (instancetype) initWithOnlineMap: (AGSMap *)  onlineMap

Creates a task with the provided map to take offline. The map must be a web map either on ArcGIS Online or an on-premises ArcGIS Portal.

Parameters
onlineMapto take offline.
Since
100.1

◆ initWithPortalItem:

- (instancetype) initWithPortalItem: (AGSPortalItem *)  portalItem

Creates a task with the provided portal item. The item must represent a web map (item type should be AGSPortalItemTypeWebMap) either on ArcGIS Online or an on-premises ArcGIS Portal.

Parameters
portalItemspecifying a map to take offline.
Since
100.1

◆ loadDidFinishWithError:

- (void) loadDidFinishWithError: (nullable NSError *)  error

Only subclasses should call this method in doStartLoading: (AGSLoadableBase(ForSubclassEyesOnly)) and doCancelLoading (AGSLoadableBase(ForSubclassEyesOnly)) when done loading or failed to load.

Since
100

Provided by category AGSLoadableBase(ForSubclassEyesOnly).

◆ loadWithCompletion:

- (void) loadWithCompletion: (nullable void(^)(NSError *__nullable error))  completion
requiredinherited

Loads data for the object asynchronously. The completion block is invoked upon completion.

You can call this method any number of times, however only one attempt is made to load the data. If it is already loading, it will just continue to load (i.e. not force a reload). If it has already loaded successfully, the completion block will be invoked right away. If it has already failed to load, the completion block will be invoked right away with error previously encountered. This method supports multiple callers and will call them all back on completion. However, each caller's completion block will be invoked once and only once.

Parameters
completionblock that is invoked when object loads successfully or fails to load. An error is passed to the block if the object fails to load.
Note
The completion block is always invoked on the main thread.
Since
100
See also
- cancelLoad to cancel loading
- retryLoadWithCompletion: to force reload

◆ offlineMapTaskWithOnlineMap:

+ (instancetype) offlineMapTaskWithOnlineMap: (AGSMap *)  onlineMap

Creates a task with the provided map to take offline. The map must be a web map either on ArcGIS Online or an on-premises ArcGIS Portal.

Parameters
onlineMapto take offline.
Returns
A new task.
Since
100.1

◆ offlineMapTaskWithPortalItem:

+ (instancetype) offlineMapTaskWithPortalItem: (AGSPortalItem *)  portalItem

Creates a task with the provided portal item. The item must represent a web map (item type should be AGSPortalItemTypeWebMap) either on ArcGIS Online or an on-premises ArcGIS Portal.

Parameters
portalItemspecifying a map to take offline.
Returns
A new task.
Since
100.1

◆ onLoadStatusChanged

- (void) onLoadStatusChanged

Never call this method directly. The framework calls this method on a background thread when AGSLoadable::loadStatus changes is called. Subclasses can optionally implement this to know when their loading status has changed.

Since
100

Provided by category AGSLoadableBase(ForSubclassEyesOnly).

◆ retryLoadWithCompletion:

- (void) retryLoadWithCompletion: (nullable void(^)(NSError *__nullable error))  completion
requiredinherited

Tries to reload when an object has failed to load. This method should be called judiciously. It should be called when:

  1. you didn't have network connectivity earlier when it failed and you want to retry now that you have connectivity
  2. the server was down earlier when it failed and you want to retry
  3. the request is taking too long and you want to cancel it and retry, in which case you will first call cancelLoad and then this method

If the data hasn't started loading, it will start loading. If it is already loading, it will just continue to load. If it has already loaded successfully, calls back right away. If it has already failed to load, tries again. This method supports multiple callers and will call them all back on completion. However, each caller's completion block will be invoked once and only once.

Parameters
completionblock that is invoked when object loads successfully or fails to load. An error is passed to the block if the object fails to load.
Note
The completion block is always invoked on the main thread.
Since
100

Property Documentation

◆ loadError

- (NSError*) loadError
readnonatomicstronginherited

The error that was encountered during the most recent load operation. Will be nil if the operation succeeded.

Since
100

◆ loadStatus

- (AGSLoadStatus) loadStatus
readrequirednonatomicassigninherited

Status of the load operation.

Since
100

◆ onlineMap

- (AGSMap*) onlineMap
readnonatomicstrong

The map to take offline. The map must be a web map either on ArcGIS Online or an on-premises ArcGIS Portal.

Since
100.1

◆ portalItem

- (AGSPortalItem*) portalItem
readnonatomicstrong

Portal item specifying the map to take offline. The item must represent a web map (item type should be AGSPortalItemTypeWebMap) either on ArcGIS Online or an on-premises ArcGIS Portal.

Since
100.1