Download Files

This guide describes the methods to download files from cloud storage.

Download File

The downloading of files is done by adding a file to the download queue in the following way.

Enqueue File

The Files SDK provides two functions for downloading files from cloud storage to a mobile device.

fun enqueueFile(fileItem: FileItem, destDirUri: Uri, isPassToScanner: Boolean = false)

This function allows you to specify the directory to save the file as a Uri.

Another function allows you to specify the absolute path to the directory:

fun enqueueFile(fileItem: FileItem, destDirPath: String, isPassToScanner: Boolean = false)

Parameters:

• fileItem - a file in the cloud storage that you need to download to your local device.
• destDirUri specifies the directory on the device as a Uri where to place the downloaded file.
• destDirPath sets the directory on a device as the absolute path (String).
• isPassToScanner - If true, the Files SDK will try to add the downloaded file to the device's media collection (for example, the image will be added to the gallery on a device).

The application usually calls the Uri option if it uses the SAF (Storage Access Framework) to select the file save directory.

If the application has full access to the local storage and uses its own UI to select a directory, it can be easier to pass a direct path to the directory via the destDirPath parameter.

The following code example demonstrates adding a file to the download queue.

// File item from the cloud.val fileItem: FileItem
// The Uri of the directory on the device where to place the downloaded files.// App usually receives uri when it starts Intent.ACTION_OPEN_DOCUMENT_TREEvar destDirUri: Uri = // ...
// Adds file to the download queue.FileManager.downloader.enqueueFile(fileItem, destDirUri)

important

If the application passes the absolute path of target directory to the function and this directory is located outside of the app-specific directory, then the application must have write access to the shared local storage. Otherwise, the file downloading will be failed.

Cancel Downloading

The following code example demonstrates a cancellation of a file download.

// File item to be cancelled.val fileItem: FileItem
// ...
// Removes file from downloading queue.FileManager.downloader.cancelFile(fileItem)

Download Monitoring

The library provides the following functionality for monitoring downloading.

Monitoring the download queue

The following code example demonstrates getting a queue observable.

var disposable: Disposable? = null
// Sort mode.val sortMode: FileTreeBrowser.Sort = FileTreeBrowser.Sort.NO_SORTING// FileTreeBrowser.Sort:// * NO_SORTING - No sorting (default)// * NAME_ASC_DIR_FIRST - Sort by name ascending; Directories first.// * TYPE_ASC_DIR_FIRST - Sort by type ascending; Directories first.// * MODIFIED_DESC_DIR_FIRST - Sort by modification time descending; Directories first.// * SIZE_DESC_DIR_FIRST - Sort by size descending; Directories first.
// ...
// Returned observable that emits downloading queue content every time// when one of the following is changed:// * New file enqueued for downloading// * File cancelled downloading// * File status changed// * Progress changed//// You have to subscribe on returned observable in order to receive updates.disposable = FileManager.downloader.getQueueObservable(sortMode)        .subscribe { // it: List<FileItem>            // Update your recycler view adapter with received list.        }
// ...
// You must call dispose() on disposable that returned by subscribe() method,// when it no longer needed, for example in your fragment’s onStop() or onPause().disposable?.dispose()

Single File download monitoring

To monitor the download progress of the file item, caller must first enqueue this file item for download (see Enqueue File), then call getItemObservable() and then subscribe to the returned observable. Calling of getItemObservable() before enqueuing the file item will lead to unpredictable results because of internal subscription to a wrong or an invalid model.

The following code example demonstrates getting an observable of the file item being downloaded.

var disposable: Disposable? = null
// File item for monitoring.val sortMode: FileItem
// ...
// Returns Observable, which emits updates of file item being downloaded every time// when one of the following is changed:// * Progress changed;// * File status changed;// * File cancelled downloading.//// You have to subscribe on returned observable in order to receive updates.disposable = FileManager.downloader.getItemObservable(fileItem)        .subscribeBy(            onNext = { // it: FileItem                // Update yout UI            },            onError = { // it: Throwable                // Update yout UI            },            onComplete = {                // If at the moment of subscription the file item is already downloaded,                         // returned observable completes immediately after                // emitting of current file item.            }        )
// ...
// You must call dispose() on disposable that returned by subscribe() method,// when it no longer needed, for example in your fragment’s onStop() or onPause().disposable?.dispose()

Download Status

The following code example demonstrates how to subscribe to a download status observable.

var disposable: Disposable? = null
// ...
// Returns Observable, which emits DownloaderEvent each time when downloading status changed.// You have to subscribe on returned observable in order to receive updates.disposable = FileManager.downloader.downloadStatus.subscribe { // it: DownloaderEvent    // To determine that all downloads finished (successfully or with error)     // and queue is empty, check the following condition::    if (it.filesLeft == 0 && (it.isDone || it.isCancelled || it.error != null)) {        // queue is empty    } else {        // queue is not empty    }}
// ...
// You must call dispose() on disposable that returned by subscribe() method,// when it no longer needed, for example in your fragment’s onStop() or onPause().disposable?.dispose()

Get Cached Queue

The following code example demonstrates getting a cached queue observable.

var disposable: Disposable? = null
// FileItem list for caching.val fileItemList: List<FileItem>
// Sort mode.val sortMode: FileItem// FileTreeBrowser.Sort:// * NO_SORTING - No sorting (default)// * NAME_ASC_DIR_FIRST - Sort by name ascending; Directories first.// * TYPE_ASC_DIR_FIRST - Sort by type ascending; Directories first.// * MODIFIED_DESC_DIR_FIRST - Sort by modification time descending; Directories first.// * SIZE_DESC_DIR_FIRST - Sort by size descending; Directories first.
// ...
// Returns Observable, which emits emits content of downloading queue.// You have to subscribe on returned observable in order to receive updates.disposable += FileManager.downloader.getCachedQueueObservable(fileItemList, sort)        .observeOn(AndroidSchedulers.mainThread())        .subscribeBy(                onError = {                    // Handle it                },                onSuccess = {                    // Handle it                }        )
// ...
// You must call dispose() on disposable that returned by subscribe() method,// when it no longer needed, for example in your fragment’s onStop() or onPause().disposable?.dispose()

Links - FileDownloader, FileTreeBrowser.Sort, FileItem, DownloaderEvent.