GeodatabaseSyncTask Class

Member Function Documentation

[explicit] GeodatabaseSyncTask::GeodatabaseSyncTask(const QUrl &url, QObject *parent = nullptr)

Creates a geodatabase sync task object using a URL to a sync-enabled ArcGIS feature service.

• url - A URL to an ArcGIS feature service with the sync capability enabled.
• parent - The optional parent QObject.

GeodatabaseSyncTask::GeodatabaseSyncTask(const QUrl &url, Esri::ArcGISRuntime::Credential *credential, QObject *parent = nullptr)

Constructs a GeodatabaseSyncTask with a URL and a credential.

• url - The URL of the sync-enabled ArcGIS feature service.
• credential - The credential.
• parent - The parent object for this GeodatabaseSyncTask (optional).

[override virtual] GeodatabaseSyncTask::~GeodatabaseSyncTask()

Destructor.

[override virtual] QString GeodatabaseSyncTask::apiKey() const

Reimplements: ApiKeyResource::apiKey() const.

Returns the API key allows your app to access ArcGIS location services and private portal items.

An API key is a unique long-lived access token that is used to authenticate and monitor requests to ArcGIS location services and private portal items. You can create and manage an API key using your portal when you sign in with an ArcGIS Location Platform account or an ArcGIS Online account with administrator access or a custom role that has the `Generate API keys` privilege. To learn how to create and manage API keys, go to the Create an API Key tutorial. You must ensure that your API key has the correct privileges to access secure resources.

Note: An API key created with a referrer is not supported. If you need service requests to include the referrer, use the SDK's functionality to intercept the request and add an HTTP referer header.

In addition to setting an ArcGISRuntimeEnvironment::apiKey at a global level for your application, you can set it on any class that implements ApiKeyResource. This overrides the ArcGISRuntimeEnvironment::apiKey and enables more granular usage telemetry and management of ArcGIS location resources used by your app.

Classes that expose an API key property by implementing ApiKeyResource include:

• Basemap
• ArcGISSceneLayer
• ArcGISTiledLayer
• ArcGISVectorTiledLayer
• ServiceFeatureTable
• ExportVectorTilesTask
• LocatorTask
• GeodatabaseSyncTask
• ClosestFacilityTask
• RouteTask
• ServiceAreaTask
• ExportTileCacheTask

For more information, see API key authentication and Types of authentication.

See also setApiKey().

[override virtual] void GeodatabaseSyncTask::cancelLoad()

Reimplements: Loadable::cancelLoad().

Cancels loading metadata for the object.

See Loadable.

[since Esri::ArcGISRuntime 200.2] QFuture<Esri::ArcGISRuntime::GenerateGeodatabaseParameters> GeodatabaseSyncTask::createDefaultGenerateGeodatabaseParametersAsync(const Esri::ArcGISRuntime::Geometry &extent)

Creates default parameters to generate and download a geodatabase using the GenerateGeodatabaseJob.

• extent - The extent of the data to be included in the generated geodatabase. Must be non-empty.

This populates the parameters with values that match the feature service. For example, if the service does not support SyncModel::Layer then SyncModel::Geodatabase will be used and all layers from the service will be included. Attachments are included by default, but related tables/layers are not included. Output features are in the spatial reference of the given extent.

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::SyncGeodatabaseParameters> GeodatabaseSyncTask::createDefaultSyncGeodatabaseParametersAsync(Esri::ArcGISRuntime::Geodatabase *geodatabase)

Creates default parameters to synchronize a geodatabase using the SyncGeodatabaseJob.

• geodatabase - a geodatabase to sync.

This populates the parameters with values that match the geodatabase sync task's feature service and the geodatabase. For a geodatabase with SyncModel::Layer then all geodatabase layers will be included. If the service is read-only then the sync direction will be SyncDirection::Download. Otherwise the sync direction will be SyncDirection::Bidirectional.

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::SyncGeodatabaseParameters> GeodatabaseSyncTask::createDefaultSyncGeodatabaseParametersAsync(Esri::ArcGISRuntime::Geodatabase *geodatabase, Esri::ArcGISRuntime::SyncDirection syncDirection)

Creates default parameters for a sync geodatabase using the given sync direction.

• geodatabase - a geodatabase to sync.
• syncDirection - the sync direction to use.

This populates the parameters with values that match the geodatabase sync task's feature service and the geodatabase. For a geodatabase with SyncModel::Layer then all geodatabase layers will be included. A service is editable if it has capabilities that include any of create, update or delete. In this case both SyncDirection::Bidirectional and SyncDirection::Upload are supported sync directions. Alternatively, a service that does not have create, update or delete capability is considered read-only and only SyncDirection::Download will be supported. If the given sync direction is not compatible with the geodatabase sync task's feature service or the geodatabase is not sync-enabled, the returned task will fail.

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.

[override virtual] Esri::ArcGISRuntime::Credential *GeodatabaseSyncTask::credential() const

Reimplements: RemoteResource::credential() const.

Returns the security credential used to access the service.

Only applicable if using an service that is secured.

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

Signal emitted when this object is done loading.

• loadError - Details about any error that may have occurred.

See also Loadable and Object.

[static, since Esri::ArcGISRuntime 200.2] QFuture<bool> GeodatabaseSyncTask::exportDeltaAsync(Esri::ArcGISRuntime::Geodatabase *geodatabase, const QString &outputPath)

Generates an upload delta geodatabase file containing all the changes since the last sync.

• geodatabase - The geodatabase to generate a delta from.
• outputPath - The path and filename to save the generated delta to.

A delta geodatabase contains the changes that have occurred since a mobile replica Geodatabase was last-synchronized with the feature service. See Synchronize Replica for an overview of the delta files used in synchronization. An "upload" delta geodatabase contains the local edits, performed on the user's device, to be sent to the originating feature service.

When you run this task, any local edits in the Geodatabase will be exported to the specified output path. The output path should include the full path and file name (ending in ".geodatabase") for the export.

The delta file created by this method is not sent to the server and has no impact on any subsequent sync job. You can call this method repeatedly without affecting the state of the local geodatabase.

The task returned by this method has a boolean result that indicates whether or not a delta geodatabase was created.

You should not execute more than one sync on a particular geodatabase at the same time. This includes any operations that export or import deltas from the local Geodatabase, which are:

• exportDeltaAsync(Esri::ArcGISRuntime::Geodatabase*, const QString&)
• importDeltaAsync(Esri::ArcGISRuntime::Geodatabase*, const QString&, QObject*)
• SyncGeodatabaseJob
• OfflineMapSyncJob

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 SyncGeodatabaseParameters::isKeepGeodatabaseDeltas.

Esri::ArcGISRuntime::ArcGISFeatureServiceInfo GeodatabaseSyncTask::featureServiceInfo() const

Returns metadata about the ArcGIS feature service.

This information is available when the task is loaded.

Esri::ArcGISRuntime::GenerateGeodatabaseJob *GeodatabaseSyncTask::generateGeodatabase(const Esri::ArcGISRuntime::GenerateGeodatabaseParameters &parameters, const QString &pathToGeodatabaseFile)

Returns a job to generate and download a geodatabase from an ArcGIS feature service.

• parameters - The parameters for generate geodatabase.
• pathToGeodatabaseFile - a path including a new filename where the downloaded geodatabase is written to.

The result of the job will be of type Geodatabase.

The pathToGeodatabaseFile can specify a path for the downloaded geodatabase, including the desired name and the .geodatabase file extension. Or, pathToGeodatabaseFile can be a filename only, in which case the file extension is added and the geodatabase is stored in the user's Documents folder.

A GenerateGeodatabaseJob representing the progress on the server is returned.

The returned job is in the JobStatus::NotStarted state. Start it by calling Job::start().

The job should be deleted after completion.

See also Job.

[static, since Esri::ArcGISRuntime 200.2] QFuture<QList<Esri::ArcGISRuntime::SyncLayerResult *>> GeodatabaseSyncTask::importDeltaAsync(Esri::ArcGISRuntime::Geodatabase *geodatabase, const QString &inputPath, QObject *parent)

Imports a geodatabase delta and applies it to the given geodatabase.

• geodatabase - The geodatabase to apply a delta to.
• inputPath - The path and filename to import the delta from.
• parent - A mandatory QObject parent. Since this method is static, results will have no parent by default.

A delta geodatabase contains the changes that have occurred since a mobile replica Geodatabase was last-synchronized with the feature service. See https://developers.arcgis.com/rest/services-reference/enterprise/synchronize-replica.htm for an overview of the delta files used in synchronization. A "download" delta geodatabase contains the online edits that will be imported to the local geodatabase.

The task returned by this method returns an array of SyncLayerResult.

You should not execute more than one sync on a particular geodatabase at the same time. This includes any operations that export or import deltas from the local Geodatabase, which are:

• exportDeltaAsync(Esri::ArcGISRuntime::Geodatabase*, const QString&)
• importDeltaAsync(Esri::ArcGISRuntime::Geodatabase*, const QString&, QObject*)
• SyncGeodatabaseJob
• OfflineMapSyncJob

If you want the result to have no parent, pass nullptr as the parent. Be sure to manage the memory of the result or it will leak.

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.

[static, since Esri::ArcGISRuntime 100.3] Esri::ArcGISRuntime::GeodatabaseSyncTask *GeodatabaseSyncTask::instance()

Returns an instance of the GeodatabaseSyncTask singleton.

The instance is used to connect to the Object::errorOccurred, and importDeltaCompleted signals. You do not need to obtain the instance to call the static methods on the GeodatabaseSyncTask.

This function was introduced in Esri::ArcGISRuntime 100.3.

[override virtual] void GeodatabaseSyncTask::load()

Reimplements: Loadable::load().

Loads the metadata for the object asynchronously.

See Loadable.

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

Reimplements: Loadable::loadError() const.

Returns the load error.

See Loadable.

See also Error.

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

Reimplements: Loadable::loadStatus() const.

Returns the load status.

See Loadable.

See also LoadStatus.

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

Signal emitted when the load status changes for this object.

• loadStatus - The LoadStatus.

See also Loadable.

[since Esri::ArcGISRuntime 200.2] QFuture<void> GeodatabaseSyncTask::registerSyncEnabledGeodatabaseAsync(Esri::ArcGISRuntime::Geodatabase *geodatabase)

Registers a copy of a sync enabled geodatabase with a service to allow the copy to sync changes.

• geodatabase - a geodatabase to register.

This method is typically used as part of services pattern workflow, sometimes known as a pre-planned workflow. A sync enabled geodatabase is generated centrally and not modified or synced. Copies of this original geodatabase are distributed and loaded onto each user's device. The copy must first be registered with the service to allow the server to identify changes in subsequent sync operations. One of the main benefits of this workflow is a reduction in server load to generate geodatabases for many clients. It is important not to sync the copy before registering to ensure the server can maintain consistent state on each copy. This operation is not the opposite of unregisterGeodatabaseAsync(const QUuid&) which is used to remove a geodatabase from the service prior to deletion.

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.

[override virtual, since Esri::ArcGISRuntime 100.1] Esri::ArcGISRuntime::RequestConfiguration GeodatabaseSyncTask::requestConfiguration() const

Reimplements: RemoteResource::requestConfiguration() const.

Returns the RequestConfiguration in use by this task.

This function was introduced in Esri::ArcGISRuntime 100.1.

See also setRequestConfiguration().

[override virtual] void GeodatabaseSyncTask::retryLoad()

Reimplements: Loadable::retryLoad().

Loads or retries loading metadata for the object asynchronously.

Will retry loading the metadata if the object is failed to load. Will load the object if it is not loaded. Will not retry to load the object if the object is loaded.

See Loadable.

[override virtual] void GeodatabaseSyncTask::setApiKey(const QString &apiKey)

Reimplements: ApiKeyResource::setApiKey(const QString &apiKey).

Sets the apiKey to apiKey.

See also apiKey.

[override virtual, since Esri::ArcGISRuntime 100.1] void GeodatabaseSyncTask::setRequestConfiguration(const Esri::ArcGISRuntime::RequestConfiguration &requestConfiguration)

Reimplements: RemoteResource::setRequestConfiguration(const Esri::ArcGISRuntime::RequestConfiguration &requestConfiguration).

Sets configuration parameters used for network requests sent by this task to requestConfiguration.

This function was introduced in Esri::ArcGISRuntime 100.1.

See also requestConfiguration().

Esri::ArcGISRuntime::SyncGeodatabaseJob *GeodatabaseSyncTask::syncGeodatabase(const Esri::ArcGISRuntime::SyncGeodatabaseParameters &parameters, Esri::ArcGISRuntime::Geodatabase *geodatabase)

Returns a job to synchronize a geodatabase back to a service.

• parameters - Parameters to use to sync the geodatabase.
• geodatabase - The geodatabase to sync.

For a successfully completed job the job's result returns an array of SyncLayerResult, typically the array is empty. If individual edits failed then the result array provides these errors grouped by each table using SyncLayerResult instances which in turn contain each edit error.

You should not execute more than one sync on a particular geodatabase at the same time. This includes any operations that export or import deltas from the local Geodatabase, which are:

• exportDeltaAsync(Esri::ArcGISRuntime::Geodatabase*, const QString&)
• importDeltaAsync(Esri::ArcGISRuntime::Geodatabase*, const QString&, QObject*)
• SyncGeodatabaseJob
• OfflineMapSyncJob

See also Job.

[since Esri::ArcGISRuntime 100.3] Esri::ArcGISRuntime::SyncGeodatabaseJob *GeodatabaseSyncTask::syncGeodatabase(Esri::ArcGISRuntime::SyncDirection syncDirection, bool rollbackOnFailure, Esri::ArcGISRuntime::Geodatabase *geodatabase)

Returns a job to sync a mobile geodatabase with its originating ArcGIS Feature service using the given sync direction and rollback on failure Boolean value.

• syncDirection - The preferred sync direction.
• rollbackOnFailure - Whether to roll back edits when a failure occurs.
• geodatabase - The geodatabase to sync with the service.

The result of the job will be a list of SyncLayerResult objects. This list will be empty for a successfully completed job. If individual edits failed then the result provides these errors grouped by each table using SyncLayerResult instances. These contain information for each edit error as a FeatureEditResult.

If rollbackOnFailure is false, then failed edits are skipped. Other edits are still applied. This property only applies to edits uploaded by the client to the server. It does not apply to edits imported by client from the server.

If the given sync direction is not compatible with the sync task's feature service, the returned job will fail.

You should not execute more than one sync on a particular geodatabase at the same time. This includes any operations that export or import deltas from the local Geodatabase:

• exportDeltaAsync(Esri::ArcGISRuntime::Geodatabase*, const QString&)
• importDeltaAsync(Esri::ArcGISRuntime::Geodatabase*, const QString&, QObject*)
• SyncGeodatabaseJob
• OfflineMapSyncJob

A SyncGeodatabaseJob representing the progress on the server is returned. The returned job is in the JobStatus::NotStarted state. Start it by calling Job::start().

The job should be deleted after completion.

This function was introduced in Esri::ArcGISRuntime 100.3.

See also Job.

[since Esri.ArcGISRuntime 200.2] QFuture<void> GeodatabaseSyncTask::unregisterGeodatabaseAsync(Esri::ArcGISRuntime::Geodatabase *geodatabase)

Unregisters a geodatabase from a service removing the services replica id.

• geodatabase - a geodatabase to unregister.

After unregistering a geodatabase it can no longer be synced back to the service. This is often used prior to deleting a local geodatabase. This operation is not related to registerSyncEnabledGeodatabaseAsync(Esri::ArcGISRuntime::Geodatabase*), which is for registering copies of a sync-enabled geodatabase.

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<void> GeodatabaseSyncTask::unregisterGeodatabaseAsync(const QUuid &syncId)

Unregisters a geodatabase from its source ArcGIS feature service using the geodatabases sync ID. This removes the services replica id.

• syncId - sync ID of geodatabase to unregister.

This method is used to unregister a geodatabase from a service using the sync ID. This is commonly used to enable cleanup of the service after the local geodatabase has already been deleted. See Geodatabase::syncId. After unregistering a geodatabase it can no longer be synced back to the service. This operation is not related to registerSyncEnabledGeodatabaseAsync(Esri::ArcGISRuntime::Geodatabase*), which is for registering copies of a sync-enabled geodatabase.

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.

[override virtual] QUrl GeodatabaseSyncTask::url() const

Reimplements: RemoteResource::url() const.

Returns the URL of the ArcGIS feature service.

This property is only writable when the task is in load status LoadStatus::NotLoaded.