asyncDownload method

void onComplete(
1. GemError err
), {
void onProgress(
1. int progress
)?,
bool allowChargedNetworks = false,
DataSavePolicy savePolicy = DataSavePolicy.useDefault,
ContentDownloadThreadPriority priority = ContentDownloadThreadPriority.defaultPriority,

})

Start or resume an asynchronous download of the content product.

The method creates and registers a ProgressListener which will receive progress and completion events. The caller must provide a mandatory onComplete callback to receive the final outcome. When the operation finishes the listener's completion callback and the supplied onComplete are invoked with a GemError indicating success or the failure reason.

The callback can be changed later using setProgressListener or retrieved via the progressListener property.

Parameters

onComplete: Required callback invoked when the download completes. The function is called with:
- err — a GemError describing the final result. It is called with GemError.success on success, or another GemError value on failure.
onProgress: Optional callback invoked periodically with a single int argument (0..100) representing the current download progress.
allowChargedNetworks: When true, charged networks are allowed for this download. This overrides the global setting configured via SdkSettings.setAllowOffboardServiceOnExtraChargedNetwork for the ServiceGroupType.contentService group.
savePolicy: A DataSavePolicy value selecting where downloaded data will be stored.
priority: A ContentDownloadThreadPriority hint for downloader thread scheduling.

Returns

A ProgressListener instance associated with the download. The listener reports progress updates and completion. If the operation cannot be started an error is reported via the onComplete callback and a placeholder listener is returned.

Example

The following example starts a download and logs progress and completion:

item.asyncDownload((GemError err) {
  if (err == GemError.success) {
    print('Download finished successfully');
  } else {
    print('Download failed: $err');
  }
}, onProgress: (int p) {
  print('Download progress: $p%');
});

Also see:

pauseDownload - Pause an ongoing download.
cancelDownload - Cancel an ongoing download.
setProgressListener - Change the progress listener callbacks.
progressListener - Access the current progress listener.

Implementation

ProgressListener asyncDownload(
  final void Function(GemError err) onComplete, {
  final void Function(int progress)? onProgress,
  final bool allowChargedNetworks = false,
  final DataSavePolicy savePolicy = DataSavePolicy.useDefault,
  final ContentDownloadThreadPriority priority =
      ContentDownloadThreadPriority.defaultPriority,
}) {
  final EventDrivenProgressListener progListener =
      EventDrivenProgressListener();
  final OperationResult resultString = objectMethod(
    pointerId,
    'ContentStoreItem',
    'asyncDownload',
    args: <String, dynamic>{
      'listener': progListener.id,
      'allowChargedNetworks': allowChargedNetworks,
      'savePolicy': savePolicy.id,
      'priority': priority.id,
    },
  );

  if (resultString.containsKey('error')) {
    onComplete(GemErrorExtension.fromCode(resultString['error']));
    return EventDrivenProgressListener.init(0);
  }

  if (onProgress != null) {
    progListener.registerOnProgress((final int p0) {
      onProgress.call(p0);
    });
  }

  progListener.registerOnCompleteWithData((
    final int err,
    final String hint,
    final Map<dynamic, dynamic> json,
  ) {
    if (err == 0) {
      onComplete(GemErrorExtension.fromCode(0));
    } else {
      onComplete(GemErrorExtension.fromCode(err));
    }
  });
  GemKitPlatform.instance.registerEventHandler(progListener.id, progListener);
  return progListener;
}