Pro Android with Kotlin

96
CHAPTER 6: Content Providers
The main idea of a documents provider is that your app provides access to documents, 
wherever the corresponding data are stored, and otherwise doesn’t care about how the 
documents and the documents structure get presented to the user or other apps. The 
documents provider data model consists of one to many trees starting at root nodes, 
with subnodes being either documents or directories spanning subtrees, again with other 
directories and documents. It thus resembles the structure of data in a file system.
To start with a documents provider, you create a class implementing android.provider.
DocumentsProvider, which itself is a specialized subclass of android.content.
ContentProvider. At a bare minimum, you have to implement these methods:

override fun onCreate(): Boolean:
Use this to initialize the documents provider. Since this runs on the app’s main thread, you 
must not perform lengthy operations here. But you can prepare the data access to the 
provider. This returns true if the provider was successfully loaded and false otherwise.

override fun queryRoots(projection: Array?): Cursor:
This is supposed to query the roots of the provider’s data structure. In 
many cases, the data will fit into one tree, and you thus need to provide 
just one root, but you can have as many roots as makes sense for your 
requirements. The projection argument may present a list of columns 
to be included in the result set. The names are the same as the COLUMN_* 
constants inside DocumentsContract.Root. It may be null, which means 
return all columns. The method must return cursors with at a maximum the 
following fields (shown are the constant names from DocumentsContract.
Root):

COLUMN_AVAILABLE_BYTES (long): Available bytes under the root. Optional, and 
may be null to indicate unknown.

COLUMN_CAPACITY_BYTES (long): The capacity of the tree at that root, in bytes. 
Think of a file system capacity. Optional, and may be null to indicate unknown.

COLUMN_DOCUMENT_ID: The ID (string) of the directory corresponding to that 
root. Required.

COLUMN_FLAGS: Flags that apply to a root (int). A combination of (constants in 
DocumentsContract.Root):

FLAG_LOCAL_ONLY (local to the device, no network access),

FLAG_SUPPORTS_CREATE (at least one document under the root supports 
creating content)
Note The SAF was included in API level 19. As of February 2018, this is the version used for more 
than 90 percent of active Android devices. You cannot use SAF for devices prior to that, but if you 
really need to cover the remaining 10 percent, you still can provide documents as normal content 
mediated by content providers and factor out code that can be used by both the SAF and the legacy 
provider.

---