Accesso a file specifici dell'app

In molti casi, l'app crea file a cui altre app non devono o non devono accedere. Il sistema fornisce le seguenti posizioni per l'archiviazione di questi file specifici per l'app:

• Directory di archiviazione interna: queste directory includono una posizione dedicata per l'archiviazione di file permanenti e un'altra posizione per l'archiviazione dei dati della cache. Il sistema impedisce ad altre app di accedere a queste posizioni e su Android 10 (livello API 29) e versioni successive, queste posizioni sono criptate. Queste caratteristiche rendono queste sedi un luogo ideale per archiviare dati sensibili a cui può accedere solo la tua app.

• Directory di archiviazione esterna:queste directory includono una posizione dedicata per l'archiviazione di file permanenti e un'altra posizione per l'archiviazione dei dati della cache. Anche se è possibile che un'altra app abbia accesso a queste directory se l'app dispone delle autorizzazioni appropriate, i file archiviati in queste directory sono pensati per essere utilizzati esclusivamente dalla tua app. Se intendi creare specificamente file a cui altre app dovrebbero poter accedere, la tua app deve archiviare questi file nell'spazio di archiviazione condiviso della memoria esterna.

Quando l'utente disinstalla l'app, i file salvati nello spazio di archiviazione specifico dell'app vengono rimossi. Per questo motivo, non devi utilizzare questo spazio di archiviazione per salvare tutto ciò che l'utente si aspetta di conservare indipendentemente dalla tua app. Ad esempio, se la tua app consente agli utenti di acquisire foto, l'utente si aspetta di poter accedere a queste foto anche dopo la disinstallazione dell'app. Dovresti utilizzare lo spazio di archiviazione condiviso per salvare questi tipi di file nella raccolta multimediale appropriata.

Le seguenti sezioni descrivono come archiviare e accedere ai file all'interno di directory specifiche dell'app.

Accesso dalla memoria interna

Per ogni app, il sistema fornisce directory all'interno della memoria interna in cui un'app può organizzare i propri file. Una directory è progettata per i file permanenti dell'app, mentre un'altra contiene i file dell'app memorizzati nella cache. L'app non richiede alcuna autorizzazione di sistema per leggere e scrivere sui file in queste directory.

Altre app non possono accedere ai file memorizzati nella memoria interna. Ciò rende l'archiviazione interna una buona posizione per i dati delle app a cui altre app non dovrebbero accedere.

Tuttavia, tieni presente che queste directory tendono a essere ridotte. Prima di scrivere file specifici dell'app nella memoria interna, l'app deve eseguire una query sullo spazio libero sul dispositivo.

Accedere ai file permanenti

I file permanenti e ordinari della tua app risiedono in una directory a cui puoi accedere utilizzando la proprietà filesDir di un oggetto di contesto. Il framework offre vari metodi per accedere ai file in questa directory e archiviarli.

Accedere ai file e archiviarli

Puoi utilizzare l'API File per accedere ai file e archiviarli.

Per mantenere le prestazioni dell'app, non aprire e chiudere lo stesso file più volte.

Il seguente snippet di codice mostra come utilizzare l'API File:

Kotlin

val file = File(context.filesDir, filename)

Java

File file = new File(context.getFilesDir(), filename);

Archiviare un file utilizzando uno stream

In alternativa all'utilizzo dell'API File, puoi chiamare openFileOutput() per ottenere una FileOutputStream che scriva in un file all'interno della directory filesDir.

Lo snippet di codice riportato di seguito mostra come scrivere testo in un file:

Kotlin

val filename = "myfile"
val fileContents = "Hello world!"
context.openFileOutput(filename, Context.MODE_PRIVATE).use {
        it.write(fileContents.toByteArray())
}

Java

String filename = "myfile";
String fileContents = "Hello world!";
try (FileOutputStream fos = context.openFileOutput(filename, Context.MODE_PRIVATE)) {
    fos.write(fileContents.toByteArray());
}

Attenzione: sui dispositivi con Android 7.0 (livello API 24) o versioni successive, a meno che non passi la modalità file Context.MODE_PRIVATE in openFileOutput(), si verifica una segnalazione di SecurityException.

Per consentire ad altre app di accedere ai file memorizzati in questa directory nella memoria interna, utilizza un FileProvider con l'attributo FLAG_GRANT_READ_URI_PERMISSION.

Accedere a un file utilizzando uno stream

Per leggere un file come stream, utilizza openFileInput():

Kotlin

context.openFileInput(filename).bufferedReader().useLines { lines ->
    lines.fold("") { some, text ->
        "$some\n$text"
    }
}

Java

FileInputStream fis = context.openFileInput(filename);
InputStreamReader inputStreamReader =
        new InputStreamReader(fis, StandardCharsets.UTF_8);
StringBuilder stringBuilder = new StringBuilder();
try (BufferedReader reader = new BufferedReader(inputStreamReader)) {
    String line = reader.readLine();
    while (line != null) {
        stringBuilder.append(line).append('\n');
        line = reader.readLine();
    }
} catch (IOException e) {
    // Error occurred when opening raw file for reading.
} finally {
    String contents = stringBuilder.toString();
}

Nota: se devi accedere a un file come stream al momento dell'installazione, salva il file nella directory /res/raw del progetto. Puoi aprire questi file con openRawResource(), trasmettendo il nome file preceduto dal prefisso R.raw come ID risorsa. Questo metodo restituisce un elemento InputStream che puoi utilizzare per leggere il file. Non puoi scrivere nel file originale.

Visualizza l'elenco dei file

Puoi ottenere un array contenente i nomi di tutti i file all'interno della directory filesDir chiamando fileList(), come mostrato nel seguente snippet di codice:

Kotlin

var files: Array<String> = context.fileList()

Java

Array<String> files = context.fileList();

Crea directory nidificate

Puoi anche creare directory nidificate o aprire una directory interna chiamando getDir() nel codice basato su Kotlin o passando la directory root e un nuovo nome di directory a un costruttore File in codice basato su Java:

Kotlin

context.getDir(dirName, Context.MODE_PRIVATE)

Java

File directory = context.getFilesDir();
File file = new File(directory, filename);

Nota: filesDir è sempre una directory predecessore di questa nuova directory.

Creare file di cache

Se devi archiviare dati sensibili solo temporaneamente, devi utilizzare la directory della cache designata dell'app all'interno della memoria interna per salvare i dati. Come per tutto lo spazio di archiviazione specifico dell'app, i file archiviati in questa directory vengono rimossi quando l'utente disinstalla l'app, anche se i file in questa directory potrebbero essere rimossi prima.

Nota: questa directory della cache è progettata per archiviare una piccola quantità di dati sensibili della tua app. Per determinare la quantità di spazio attualmente disponibile nella cache per la tua app, chiama getCacheQuotaBytes().

Per creare un file memorizzato nella cache, chiama File.createTempFile():

Kotlin

File.createTempFile(filename, null, context.cacheDir)

Java

File.createTempFile(filename, null, context.getCacheDir());

L'app accede a un file in questa directory utilizzando la proprietà cacheDir di un oggetto di contesto e l'API File:

Kotlin

val cacheFile = File(context.cacheDir, filename)

Java

File cacheFile = new File(context.getCacheDir(), filename);

Attenzione: quando lo spazio nella memoria interna del dispositivo si esaurisce, Android potrebbe eliminare questi file della cache per recuperare spazio. Verifica quindi l'esistenza dei file della cache prima di leggerli.

Rimuovere i file della cache

Anche se a volte Android elimina i file della cache autonomamente, non è consigliabile fare affidamento sul sistema per ripulire questi file automaticamente. Devi sempre conservare i file della cache dell'app all'interno della memoria interna.

Per rimuovere un file dalla directory della cache all'interno della memoria interna, utilizza uno dei seguenti metodi:

• Il metodo delete() su un oggetto File che rappresenta il file:

  Kotlin

  cacheFile.delete()
  

  Java

  cacheFile.delete();
  

• Il metodo deleteFile() del contesto dell'app, che trasmette il nome del file:

  Kotlin

  context.deleteFile(cacheFileName)
  

  Java

  context.deleteFile(cacheFileName);
  

Accedi da unità di archiviazione esterna

Se la memoria interna non offre spazio sufficiente per archiviare file specifici dell'app, valuta la possibilità di utilizzare un'unità di archiviazione esterna. All'interno di una memoria esterna, il sistema fornisce directory in cui un'app può organizzare file che offrono valore all'utente solo all'interno dell'app. Una directory è progettata per i file permanenti dell'app, mentre un'altra contiene i file memorizzati nella cache dell'app.

Su Android 4.4 (livello API 19) o versioni successive, la tua app non deve richiedere autorizzazioni relative allo spazio di archiviazione per accedere a directory specifiche dell'app all'interno dello spazio di archiviazione esterno. I file archiviati in queste directory vengono rimossi quando l'app viene disinstallata.

Attenzione: non è garantito che i file in queste directory siano accessibili, ad esempio quando una scheda SD rimovibile viene estratta dal dispositivo. Se la funzionalità dell'app dipende da questi file, devi archiviare i file all'interno dell'archivio interno.

Sui dispositivi con Android 9 (livello API 28) o versioni precedenti, l'app può accedere ai file specifici dell'app che appartengono ad altre app, purché tu disponga delle autorizzazioni di archiviazione appropriate. Per offrire agli utenti un maggiore controllo sui file e limitarne il disordine, per impostazione predefinita le app destinate ad Android 10 (livello API 29) e versioni successive hanno accesso limitato all'archiviazione esterna, o archiviazione con ambito. Quando l'archiviazione con ambito è abilitata, le app non possono accedere alle directory specifiche delle app che appartengono ad altre app.

Verificare che lo spazio di archiviazione sia disponibile

Poiché l'unità di archiviazione esterna si trova su un volume fisico che l'utente potrebbe essere in grado di rimuovere, verifica che il volume sia accessibile prima di provare a leggere o scrivere dati specifici dell'app nella memoria esterna.

Puoi eseguire query sullo stato del volume chiamando Environment.getExternalStorageState(). Se lo stato restituito è MEDIA_MOUNTED, puoi leggere e scrivere file specifici dell'app all'interno dell'unità di archiviazione esterna. Se è MEDIA_MOUNTED_READ_ONLY, puoi solo leggere questi file.

Ad esempio, i seguenti metodi sono utili per determinare la disponibilità dello spazio di archiviazione:

Kotlin

// Checks if a volume containing external storage is available
// for read and write.
fun isExternalStorageWritable(): Boolean {
    return Environment.getExternalStorageState() == Environment.MEDIA_MOUNTED
}

// Checks if a volume containing external storage is available to at least read.
fun isExternalStorageReadable(): Boolean {
     return Environment.getExternalStorageState() in
        setOf(Environment.MEDIA_MOUNTED, Environment.MEDIA_MOUNTED_READ_ONLY)
}

Java

// Checks if a volume containing external storage is available
// for read and write.
private boolean isExternalStorageWritable() {
    return Environment.getExternalStorageState().equals(Environment.MEDIA_MOUNTED);
}

// Checks if a volume containing external storage is available to at least read.
private boolean isExternalStorageReadable() {
     return Environment.getExternalStorageState().equals(Environment.MEDIA_MOUNTED) ||
            Environment.getExternalStorageState().equals(Environment.MEDIA_MOUNTED_READ_ONLY);
}

Sui dispositivi senza unità di archiviazione esterna rimovibile, utilizza il comando seguente per abilitare un volume virtuale al fine di testare la logica di disponibilità dell'unità di archiviazione esterna:

adb shell sm set-virtual-disk true

Seleziona una posizione di archiviazione fisica

A volte, un dispositivo che alloca una partizione della sua memoria interna come unità di archiviazione esterna fornisce anche uno slot per schede SD. Ciò significa che il dispositivo ha più volumi fisici che potrebbero contenere unità di archiviazione esterna, quindi devi selezionare quale utilizzare per l'archiviazione specifica per l'app.

Per accedere alle diverse sedi, chiama il numero ContextCompat.getExternalFilesDirs(). Come mostrato nello snippet di codice, il primo elemento dell'array restituito è considerato il volume di archiviazione esterna principale. Usa questo volume a meno che non sia al massimo o non disponibile.

Kotlin

val externalStorageVolumes: Array<out File> =
        ContextCompat.getExternalFilesDirs(applicationContext, null)
val primaryExternalStorage = externalStorageVolumes[0]

Java

File[] externalStorageVolumes =
        ContextCompat.getExternalFilesDirs(getApplicationContext(), null);
File primaryExternalStorage = externalStorageVolumes[0];

Nota: se la tua app viene utilizzata su un dispositivo con Android 4.3 (livello API 18) o versioni precedenti, l'array contiene un solo elemento, che rappresenta il volume di archiviazione esterna principale.

Accedere ai file permanenti

Per accedere a file specifici dell'app dalla memoria esterna, chiama getExternalFilesDir().

Per mantenere le prestazioni dell'app, non aprire e chiudere lo stesso file più volte.

Il seguente snippet di codice mostra come chiamare getExternalFilesDir():

Kotlin

val appSpecificExternalDir = File(context.getExternalFilesDir(null), filename)

Java

File appSpecificExternalDir = new File(context.getExternalFilesDir(null), filename);

Nota: su Android 11 (livello API 30) e versioni successive, le app non possono creare una propria directory specifica dell'app nella memoria esterna.

Creare file di cache

Per aggiungere un file specifico dell'app alla cache all'interno dell'unità di archiviazione esterna, consulta externalCacheDir:

Kotlin

val externalCacheFile = File(context.externalCacheDir, filename)

Java

File externalCacheFile = new File(context.getExternalCacheDir(), filename);

Rimuovere i file della cache

Per rimuovere un file dalla directory della cache esterna, utilizza il metodo delete() su un oggetto File che rappresenta il file:

Kotlin

externalCacheFile.delete()

Java

externalCacheFile.delete();

Contenuti multimediali

Se la tua app funziona con file multimediali che offrono valore all'utente solo al suo interno, ti consigliamo di memorizzarli in directory specifiche dell'app all'interno di uno spazio di archiviazione esterno, come mostrato nel seguente snippet di codice:

Kotlin

fun getAppSpecificAlbumStorageDir(context: Context, albumName: String): File? {
    // Get the pictures directory that's inside the app-specific directory on
    // external storage.
    val file = File(context.getExternalFilesDir(
            Environment.DIRECTORY_PICTURES), albumName)
    if (!file?.mkdirs()) {
        Log.e(LOG_TAG, "Directory not created")
    }
    return file
}

Java

@Nullable
File getAppSpecificAlbumStorageDir(Context context, String albumName) {
    // Get the pictures directory that's inside the app-specific directory on
    // external storage.
    File file = new File(context.getExternalFilesDir(
            Environment.DIRECTORY_PICTURES), albumName);
    if (file == null || !file.mkdirs()) {
        Log.e(LOG_TAG, "Directory not created");
    }
    return file;
}

È importante utilizzare i nomi di directory forniti da costanti API come DIRECTORY_PICTURES. Questi nomi di directory assicurano che i file vengano trattati correttamente dal sistema. Se nessuno dei nomi di sottodirectory predefiniti corrisponde ai tuoi file, puoi trasferire null in getExternalFilesDir(). Questa operazione restituisce la directory principale dell'app principale all'interno dell'unità di archiviazione esterna.

Esegui query su spazio libero

Molti utenti non hanno molto spazio di archiviazione disponibile sui loro dispositivi, pertanto l'app dovrebbe occupare spazio in modo ponderato.

Se sai in anticipo quanti dati stai archiviando, puoi scoprire quanto spazio il dispositivo può fornire alla tua app chiamando il numero getAllocatableBytes(). Il valore restituito di getAllocatableBytes() potrebbe essere superiore alla quantità attuale di spazio libero sul dispositivo. Questo perché il sistema ha identificato dei file che può rimuovere dalle directory della cache di altre app.

Se c'è abbastanza spazio per salvare i dati della tua app, chiama il numero allocateBytes(). In caso contrario, l'app può richiedere all'utente di rimuovere alcuni file dal dispositivo o rimuovere tutti i file della cache dal dispositivo.

Il seguente snippet di codice mostra un esempio di come la tua app può eseguire query sullo spazio libero sul dispositivo:

Kotlin

// App needs 10 MB within internal storage.
const val NUM_BYTES_NEEDED_FOR_MY_APP = 1024 * 1024 * 10L;

val storageManager = applicationContext.getSystemService<StorageManager>()!!
val appSpecificInternalDirUuid: UUID = storageManager.getUuidForPath(filesDir)
val availableBytes: Long =
        storageManager.getAllocatableBytes(appSpecificInternalDirUuid)
if (availableBytes >= NUM_BYTES_NEEDED_FOR_MY_APP) {
    storageManager.allocateBytes(
        appSpecificInternalDirUuid, NUM_BYTES_NEEDED_FOR_MY_APP)
} else {
    val storageIntent = Intent().apply {
        // To request that the user remove all app cache files instead, set
        // "action" to ACTION_CLEAR_APP_CACHE.
        action = ACTION_MANAGE_STORAGE
    }
}

Java

// App needs 10 MB within internal storage.
private static final long NUM_BYTES_NEEDED_FOR_MY_APP = 1024 * 1024 * 10L;

StorageManager storageManager =
        getApplicationContext().getSystemService(StorageManager.class);
UUID appSpecificInternalDirUuid = storageManager.getUuidForPath(getFilesDir());
long availableBytes =
        storageManager.getAllocatableBytes(appSpecificInternalDirUuid);
if (availableBytes >= NUM_BYTES_NEEDED_FOR_MY_APP) {
    storageManager.allocateBytes(
            appSpecificInternalDirUuid, NUM_BYTES_NEEDED_FOR_MY_APP);
} else {
    // To request that the user remove all app cache files instead, set
    // "action" to ACTION_CLEAR_APP_CACHE.
    Intent storageIntent = new Intent();
    storageIntent.setAction(ACTION_MANAGE_STORAGE);
}

Nota: non è necessario verificare la quantità di spazio disponibile prima di salvare il file. Puoi provare a scrivere subito il file e individuare un IOException se si verifica. Potrebbe essere necessario eseguire questa operazione se non sai esattamente di quanto spazio ti serve. Ad esempio, se cambia la codifica del file prima di salvarlo convertendo un'immagine PNG in JPEG, non conosci in anticipo le dimensioni del file.

Creare un'attività di gestione dello spazio di archiviazione

La tua app può dichiarare e creare un'attività personalizzata che, all'avvio, consente all'utente di gestire i dati che l'app ha archiviato sul suo dispositivo. Dichiari questa attività "Gestisci spazio" personalizzata utilizzando l'attributo android:manageSpaceActivity nel file manifest. Le app di gestione file possono attivare questa attività anche se l'app non esporta l'attività, ovvero quando l'attività imposta android:exported su false.

Chiedi all'utente di rimuovere alcuni file del dispositivo

Per richiedere all'utente di scegliere i file da rimuovere presenti sul dispositivo, richiama un intent che include l'azione ACTION_MANAGE_STORAGE. Questo intent mostra una richiesta all'utente. Se vuoi, questo prompt può mostrare la quantità di spazio libero disponibile sul dispositivo. Per mostrare queste informazioni facili da usare, utilizza il risultato del seguente calcolo:

StorageStatsManager.getFreeBytes() / StorageStatsManager.getTotalBytes()

Chiedi all'utente di rimuovere tutti i file della cache

In alternativa, puoi richiedere all'utente di cancellare i file della cache da tutte le app sul dispositivo. Per farlo, richiama un intent che include l'azione dell'intent ACTION_CLEAR_APP_CACHE.

Attenzione: l'azione intent ACTION_CLEAR_APP_CACHE può influire notevolmente sulla durata della batteria del dispositivo e potrebbe rimuovere un numero elevato di file.

Risorse aggiuntive

Per ulteriori informazioni sul salvataggio di file nello spazio di archiviazione del dispositivo, consulta le risorse seguenti.

Video

• Preparazione per l'archiviazione mirata (Android Dev Summit '19)