Storage Access Framework: qué es, cómo funciona y acceso a archivos en Android

¿Qué es Storage Access Framework?

Storage Access Framework es una parte del SDK de Android que proporciona una interfaz unificada para seleccionar y crear documentos a través de un diálogo del sistema. SAF abstrae la ubicación física de los archivos: la aplicación no sabe de dónde se lee el archivo — disco local, Google Drive o Dropbox.

La arquitectura de SAF incluye tres componentes: la aplicación cliente que inicia la solicitud, el selector del sistema — un diálogo estándar de selección de archivos, y el DocumentProvider — un proveedor de contenido que implementa el acceso a archivos de un almacenamiento específico. El usuario ve una interfaz unificada independientemente de la fuente de datos.

SAF está disponible desde Android 4.4 (API 19). Inicialmente, el framework solo admitía documentos, pero en Android 5.0 se añadió soporte para directorios mediante ACTION_OPEN_DOCUMENT_TREE. Desde Android 10, SAF se convirtió en la forma recomendada de acceder a cualquier archivo fuera del almacenamiento específico de la aplicación.

Cómo funciona SAF: selector del sistema y URI

SAF lanza un diálogo de selección de archivos del sistema mediante un Intent con la acción ACTION_OPEN_DOCUMENT. El usuario ve una lista de fuentes disponibles: almacenamiento interno, Google Drive, Dropbox y otros proveedores registrados. Después de seleccionar un archivo, el sistema devuelve un content URI con permisos de acceso temporales.

El content URI tiene el formato content://com.android.externalstorage.documents/document/primary/Download/file.pdf. A diferencia de un URI file://, el content URI no revela la ruta real del archivo y funciona a través de DocumentProvider. La aplicación lee el archivo mediante ContentResolver.openInputStream con el URI obtenido.

El selector del sistema admite automáticamente búsqueda, ordenación y filtrado de archivos por tipos MIME. El desarrollador especifica los tipos necesarios mediante Intent.putExtra(Intent.EXTRA_MIME_TYPES, arrayOf("application/pdf", "image/*")), y el selector muestra solo los archivos relevantes.

Ciclo de vida del acceso URI

Por defecto, el URI es válido hasta que se reinicia la aplicación o se reinicia el dispositivo. Para acceso a largo plazo, la aplicación solicita takePersistableUriPermission — esto permite leer el archivo en ejecuciones posteriores sin tener que volver a seleccionarlo mediante el diálogo.

ACTION_OPEN_DOCUMENT y ACTION_CREATE_DOCUMENT

SAF proporciona tres acciones principales para trabajar con archivos: abrir, crear y seleccionar árbol de carpetas. ACTION_OPEN_DOCUMENT abre el selector del sistema para elegir un archivo existente. ACTION_CREATE_DOCUMENT crea un archivo nuevo — el usuario ingresa un nombre en el diálogo y la aplicación recibe un URI para escritura.

ACTION_OPEN_DOCUMENT_TREE permite seleccionar un directorio completo y obtener acceso a todos los archivos dentro de él. Esto se usa en administradores de archivos, aplicaciones de respaldo y sincronización. La aplicación recibe un URI de directorio y puede enumerar recursivamente el contenido mediante DocumentFile.

Para cada acción, los tipos MIME se especifican mediante EXTRA_MIME_TYPES. Se pueden especificar varios tipos: "application/pdf", "image/*", "text/plain". Si no se especifican tipos, el selector muestra todos los archivos.

Persistent URI permissions

Persistent URI permissions es un mecanismo de SAF que permite conservar el acceso a un archivo después de que finalice la sesión actual. Sin este flag, el URI solo es válido hasta que se reinicia la aplicación. La aplicación solicita el flag FLAG_GRANT_PERSISTABLE_URI_PERMISSION junto con los flags READ y WRITE.

Para guardar los permisos se utiliza el método ContentResolver.takePersistableUriPermission. El sistema guarda el URI en un registro especial y restaura el acceso en el siguiente inicio de la aplicación. Para comprobar si la aplicación tiene acceso persistente a un URI, se utiliza ContentResolver.persistedUriPermissions.

El usuario puede revocar los permisos guardados mediante Configuración → Aplicaciones → Permisos. La aplicación debe manejar el escenario en el que el acceso a un archivo se pierde inesperadamente. Se recomienda verificar el acceso mediante ContentResolver.openInputStream antes de comenzar a trabajar y manejar correctamente SecurityException.

Ejemplos de código: selección de archivo mediante SAF

SAF se lanza a través de un Intent estándar. El código es mínimo: crear un Intent con ACTION_OPEN_DOCUMENT, especificar los tipos MIME y lanzarlo mediante ActivityResultContracts.StartActivityForResult. Después de seleccionar un archivo, el callback recibe el URI en data.data, que luego se utiliza para la lectura.

val pickFile = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { result ->
    result.data?.data?.let { uri ->
        val inputStream = contentResolver?.openInputStream(uri)
        // read from inputStream
    }
}

val intent = Intent(Intent.ACTION_OPEN_DOCUMENT).apply {
    addCategory(Intent.CATEGORY_OPENABLE)
    setType("application/pdf")
    putExtra(Intent.EXTRA_ALLOW_MULTIPLE, true)
}
pickFile.launch(intent)

Creación de archivo mediante ACTION_CREATE_DOCUMENT

Para escribir un archivo nuevo, use ACTION_CREATE_DOCUMENT. El Intent acepta el tipo MIME y el nombre del archivo mediante EXTRA_TITLE. Después de seleccionar una carpeta y confirmar, el usuario devuelve un URI en el que la aplicación escribe datos mediante ContentResolver.openOutputStream. El sistema crea automáticamente el archivo en la ubicación elegida.

SAF vs READ_EXTERNAL_STORAGE

SAF se diferencia del tradicional READ_EXTERNAL_STORAGE en un enfoque fundamentalmente diferente hacia la seguridad. En lugar de solicitar acceso a todo el almacenamiento de una vez, SAF solicita acceso solo a un archivo específico. Esto minimiza la superficie de ataque y aumenta la confianza del usuario.

READ_EXTERNAL_STORAGE otorga acceso a todos los archivos del dispositivo, incluyendo fotos y documentos de otras aplicaciones. En Android 10+, este enfoque está restringido. SAF, por el contrario, proporciona acceso solo al archivo seleccionado por el usuario y requiere confirmación explícita para cada archivo. Para operaciones por lotes con medios, use MediaStore; para documentos individuales, use SAF.

La principal desventaja de SAF es la necesidad de seleccionar cada archivo individualmente. Para operaciones masivas (copia de seguridad, sincronización de carpetas), se utiliza ACTION_OPEN_DOCUMENT_TREE, que otorga acceso a todos los archivos del directorio seleccionado. La solución depende del escenario: SAF es óptimo para selección del usuario, MediaStore para acceso programático a medios.