How do I use the permissions module to simplify permission handling using coroutines?

Android Contacts API Library written in Kotlin with Java interoperability. No more ContentProviders and cursors. Say goodbye to ContactsContract. Build your own contacts app!

How do I use the permissions module to simplify permission handling using coroutines?

This library provides extensions in the permissions module that allow you to prompt users for required permissions before executing a core API function. These extensions use Kotlin Coroutines.

For all core API functions that requires certain permissions to be granted (e.g. query, insert, update, and deletes), there is a corresponding xxxWithPermission extension function.

Using withPermission extensions

To perform an query, insert, update, and delete with permission,

launch {
    val contactsApi = Contacts(context)
    val query = contactsApi.queryWithPermission()
    val insert = contactsApi.insertWithPermission()
    val update = contactsApi.updateWithPermission()
    val delete = contactsApi.deleteWithPermission()
}

For each invocation of xxxWithPermission, if the required permission(s) are not yet granted, the current coroutine is suspended, user is prompted to grant permissions, and then an operation instance is returned (which may then be executed to get a result).

If permission(s) are already granted, then an operation instance is returned immediately without suspending the coroutine and prompting the user for permission.

If permission(s) are not granted, then the operation will immediately fail and the result you get is incorrect (usually null or empty when it should not be).

Prior to Android 6.0 Marshmallow (API level 23), users are NOT prompted for permission at runtime because users must already grant all permissions prior to app install.

Not compatible with Java

Unlike the core module, the permissions module is not compatible with Java because it requires Kotlin Coroutines.

These extensions are optional

You are free to use the core APIs however you want with whatever libraries or frameworks you want that works with Java or use your own DIY solution.