delete-blocked-numbers.md

Delete blocked numbers

This library provides the BlockedNumbersDelete API that allows you to delete existing BlockedNumbers.

An instance of the BlockedNumbersDelete API is obtained by,

val delete = Contacts(context).blockedNumbers().delete()

Note that blocked number deletions will only work for privileged apps. For more info, read about Blocked numbers.

A basic delete

To delete a set of existing blocked numbers,

val deleteResult = delete
    .blockedNumbers()
    .delete()
    .blockedNumbers(existingBlockedNumbers)
    .commit()

To delete a set of existing blocked numbers using IDs,

val deleteResult = delete
    .blockedNumbers()
    .delete()
    .blockedNumbersWithId(1, 2, 3)
    .commit()

An advanced delete

You may specify a matching criteria, like in queries, that will delete all matching blocked numbers,

val deleteResult = delete
    .dataWhere { Number contains "555" }
    .commit()

Executing the delete

To execute the delete,

.commit()

If you want to delete all given blockedNumbers in a single atomic transaction,

.commitInOneTransaction()

The call to commitInOneTransaction will only succeed if ALL given blocked numbers are successfully deleted. If one delete fails, the entire operation will fail and everything will be reverted prior to the delete operation. In contrast, commit allows for some deletes to succeed and some to fail.

Handling the delete result

The commit and commitInOneTransaction functions returns a Result,

To check if all deletes succeeded,

val allDeletesSuccessful = deleteResult.isSuccessful

To check if a particular delete succeeded,

val deleteSuccessful = deleteResult.isSuccessful(blockedNumber)
val deleteSuccessful = deleteResult.isSuccessful(blockedNumber.id)

To check if a particular advanced delete managed to delete at least one matching blocked number,

val where = BlockedNumbersFields.Number contains "555"
val deleteResult = delete.groupsWhere(where).commit()
val advancedDeleteSuccessful = deleteResult.isSuccessful(where)

Performing the delete and result processing asynchronously

Deletes are executed when the commit or commitInOneTransaction function is invoked. The work is done in the same thread as the call-site. This may result in a choppy UI.

To perform the work in a different thread, use the Kotlin coroutine extensions provided in the async module. For more info, read Execute work outside of the UI thread using coroutines.

You may, of course, use other multi-threading libraries or just do it yourself =)

ℹ️ Extensions for Kotlin Flow and RxJava are also in the project roadmap.

Performing the delete with permission

There are no permissions required for blocked numbers. However, there are privileges that must be acquired. For more info, read about Blocked numbers.