Oggi vi voglio parlare di un componente della raccolta Jetpack di Android, “DownloadManager”, insieme ad una breve panoramica e guida del suo utilizzo.
Potrete consultare un esempio completo attraverso questo repository di Github. Gli snippet di codice successi saranno presi da questo progetto.
Inoltre, è disponibile su PlayStore l’applicazione di prova che ho creato appositamente come supporto a questo articolo.

Guida DownloadManager: Di cosa tratta?

DownloadManager è un servizio di sistema Android che gestisce i download HTTP di lunga/breve durata. Non richiede implementazioni di librerie aggiuntive, poiché si trova all’interno del’ SDK di Android.
Le applicazioni possono richiedere a questo servizio di scaricare un Uri e di salvarlo in uno specifico percorso, che sia privato dell’applicazione o pubblico.

DownloadManager si occuperà infine di gestire il processo in background di download, delle interazioni HTTP e ripartirà dall’inizio in caso di fallimento o di riavvio del dispositivo.

I permessi necessari

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.DOWNLOAD_WITHOUT_NOTIFICATION" />

• android.permission.INTERNET
  Necessario per le applicazioni per accedere ad internet.
• (OPZIONALE) android.permission.DOWNLOAD_WITHOUT_NOTIFICATION
  Necessario per usare DownloadManager senza rendere visibile la notifica (DownloadManager.Request.VISIBILITY_HIDDEN) di download del file. Nel caso si lasciasse la notifica visibile, tale permesso non è necessario.

Come potete vedere, l’utilizzo di questo componente non prevede l’utilizzo di particolari permessi (soprattutto quelli catalogati da Android come “pericolosi”).

Come richiedere un download

Per prima cosa, è necessario creare una istanza della classe DownloadManager. Come tutti i servizi di sistema Android, non viene creata un istanza dal costruttore ma viene richiesta dal contesto:

val downloadManager = context.getSystemService(Context.DOWNLOAD_SERVICE) as DownloadManager

Ora che abbiamo creato l’oggetto, possiamo inviargli una richiesta di download, creando un oggetto di classe DownloadManager.Request.
Questa classe ha l’obiettivo di contenere tutte le informazioni necessarie a DownloadManager per poter gestire il download di un File:

private fun generateDownloadRequest():DownloadManager.Request{

//Creiamo un oggetto DownloadManager.Request e 
//gli passiamo l'url per il download del file
val request:DownloadManager.Request = DownloadManager.Request(Uri.parse("http://url_file.pdf"))
//Impostiamo il titolo della notifica che verrà visualizzata    
request.setTitle(txt_notification_title.editText?.text.toString())
//Impostiamo la descrizione della notifica che verrà visualizzata        
request.setDescription(txt_notification_description.editText?.text.toString())
//impostiamo la destinazione del file, in questo caso sarà nella cartella privata dell'applicazione "Downloads". Il nome del file sarà testFile
request.setDestinationInExternalFilesDir(this, Environment.DIRECTORY_DOWNLOADS,"testFile")
//impostiamo se il download ha il permesso di usare il traffico della rete mobile
request.setAllowedOverMetered(true)
 //impostiamo se il download ha il permesso di scaricare anche in caso fossimo in roaming       
request.setAllowedOverRoaming(true)
 
//Build.VERSION_CODES.N o maggiore: Impostiamo se il 
//download deve partire solo se il dispositivo è in carica         
request.setRequiresCharging(false)
//Build.VERSION_CODES.N o maggiore: Impostiamo se il 
//download deve partire solo se il dispositivo è in
//modalità Idle (inattivo)
request.setRequiresDeviceIdle(false)

//Impostiamo se si visualizza o meno la notifica di download
//
//DownloadManager.Request.VISIBILITY_VISIBLE_NOTIFY_COMPLETED
//Notifica visibile sia durante che a completamento del download
//
//DownloadManager.Request.VISIBILITY_HIDDEN
//Mai visualizzata. Ricordarsi di aggiungere al manifest il permesso
//android.permission.DOWNLOAD_WITHOUT_NOTIFICATION
//
//DownloadManager.Request.VISIBILITY_VISIBLE
//Notifica visibile solo durante il download. A download completato
//scompare
//
request.setNotificationVisibility(DownloadManager.Request.VISIBILITY_VISIBLE_NOTIFY_COMPLETED)

  return request
 }

In questo esempio ho cercato di includere tutti i vari parametri che vi può essere utile modificare, con relativa descrizione nei commenti,

Una volta creata la richiesta, sarà possibile passarla al DownloadManager in questo modo:

val id:Long = downloadManager.enqueue(request)

Molto importante è il valore restituito da DownloadManager.enqueue: Si tratta dell’identificativo che il sistema ha assegnato alla richiesta. Sarà importante per capire quando il download è terminato (Sia nel bene che nel male).

Intercettare il completamento del download

Per capire se il download richiesto è terminato è necessario registriare un receiver nel manifest (oppure anche runtime):

<receiver android:name=".receiver.DownloadManagerReceiver">
     <intent-filter>
        <action android:name="android.intent.action.DOWNLOAD_COMPLETE" />
        <action
android:name="android.intent.action.DOWNLOAD_NOTIFICATION_CLICKED"/>
     </intent-filter>
</receiver>

Le azioni registrate ed inviate da DownloadManager sono:

• android.intent.action.DOWNLOAD_COMPLETE
  Invia questo evento quando un Download è stato completato.
• android.intent.action.DOWNLOAD_NOTIFICATION_CLICKED
  Invia questo evento quando l’utente clicca sulla notifica mentre il download è ANCORA in corso.

import android.app.DownloadManager
import android.content.BroadcastReceiver
import android.content.Context
import android.content.Intent
import android.util.Log
import android.widget.Toast
import com.danielebachicchi.jetpackdownloadmanagerexample.utils.DownloadManagerUtils
import com.danielebachicchi.jetpackdownloadmanagerexample.item.DownloadObject

class DownloadManagerReceiver: BroadcastReceiver() {
 
    override fun onReceive(p0: Context?, p1: Intent?) {
        val action:String? = p1?.action
 
        var downloadID:Long = -1

        if(DownloadManager.ACTION_DOWNLOAD_COMPLETE == action){
            //ritirare l'id del download completato
            downloadID = p1.getLongExtra(DownloadManager.EXTRA_DOWNLOAD_ID,-1)

            val downloadManager:DownloadManager = p0!!.getSystemService(Context.DOWNLOAD_SERVICE) as DownloadManager
                
            val downloadObject: DownloadObject? =
                DownloadManagerUtils.queryDownloadManagerObject(
                    downloadManager,
                    downloadID
                )
            //Ora abbiamo l'oggetto con tutte le 
            //informazioni del download, potete
           //fare tutto quello che volete!

        }else if (DownloadManager.ACTION_NOTIFICATION_CLICKED == action){
            downloadID = p1.getLongExtra(DownloadManager.EXTRA_DOWNLOAD_ID,-1)

          //Gestite il caso in cui la notifica del 
          //download di downloadID è stata cliccata
          //dall'utente

        }
    }
}

fun queryDownloadManagerObject(downloadManager:DownloadManager, id:Long): DownloadObject?{

           val cursor:Cursor = downloadManager.query(DownloadManager.Query().setFilterById(id))

            var result: DownloadObject? = null
            if (cursor.moveToFirst())
                result = DownloadObject.fromCursor(cursor)


           return result


        }

DownloadManager.query ritorna un Cursor con le informazioni del download richiesto (tramite l’id dell’oggetto, passato da DownloadManager alla richiesta del download). Se ritorna almeno un risultato si procede alla conversione del Cursor ad oggetto:

import android.app.DownloadManager
import android.database.Cursor
import java.util.*

class DownloadObject (val uri:String,
                      val localUri:String,
                      val bytesDownloaded:Long,
                      val bytesTotal:Long,
                      val id:Long,
                      val title:String,
                      val description:String,
                      val date:Date,
                      val mediaProviderUri:String?,
                      val mediaType:String,
                      val reason:String,
                      val status:Int) {



    companion object{
        /*
        --- DownloadManager Row Example ---
        _id : 45
        mediaprovider_uri : null
        destination : 2
        title : Download Test
        description : Downloading a file for testing Download Manager API
        uri : http://ipv4.download.thinkbroadband.com/10MB.zip
        status : 200
        hint : null
        media_type : application/zip
        total_size : 10485760
        last_modified_timestamp : 1565972803944
        bytes_so_far : 10485760
        allow_write : 0
        local_uri : content://downloads/all_downloads/45
        reason : placeholder
         --- End Row ---*/
        fun fromCursor(cursor:Cursor): DownloadObject {
            val uri = cursor.getString(cursor.getColumnIndex(DownloadManager.COLUMN_URI))
            
            val localUri = cursor.getString(cursor.getColumnIndex(DownloadManager.COLUMN_LOCAL_URI))
            
            val bytesDownloaded = cursor.getLong(cursor.getColumnIndex(DownloadManager.COLUMN_BYTES_DOWNLOADED_SO_FAR))
            
            val description = cursor.getString(cursor.getColumnIndex(DownloadManager.COLUMN_DESCRIPTION))
            
            val id = cursor.getLong(cursor.getColumnIndex(DownloadManager.COLUMN_ID))
            
            val date = Date(cursor.getLong(cursor.getColumnIndex(DownloadManager.COLUMN_LAST_MODIFIED_TIMESTAMP)))
            
            val mediaProviderUri:String? = cursor.getString(cursor.getColumnIndex(DownloadManager.COLUMN_MEDIAPROVIDER_URI))
            
            val mediaType = cursor.getString(cursor.getColumnIndex(DownloadManager.COLUMN_MEDIA_TYPE))
            
            val reason = cursor.getString(cursor.getColumnIndex(DownloadManager.COLUMN_REASON))
            
            val status = cursor.getInt(cursor.getColumnIndex(DownloadManager.COLUMN_STATUS))
            
            val title = cursor.getString(cursor.getColumnIndex(DownloadManager.COLUMN_TITLE))
            
            val bytesTotal = cursor.getLong(cursor.getColumnIndex(DownloadManager.COLUMN_TOTAL_SIZE_BYTES))

            return DownloadObject(
                uri,
                localUri,
                bytesDownloaded,
                bytesTotal,
                id,
                title,
                description,
                date,
                mediaProviderUri,
                mediaType,
                reason,
                status
            )

        }
    }

    override fun toString(): String {
        return "DownloadObject(\nuri='$uri'\nlocalUri='$localUri'\nbytesDownloaded=$bytesDownloaded\nbytesTotal=$bytesTotal\nid=$id\ntitle='$title'\ndescription='$description'\ndate=$date\nmediaProviderUri=$mediaProviderUri\nmediaType='$mediaType'\nreason='$reason'\nstatus=$status\n)"
    }


}

Questo è un oggetto di utility creato da me con l’obiettivo di racchiudere tutte le informazioni che DownloadManager possiede per un determinato download, con relativo metodo di wrapping dal Cursor.

Guida DownloadManager: il repository Git e l’applicazione di esempio!

Vi consiglio caldamente di consultare il codice del repository Github o scaricare l’applicazione esempio direttamente dal PlayStore (lasciatemi qualche stella se vi è stata almeno un poco utile e lasciate un commento con il vostro parere, mi piacerebbe sentire la vostra opinione)

• 

• 

Anche oggi è tutto, fatemi sapere se questa guida del componente Android DownloadManager vi è stata utile!

Buon codice a tutti voi!