MediaStore API: cos'è, funzionalità e lavoro con file multimediali condivisi

Cos'è MediaStore API?

MediaStore API è un content provider di sistema sulla piattaforma Android progettato per indicizzare, archiviare e fornire accesso ai file multimediali del dispositivo. L'API fa parte dell'Android SDK ed è disponibile dal API Level 1.

MediaStore opera attraverso un database multimediale unificato che scansiona automaticamente il dispositivo e raccoglie metadati di tutti i file multimediali. Il database viene aggiornato dal sistema quando i file vengono aggiunti, modificati o eliminati, quindi le applicazioni ricevono sempre informazioni aggiornate senza scansione manuale.

Le tabelle principali di MediaStore sono: Images (immagini), Video (video), Audio (audio) e Files (file generali). Ogni tabella contiene colonne con metadati: nome, data di creazione, dimensione, tipo MIME, coordinate GPS e altri attributi.

Evoluzione di MediaStore nelle versioni Android

Prima di Android 10, gli sviluppatori usavano READ_EXTERNAL_STORAGE per accedere a tutti i file del dispositivo. Android 10 (API 29) ha introdotto Scoped Storage: le applicazioni potevano accedere solo ai propri file e tramite MediaStore. Android 11 ha inasprito ulteriormente la politica, bloccando completamente il percorso diretto alle directory condivise.

A partire da Android 13 (API 33), Google ha sostituito READ_EXTERNAL_STORAGE con autorizzazioni granulari: READ_MEDIA_IMAGES, READ_MEDIA_VIDEO e READ_MEDIA_AUDIO. Ciò consente agli utenti di concedere l'accesso solo a tipi specifici di media senza esporre l'intero archivio.

Come funziona MediaStore: architettura e database multimediale

MediaStore è costruito su un'architettura di content provider: ogni applicazione vi accede tramite ContentResolver e Uri. Lo scanner multimediale di sistema — MediaScannerConnection — indicizza automaticamente tutti i file del dispositivo all'avvio, alla connessione USB o al riavvio.

Il database multimediale è memorizzato nel database di sistema e contiene record per ogni file multimediale. Le colonne differiscono per tipo: le immagini hanno ORIENTATION e DATE_TAKEN, i video hanno DURATION, i file audio hanno ARTIST e ALBUM. Gli sviluppatori possono eseguire query simili a SQL con query, projection e selection per filtrare.

val projection = arrayOf(
    MediaStore.Images.Media._ID,
    MediaStore.Images.Media.DISPLAY_NAME,
    MediaStore.Images.Media.DATE_ADDED
)

val cursor = contentResolver.query(
    MediaStore.Images.Media.EXTERNAL_CONTENT_URI,
    projection,
    null,
    null,
    MediaStore.Images.Media.DATE_ADDED + " DESC"
)

cursor?.use {
    while (moveToNext()) {
        val name = getString(getColumnIndexOrThrow(MediaStore.Images.Media.DISPLAY_NAME))
    }
}

Content URI e loro significato

Ogni file multimediale è identificato da un Content URI come content://media/external/images/media/1234. L'URI esterno punta all'archivio condiviso, mentre quello interno punta ai file multimediali di sistema. Usare URI invece di percorsi di file è un vantaggio chiave di MediaStore: l'applicazione non necessita di accesso al file system e funziona tramite un content provider sicuro.

Tipi di file multimediali in MediaStore

MediaStore supporta quattro tipi principali di media, ciascuno con la propria tabella e set di metadati. Gli sviluppatori selezionano la tabella appropriata in base al tipo di contenuto con cui lavora l'applicazione.

• MediaStore.Images — foto, screenshot e immagini. Colonne: BUCKET_DISPLAY_NAME, IS_PRIVATE, LATITUDE, LONGITUDE.
• MediaStore.Video — registrazioni video e film. Colonne: DURATION, RESOLUTION, IS_DRM.
• MediaStore.Audio — tracce musicali e file audio. Colonne: ARTIST, ALBUM, COMPOSER, TRACK.
• MediaStore.Files — documenti e altri file. Disponibile da Android 10 per l'accesso condiviso.

Oltre alle colonne standard, ogni tabella contiene campi di sistema: _ID, DATA (deprecato), SIZE, MIME_TYPE, DATE_ADDED, DATE_MODIFIED. Da Android 10, il campo DATA è deprecato e gli sviluppatori devono lavorare aprendo un InputStream tramite URI.

Autorizzazioni per lavorare con MediaStore

MediaStore richiede autorizzazioni esplicite, che differiscono in base alla versione di Android. Prima di Android 13, veniva utilizzata l'autorizzazione singola READ_EXTERNAL_STORAGE. A partire da Android 13 (API 33), Google ha introdotto autorizzazioni granulari per ogni tipo di media.

Scrivere in MediaStore richiede anche WRITE_EXTERNAL_STORAGE per Android 9 e versioni precedenti. A partire da Android 10, un'applicazione può scrivere i propri file in MediaStore senza autorizzazioni aggiuntive — il sistema concede automaticamente l'accesso quando si inserisce un record tramite ContentResolver.insert.

Richiedere autorizzazioni in fase di esecuzione

Le autorizzazioni di MediaStore vengono richieste tramite il meccanismo standard ActivityResultContracts.RequestMultiplePermissions. L'utente può rifiutare la richiesta e l'applicazione deve gestire correttamente questo scenario. Si raccomanda di verificare l'autorizzazione tramite ContextCompat.checkSelfPermission prima di ogni accesso a MediaStore.

Esempi di codice: lettura e scrittura tramite MediaStore

MediaStore consente non solo di leggere ma anche di scrivere file multimediali. Per scrivere un'immagine o un video, lo sviluppatore usa ContentResolver.insert e apre un OutputStream per l'URI restituito. Il sistema aggiunge automaticamente il file al database multimediale e lo indicizza.

val values = ContentValues().apply {
    put(MediaStore.Images.Media.DISPLAY_NAME, "photo_2025.jpg")
    put(MediaStore.Images.Media.MIME_TYPE, "image/jpeg")
    put(MediaStore.Images.Media.RELATIVE_PATH, "Pictures/MyApp")
}

val uri = contentResolver?.insert(
    MediaStore.Images.Media.EXTERNAL_CONTENT_URI, values
)

uri?.let {
    val outputStream = contentResolver?.openOutputStream(it)
    outputStream?.use { stream ->
        // scrivere byte nel flusso
    }
}

Eliminare file multimediali tramite MediaStore

L'eliminazione viene eseguita tramite ContentResolver.delete con l'URI del file. Il sistema verifica i diritti di accesso: se il file appartiene all'applicazione corrente, l'eliminazione avviene senza autorizzazioni aggiuntive. Per i file di altre applicazioni su Android 10+, è richiesta la conferma dell'utente tramite un dialogo di sistema.

MediaStore vs accesso diretto ai file

MediaStore API differisce fondamentalmente dall'accesso diretto ai file tramite File API. Invece di percorsi di file, vengono utilizzati Content URI, e invece di operazioni sui file, vengono utilizzati metodi ContentResolver. Ciò offre tre vantaggi principali: sicurezza, indicizzazione automatica e interfaccia unificata.

L'accesso diretto ai file è limitato su Android 10+ per le directory condivise. MediaStore rimane l'unico modo per leggere media da Pictures, DCIM, Movies, Music e Download. Per i file specifici dell'applicazione (app-specific storage), l'accesso diretto è preservato — si tratta delle cartelle in Android/data e Android/media.

La scelta tra MediaStore e accesso diretto dipende dal tipo di contenuto. MediaStore è obbligatorio per i file multimediali condivisi accessibili da altre applicazioni. La File API diretta è adatta per file interni dell'applicazione e cache. Storage Access Framework viene utilizzato per selezionare documenti arbitrari tramite il selettore di sistema.