Accesso a file specifici dell'app

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

• Directory della memoria 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 le sedi ideali per archiviare dati sensibili a cui solo la tua app può accedere.

• Directory di archiviazione esterna:queste directory includono sia una posizione dedicata per l'archiviazione dei file permanenti sia un'altra posizione per l'archiviazione dei dati della cache. Sebbene sia possibile che un'altra app acceda a queste directory se dispone delle autorizzazioni appropriate, i file archiviati in queste directory sono destinati all'uso esclusivo della tua app. Se intendi creare file a cui altre app devono poter accedere, la tua app deve archiviarli nella sezione Archiviazione condivisa dello spazio di archiviazione esterno.

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

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

Accedere 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 della tua app e un'altra contiene i file memorizzati nella cache della tua app. L'app non richiede autorizzazioni di sistema per leggere e scrivere nei file in queste directory.

Le altre app non possono accedere ai file archiviati nella memoria interna. Per questo motivo, lo spazio di archiviazione interno è un buon posto per i dati delle app a cui altre app non devono accedere.

Tieni presente, tuttavia, che queste directory tendono a essere di piccole dimensioni. 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 normali e permanenti della tua app si trovano in una directory a cui puoi accedere utilizzando la proprietà filesDir di un oggetto di contesto. Il framework offre diversi metodi per accedere ai file e archiviarli.

Accedere ai file e archiviarli

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

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

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

val file = File(context.filesDir, filename)

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 un FileOutputStream che scrive in un file all'interno della directory filesDir.

Il seguente snippet di codice mostra come scrivere del testo in un file:

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

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

Per consentire ad altre app di accedere ai file memorizzati in questa directory all'interno della 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 flusso, utilizza openFileInput():

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

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();
}

Visualizzare l'elenco dei file

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

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

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 principale e un nuovo nome di directory a un costruttore File nel codice basato su Java:

context.getDir(dirName, Context.MODE_PRIVATE)

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

Creare file della cache

Se devi archiviare dati sensibili solo temporaneamente, devi utilizzare la directory della cache designata dell'app all'interno della memoria interna per salvarli. Come accade 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.

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

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

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

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

val cacheFile = File(context.cacheDir, filename)

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

Rimuovere i file della cache

Anche se a volte Android elimina i file della cache autonomamente, non devi fare affidamento sul sistema per pulire questi file al posto tuo. Devi sempre mantenere i file della cache della tua app nella 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, passando il nome del file:

  Kotlin

  context.deleteFile(cacheFileName)

  Java

  context.deleteFile(cacheFileName);

Accesso da un'unità di archiviazione esterna

Se lo spazio di archiviazione interno non è sufficiente per archiviare i file specifici dell'app, valuta la possibilità di utilizzare lo spazio di archiviazione esterno. Il sistema fornisce directory all'interno dello spazio di archiviazione esterno in cui un'app può organizzare i file che offrono valore all'utente solo all'interno dell'app. Una directory è progettata per i file permanenti dell'app e 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.

Sui dispositivi con Android 9 (livello API 28) o versioni precedenti, la tua app può accedere ai file specifici dell'app appartenenti ad altre app, a condizione che disponga delle autorizzazioni di archiviazione appropriate. Per offrire agli utenti un maggiore controllo sui propri file e limitare il disordine, alle app destinate ad Android 10 (livello API 29) e versioni successive viene concesso per impostazione predefinita l'accesso con ambito allo spazio di archiviazione esterno, o archiviazione con ambito. Quando lo spazio di archiviazione con ambito è abilitato, le app non possono accedere alle directory specifiche dell'app che appartengono ad altre app.

Verificare che lo spazio di archiviazione sia disponibile

Poiché lo spazio di archiviazione esterno 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 nello spazio di archiviazione esterno.

Puoi eseguire query sullo stato del volume chiamando Environment.getExternalStorageState(). Se lo stato restituito è MEDIA_MOUNTED, puoi leggere e scrivere file specifici delle app all'interno della memoria 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:

// 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)
}

// 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 memoria esterna rimovibile, utilizza il seguente comando per abilitare un volume virtuale per testare la logica di disponibilità dello spazio di archiviazione esterno:

adb shell sm set-virtual-disk true

Seleziona una posizione di archiviazione fisica

A volte, un dispositivo che alloca una partizione della memoria interna come archiviazione esterna fornisce anche uno slot per schede SD. Ciò significa che il dispositivo ha più volumi fisici che potrebbero contenere spazio di archiviazione esterno, quindi devi selezionare quello da utilizzare per lo spazio di archiviazione specifico dell'app.

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

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

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

Accedere ai file permanenti

Per accedere ai file specifici dell'app dallo spazio di archiviazione esterno, chiama getExternalFilesDir().

Per contribuire a mantenere il rendimento della tua app, non aprire e chiudere lo stesso file più volte.

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

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

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

Creare file della cache

Per aggiungere un file specifico dell'app alla cache all'interno della memoria esterna, consulta externalCacheDir:

val externalCacheFile = File(context.externalCacheDir, filename)

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

Rimuovi file della cache

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

externalCacheFile.delete()

externalCacheFile.delete();

Contenuti multimediali

Se la tua app funziona con file multimediali che offrono valore all'utente solo all'interno della tua app, è meglio archiviarli in directory specifiche dell'app all'interno dello spazio di archiviazione esterno, come dimostrato nel seguente snippet di codice:

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
}

@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 dalle costanti dell'API come DIRECTORY_PICTURES. Questi nomi di directory assicurano che i file vengano trattati correttamente dal sistema. Se nessuno dei nomi predefiniti delle sottodirectory è adatto ai tuoi file, puoi invece passare null a getExternalFilesDir(). Viene restituita la directory principale specifica dell'app all'interno dello spazio di archiviazione esterno.

Esegui query sullo spazio libero

Molti utenti non hanno molto spazio di archiviazione disponibile sui loro dispositivi, quindi la tua app deve consumare spazio in modo ponderato.

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

Se c'è spazio sufficiente per salvare i dati dell'app, chiama il numero allocateBytes(). In caso contrario, l'app può richiedere all'utente di rimuovere alcuni file dal dispositivo o di 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:

// 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
    }
}

// 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);
}

Creare un'attività di gestione dello spazio di archiviazione

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

Chiedere all'utente di rimuovere alcuni file del dispositivo

Per richiedere all'utente di scegliere i file da rimuovere 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. A questo scopo, richiama un intent che includa l'azione di intent ACTION_CLEAR_APP_CACHE.

Risorse aggiuntive

Per ulteriori informazioni su come salvare i file nella memoria del dispositivo, consulta le seguenti risorse.

Video

• Preparazione allo spazio di archiviazione limitato (Android Dev Summit '19)