ArcGIS Runtime SDK for iOS
100.15
|
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:
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.
Class Methods | |
(instancetype) | + offlineMapTaskWithOnlineMap: |
(instancetype) | + offlineMapTaskWithPortalItem: |
Properties | |
NSError * | loadError |
AGSLoadStatus | loadStatus |
AGSMap * | onlineMap |
AGSPortalItem * | portalItem |
|
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
- (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).
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. |
- (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.
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. |
- (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.
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. 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. |
- (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
.
Provided by category AGSLoadableBase(ForSubclassEyesOnly).
- (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.
retrying | flag that is true if this method was called from retryLoadWithCompletion: (AGSLoadable-p) . |
Provided by category AGSLoadableBase(ForSubclassEyesOnly).
- (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.
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". |
AGSDownloadPreplannedOfflineMapJob
to download a preplanned map area. 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).
- (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.
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. |
AGSDownloadPreplannedOfflineMapJob
object to download a preplanned map area. downloadPreplannedOfflineMapJobWithParameters:downloadDirectory:
. Use AGSDownloadPreplannedOfflineMapParameters::includeBasemap
to set basemap inclusion. Note reversal of logic from 'exclude basemap' to 'include basemap'. Provided by category AGSOfflineMapTask(AGSDeprecated).
- (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
.
startWithStatusHandler:completion: (AGSGenerateOfflineMapJob)
. 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. |
- getPreplannedMapAreasWithCompletion:
to get a list of preplanned map areas for the map this task's onlineMap
property. - (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
.
startWithStatusHandler:completion: (AGSGenerateOfflineMapJob)
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. |
AGSGenerateOfflineMapResult
. The job will fail if download directory cannot be created or is not empty. - (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.
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 | 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. |
AGSGenerateOfflineMapResult
. The job will fail if download directory cannot be created or is not empty. - (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
.
- (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 | 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. |
- (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.
AGSOfflineMapTask
if it is not already loaded. completion | A block that is invoked with the list of preplanned map areas if the operation succeeds, or an error if it fails. |
- (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.
onlineMap | to take offline. |
- (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.
portalItem | specifying a map to take offline. |
- (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.
Provided by category AGSLoadableBase(ForSubclassEyesOnly).
|
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.
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. |
- cancelLoad
to cancel loading - retryLoadWithCompletion:
to force reload + (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.
onlineMap | to take offline. |
+ (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.
portalItem | specifying a map to take offline. |
- (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.
Provided by category AGSLoadableBase(ForSubclassEyesOnly).
|
requiredinherited |
Tries to reload when an object has failed to load. This method should be called judiciously. It should be called when:
cancelLoad
and then this methodIf 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.
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. |
|
readnonatomicstronginherited |
The error that was encountered during the most recent load operation. Will be nil if the operation succeeded.
|
readrequirednonatomicassigninherited |
Status of the load operation.
|
readnonatomicstrong |
The map to take offline. The map must be a web map either on ArcGIS Online or an on-premises ArcGIS Portal.
|
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.