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:

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
AGSMap *	onlineMap
AGSPortalItem *	portalItem

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

preplannedMapArea	The offline map area that is to be downloaded from the online map.
completion	A 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

areaOfInterest	An AGSPolygon or AGSEnvelope geometry that defines the geographic area for which the map data should be taken offline.
completion	A 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

areaOfInterest	An AGSPolygon or AGSEnvelope geometry that defines the geographic area for which the map data should be taken offline.
minScale	The minimum scale for offline tile caches. Use 0 for all far out levels. See the property AGSGenerateOfflineMapParameters::minScale.
maxScale	The maximum scale for offline tile caches. Use 0 for closer in detailed levels. Sets the property AGSGenerateOfflineMapParameters::maxScale.
completion	A 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

retrying

flag 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

preplannedMapArea	Specifies the preplanned map area to be downloaded.
downloadDirectory	The 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

preplannedMapArea	Specifies the preplanned map area to be downloaded.
downloadDirectory	The 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".
excludeBasemap	A 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

parameters	AGSDownloadPreplannedOfflineMapParameters specify how to take a map offline. For example, specify the area of interest, min and max scale, layer attachment options.
downloadDirectory	directory 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

parameters	specifying how to take a map offline.
downloadDirectory	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.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:

• AGSGenerateOfflineMapParameters::includeBasemap
• AGSGenerateOfflineMapParameters::returnLayerAttachmentOption
• AGSGenerateOfflineMapParameters::attachmentSyncDirection
• AGSGenerateOfflineMapParameters::returnSchemaOnlyForEditableLayers
• AGSGenerateOfflineMapParameters::definitionExpressionFilterEnabled
• AGSGenerateOfflineMapParameters::onlineOnlyServicesOption

Parameters

parameters	The parameters specifying how to take a map offline. For example, specify the area of interest, min and max scale, layer attachment options.
parameterOverrides	The overrides to the parameters.
downloadDirectory	The 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

parameters	specifying how to take the map offline.
completion	block 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

completion

A 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

onlineMap

to 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

portalItem

specifying 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

completion

block 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

onlineMap

to 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

portalItem

specifying 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

completion

block 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