OfflineMapTask Class

  • OfflineMapTask
  • class Esri::ArcGISRuntime::OfflineMapTask

    A task with methods related to taking a map offline and synchronizing online and offline maps. More...

    Header: #include <OfflineMapTask.h>
    Since: Esri::ArcGISRuntime 100.1
    Inherits: Esri::ArcGISRuntime::Object and Esri::ArcGISRuntime::Loadable

    Public Functions

    OfflineMapTask(Esri::ArcGISRuntime::Map *onlineMap, QObject *parent = nullptr)
    OfflineMapTask(Esri::ArcGISRuntime::PortalItem *portalItem, QObject *parent = nullptr)
    virtual ~OfflineMapTask() override
    QFuture<Esri::ArcGISRuntime::DownloadPreplannedOfflineMapParameters> createDefaultDownloadPreplannedOfflineMapParametersAsync(Esri::ArcGISRuntime::PreplannedMapArea *preplannedMapArea)
    QFuture<Esri::ArcGISRuntime::GenerateOfflineMapParameters> createDefaultGenerateOfflineMapParametersAsync(const Esri::ArcGISRuntime::Geometry &areaOfInterest)
    QFuture<Esri::ArcGISRuntime::GenerateOfflineMapParameters> createDefaultGenerateOfflineMapParametersAsync(const Esri::ArcGISRuntime::Geometry &areaOfInterest, double minScale, double maxScale)
    QFuture<Esri::ArcGISRuntime::GenerateOfflineMapParameterOverrides *> createGenerateOfflineMapParameterOverridesAsync(const Esri::ArcGISRuntime::GenerateOfflineMapParameters &parameters, QObject *parent = nullptr)
    Esri::ArcGISRuntime::DownloadPreplannedOfflineMapJob *downloadPreplannedOfflineMap(const Esri::ArcGISRuntime::DownloadPreplannedOfflineMapParameters &parameters, const QString &downloadDirectoryPath)
    Esri::ArcGISRuntime::GenerateOfflineMapJob *generateOfflineMap(const Esri::ArcGISRuntime::GenerateOfflineMapParameters &parameters, const QString &downloadDirectoryPath)
    Esri::ArcGISRuntime::GenerateOfflineMapJob *generateOfflineMap(const Esri::ArcGISRuntime::GenerateOfflineMapParameters &parameters, const QString &downloadDirectoryPath, Esri::ArcGISRuntime::GenerateOfflineMapParameterOverrides *parameterOverrides)
    QFuture<Esri::ArcGISRuntime::OfflineMapCapabilities> offlineMapCapabilitiesAsync(const Esri::ArcGISRuntime::GenerateOfflineMapParameters &parameters)
    Esri::ArcGISRuntime::Map *onlineMap() const
    Esri::ArcGISRuntime::PortalItem *portalItem() const
    Esri::ArcGISRuntime::PreplannedMapAreaListModel *preplannedMapAreaList() const
    QFuture<QList<Esri::ArcGISRuntime::PreplannedMapArea *>> preplannedMapAreasAsync(QObject *parent = nullptr)

    Reimplemented Public Functions

    virtual void cancelLoad() override
    virtual void load() override
    virtual Esri::ArcGISRuntime::Error loadError() const override
    virtual Esri::ArcGISRuntime::LoadStatus loadStatus() const override
    virtual void retryLoad() override

    Signals

    void doneLoading(const Esri::ArcGISRuntime::Error &loadError)
    void loadStatusChanged(Esri::ArcGISRuntime::LoadStatus loadStatus)

    Detailed Description

    Taking a map offline involves downloading an online map and its data, including all the supported layers, tables, renderers, web map configuration, and so on, so that the map may 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 offline 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. Download the offline map content to a device using the DownloadPreplannedOfflineMapJob. Note that this API refers to an offline map area as a PreplannedMapArea. 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 a GenerateOfflineMapJob 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 that uses online only services will require a network connection and may require authentication.

    Member Function Documentation

    [explicit] OfflineMapTask::OfflineMapTask(Esri::ArcGISRuntime::Map *onlineMap, QObject *parent = nullptr)

    Constructor that accepts an online map and a parent object.

    • onlineMap - The online map to take offline.
    • parent - The parent object of this OfflineMapTask.

    [explicit] OfflineMapTask::OfflineMapTask(Esri::ArcGISRuntime::PortalItem *portalItem, QObject *parent = nullptr)

    Constructor that accepts a portal item and a parent object.

    • portalItem - The portal item that is a map to take offline.
    • parent - The parent object of this OfflineMapTask.

    The PortalItem must be of type PortalItemType::WebMap, either on ArcGIS Online or an on-premise ArcGIS Enterprise Portal.

    [override virtual] OfflineMapTask::~OfflineMapTask()

    Destructor.

    [override virtual] void OfflineMapTask::cancelLoad()

    Reimplements: Loadable::cancelLoad().

    See Loadable.

    [since Esri::ArcGISRuntime 200.2] QFuture<Esri::ArcGISRuntime::DownloadPreplannedOfflineMapParameters> OfflineMapTask::createDefaultDownloadPreplannedOfflineMapParametersAsync(Esri::ArcGISRuntime::PreplannedMapArea *preplannedMapArea)

    Returns a QFuture of DownloadPreplannedOfflineMapParameters created from the specified PreplannedMapArea.

    • preplannedMapArea - The offline map area that is to be downloaded from the online map.

    A convenience method to create DownloadPreplannedOfflineMapParameters with default values appropriate for taking the specified map area offline.

    The parameters will be populated using the values in the online map's OfflineSettings (if present).

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [since Esri::ArcGISRuntime 200.2] QFuture<Esri::ArcGISRuntime::GenerateOfflineMapParameters> OfflineMapTask::createDefaultGenerateOfflineMapParametersAsync(const Esri::ArcGISRuntime::Geometry &areaOfInterest)

    Returns a QFuture of GenerateOfflineMapParameters created from the specified area of interest.

    • areaOfInterest - the region of the online map that is to be taken offline.

    The supported geometry types for the area of interest are Envelope and Polygon. The area of interest must have a spatial reference.

    Where a Polygon is supplied, features and tiles will be filtered according to the polygon geometry, which can help reduce the size of the resulting offline map. Note that the filtered set of tiles may vary, depending on the underlying service.

    The returned parameters min scale and max scale are zero so data will be taken at the full range of scales the services support.

    The returned GenerateOfflineMapParameters 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.

    The default parameters will be populated using the values in the online map's OfflineSettings (if present).

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [since Esri::ArcGISRuntime 200.2] QFuture<Esri::ArcGISRuntime::GenerateOfflineMapParameters> OfflineMapTask::createDefaultGenerateOfflineMapParametersAsync(const Esri::ArcGISRuntime::Geometry &areaOfInterest, double minScale, double maxScale)

    Returns a QFuture of GenerateOfflineMapParameters created from the specified area of interest, min scale and max scale.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [since Esri::ArcGISRuntime 200.2] QFuture<Esri::ArcGISRuntime::GenerateOfflineMapParameterOverrides *> OfflineMapTask::createGenerateOfflineMapParameterOverridesAsync(const Esri::ArcGISRuntime::GenerateOfflineMapParameters &parameters, QObject *parent = nullptr)

    Returns a QFuture of GenerateOfflineMapParameterOverrides created from the specified GenerateOfflineMapParameters parameters.

    • parameters - The generate offline map parameters from which the overrides will be populated.
    • parent - The optional parent QObject

    When the task completes the GenerateOfflineMapParameterOverrides will be populated reflecting the values in the GenerateOfflineMapParameters parameters. The overrides may be inspected and modified to change the offline data before passing onto creating a job with Esri::ArcGISRuntime::OfflineMapTask::generateOfflineMap

    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 GenerateOfflineMapParameters::continueOnErrors.

    If GenerateOfflineMapParameters::continueOnErrors is 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.

    To check upfront which layers or tables are valid for taking offline see Esri::ArcGISRuntime::OfflineMapCapabilities

    If GenerateOfflineMapParameters::referenceBasemapDirectory is set, the overrides corresponding to online basemap layers will be omitted, since no basemap layers will be downloaded.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [signal] void OfflineMapTask::doneLoading(const Esri::ArcGISRuntime::Error &loadError)

    Signal emitted when this object is done loading.

    • loadError Details about any error that may have occurred.

    Note: If there is a load error it will also be emitted on the errorOccurred signal.

    See also Loadable and Object.

    [since Esri::ArcGISRuntime 100.4] Esri::ArcGISRuntime::DownloadPreplannedOfflineMapJob *OfflineMapTask::downloadPreplannedOfflineMap(const Esri::ArcGISRuntime::DownloadPreplannedOfflineMapParameters &parameters, const QString &downloadDirectoryPath)

    Returns a job that is used to download the preplanned map area specified by the given parameters object.

    • parameters - Specifies parameters for the job including the preplanned map area to be downloaded.
    • downloadDirectoryPath - 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".

    Note: The job that is returned is not started 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.

    This function was introduced in Esri::ArcGISRuntime 100.4.

    Esri::ArcGISRuntime::GenerateOfflineMapJob *OfflineMapTask::generateOfflineMap(const Esri::ArcGISRuntime::GenerateOfflineMapParameters &parameters, const QString &downloadDirectoryPath)

    Returns a GenerateOfflineMapJob to run this OfflineMapTask.

    • parameters - The set of parameters to use to generate the offline content.
    • downloadDirectoryPath - 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".

    [since Esri::ArcGISRuntime 100.4] Esri::ArcGISRuntime::GenerateOfflineMapJob *OfflineMapTask::generateOfflineMap(const Esri::ArcGISRuntime::GenerateOfflineMapParameters &parameters, const QString &downloadDirectoryPath, Esri::ArcGISRuntime::GenerateOfflineMapParameterOverrides *parameterOverrides)

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

    • parameters - Parameters to specify how to take a map offline. For example, specify the area of interest, min and max scale, layer attachment options. Note that any properties relating to layers should be taken offline will be ignored and the values in the parameterOverrides will be used instead.
    • downloadDirectoryPath - 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".
    • parameterOverrides - The overrides to the parameters which control how individual services are taken offline. These take precedence over settings in the parameters.

    Note: The job that is returned is not started 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.

    To create an instance GenerateOfflineMapParameterOverrides use createGenerateOfflineMapParameterOverridesAsync.

    Some properties on GenerateOfflineMapParameters will be ignored when using GenerateOfflineMapParameterOverrides and replaced with equivalent properties for each service. The overridden properties are:

    This function was introduced in Esri::ArcGISRuntime 100.4.

    [override virtual] void OfflineMapTask::load()

    Reimplements: Loadable::load().

    See Loadable.

    [override virtual] Esri::ArcGISRuntime::Error OfflineMapTask::loadError() const

    Reimplements: Loadable::loadError() const.

    See Loadable.

    [override virtual] Esri::ArcGISRuntime::LoadStatus OfflineMapTask::loadStatus() const

    Reimplements: Loadable::loadStatus() const.

    See Loadable.

    [signal] void OfflineMapTask::loadStatusChanged(Esri::ArcGISRuntime::LoadStatus loadStatus)

    Signal emitted when the load status changes for this object.

    See also Loadable.

    [since Esri::ArcGISRuntime 200.2] QFuture<Esri::ArcGISRuntime::OfflineMapCapabilities> OfflineMapTask::offlineMapCapabilitiesAsync(const Esri::ArcGISRuntime::GenerateOfflineMapParameters &parameters)

    Returns an async QFuture which, when successful, returns the OfflineMapCapabilities containing information on which layers will be included in an offline map.

    • parameters - The parameters for taking a map offline.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    Esri::ArcGISRuntime::Map *OfflineMapTask::onlineMap() const

    Returns the online map.

    Esri::ArcGISRuntime::PortalItem *OfflineMapTask::portalItem() const

    Returns the portal item.

    [since Esri::ArcGISRuntime 100.2] Esri::ArcGISRuntime::PreplannedMapAreaListModel *OfflineMapTask::preplannedMapAreaList() const

    Returns the list of preplanned map areas populated by preplannedMapAreasAsync. Note that calling this method will load the OfflineMapTask if it is not already loaded.

    This function was introduced in Esri::ArcGISRuntime 100.2.

    See also PreplannedMapArea.

    [since Esri::ArcGISRuntime 200.2] QFuture<QList<Esri::ArcGISRuntime::PreplannedMapArea *>> OfflineMapTask::preplannedMapAreasAsync(QObject *parent = nullptr)

    Returns an async QFuture which when successful, contains a list of preplanned map areas, if there are any.

    • parent - The optional parent QObject

    Once the future is completed, all new PreplannedMapArea results will be availabe in the PreplannedMapAreaListModel immediately as well as the future's QList of results.

    Note that calling this method will load the OfflineMapTask if it is not already loaded.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    See also preplannedMapAreaList.

    [override virtual] void OfflineMapTask::retryLoad()

    Reimplements: Loadable::retryLoad().

    See Loadable.

    Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.