Scoped Storage Stories: The Undocumented Documents

Android 10 is greatly restricting access to external storage via filesystem APIs. Instead, we need to use other APIs to work with content. This is the 12th post in a seemingly never-ending series, where we will explore how to work with those alternatives.


One apparent gap in the MediaStore options is the Documents/ directory. We have obvious support for the media directories and Downloads/, but everything else had to be handled via the Storage Access Framework. This includes Documents/, which, like Downloads/, seems like it would be a general-purpose location.

As it turns out, there is support for Documents/. It’s just not documented.

This comes to us courtesy of Stack Overflow user blackapps, and this answer.

To work with downloads, as we saw previously, we can use MediaStore.Downloads as the basis. However, using MediaStore.Files, we can work with Downlodads/ and Documents/, plus custom subdirectories under those.

Specifically, MediaStore.Files.getContentUri("external") gets us a Uri that we can use akin to MediaStore.Downloads.EXTERNAL_CONTENT_URI for inserting new content and querying for our own content, though as before we cannot access other apps’ content this way. If we use RELATIVE_PATH and specify Documents, our content will go into the Documents/ directory:

val values = ContentValues().apply {
  put(MediaStore.Files.FileColumns.DISPLAY_NAME, filename)
  put(MediaStore.Files.FileColumns.MIME_TYPE, mimeType)
  put(MediaStore.Files.FileColumns.RELATIVE_PATH, "Documents")
  put(MediaStore.Files.FileColumns.IS_PENDING, 1)
}

val resolver = context.contentResolver
val uri =
  resolver.insert(MediaStore.Files.getContentUri("external"), values)

uri?.let {
  resolver.openOutputStream(uri)?.use { outputStream ->
    val sink = outputStream.sink().buffer()

    response.body?.source()?.let { sink.writeAll(it) }
    sink.close()
  }

  values.clear()
  values.put(MediaStore.Downloads.IS_PENDING, 0)
  resolver.update(uri, values, null, null)
} ?: throw RuntimeException("MediaStore failed for some reason")

We can also use subdirectories under Documents/, such as Documents/AwesomeStuff. And, we can use Downloads/ as the base. Attempts to write to other root directories than Documents/ and Downloads/ will fail with an error.

You can even use this for removable volumes. blackapps’ answer shows a hard-coded storage volume ID, though presumably using StorageManager and methods like getStorageVolumes() will be more flexible.

The fact that this does not appear to be documented means that it is possible that this will not be supported in future versions of Android. So, use this approach with caution. But, if Documents/ is a must-have location, and you really want to avoid the Storage Access Framework, MediaStore.Files may be something to consider.


The entire series of “Scoped Storage Stories” posts includes posts on:


Stuck on an Android problem? Subscribers have access to live office hours chats with Mark Murphy, to help you work through your challenges!