Pro Android with Kotlin

76
CHAPTER 6: Content Providers
Dispatching URIs Inside the Provider Code
To simplify dispatching incoming URIs, the class android.content.UriMatcher comes in 
handy. If you have query-related URIs like, for example, this:
people #list all people from a directory
people/37 #inquire a person with ID 37
people/37/phone #get phone info of person with ID 37
and want to use an easy switch statement, you can write the following inside your class or 
object:
val PEOPLE_DIR_AUTHORITY = "directory"
val PEOPLE = 1
val PEOPLE_ID = 2
val PEOPLE_PHONES = 3
val uriMatcher = UriMatcher(UriMatcher.NO_MATCH)
init {
uriMatcher.addURI(PEOPLE_DIR_AUTHORITY,
"people", PEOPLE)
uriMatcher.addURI(PEOPLE_DIR_AUTHORITY,
"people/#", PEOPLE_ID)
uriMatcher.addURI(PEOPLE_DIR_AUTHORITY,
"people/#/phone", PEOPLE_PHONES)
}
Here, # stands for any number, and * matches any string.
In your ContentProvider implementation, you can then use the following construct to 
dispatch incoming string URLs:
when(uriMatcher.match(url)) {
PEOPLE ->
// incoming path = people, do s.th. with that...
PEOPLE_ID ->
// incoming path = people/#, do s.th. with that...
PEOPLE_PHONES ->
// incoming path = people/#/phone, ...
else ->
// do something else
}
Providing Content Files
Content providers not only can give access to database-like content, they may also expose 
methods for retrieving file-like data, such as image or sound files. For this aim, the following 
methods are provided:

---

77
CHAPTER 6: Content Providers

override fun getStreamTypes(uri:Uri, mimeTypeFilter:String) : 
Array
If your content provider offers files, overwrite this method to allow clients 
to determine supported MIME types given a URI. The mimeTypeFilter 
should not be null, and you can use it to filter the output. It supports 
wildcards, so if a client wants to retrieve all values, it will write */* 
here, and your provider code needs to correctly handle this. The output 
must also contain all those types that may be the result of suitable type 
conversions performed by the provider. This may return null to indicate 
an empty result set. Examples are image/png or audio/mpeg.

override fun openFile(uri:Uri, mode:String): ParcelFileDescriptor
Override this to handle requests to open a file blob. The parameter mode 
must be one of the following (there is no default):

r for read-only access

w for write-only access (first erasing if data is already present)

wa, which is like w but possibly appends data

rw for reading and appending writing

rwt, which is like rw but truncates existing data
To learn what to do with the returned ParcelFileDescriptor, see the
text after the list.

override fun openFile(uri:Uri, mode:String, 
signal:CancellationSignal): ParcelFileDescriptor
This is the same as openFile(Uri, String), but additionally the client 
may signal a cancellation while reading the file is in progress. The 
provider can save the signal object and catch the client’s cancellation 
request by periodically calling throwIfCancelled() on the signal object.

override fun openAssetFile(uri:Uri, mode:String): 
AssetFileDescriptor
This is like openFile(Uri, String), but it can be implemented by 
providers that need to be able to return subsections of files, often assets 
inside of their APK. For implementing this, you probably want to use the 
android.content.res.AssetManager class. You have it in the asset field 
of a context, so for example in an activity you can directly use asset to 
address the AssetManager.

override fun openAssetFile(uri:Uri, mode:String, 
signal:CancellationSignal): AssetFileDescriptor
This is the same as openAssetFile(Uri, String) but allows for cancellation 
from the client side. The provider can save the signal object and catch the 
client’s cancellation request by periodically calling throwIfCancelled() on 
the signal object.

---