query-blocked-numbers.md

Query blocked numbers

This library provides the BlockedNumbersQuery API that allows you to get blocked numbers.

An instance of the BlockedNumbersQuery API is obtained by,

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

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

A basic query

To get all of the blocked numbers,

val blockedNumbers = Contacts(context)
    .blockedNumbers()
    .query()
    .find()

Ordering

To order resulting BlockedNumbers using one or more fields,

.orderBy(fieldOrder)

For example, to order blocked numbers by number,

.orderBy(BlockedNumbersFields.Number.asc())

String comparisons ignores case by default. Each orderBys provides ignoreCase as an optional parameter.

Use BlockedNumbersFields to construct the orderBys.

Limiting and offsetting

To limit the amount of blocked numbers returned and/or offset (skip) a specified number of blocked numbers, use the limit and offset functions;

.limit(limit)
.offset(offset)

For more info, read Using limit and offset in queries.

Executing the query

To execute the query,

.find()

Cancelling the query

To cancel a query amid execution,

.find { returnTrueIfQueryShouldBeCancelled() }

The find function optionally takes in a function that, if it returns true, will cancel query processing as soon as possible. The function is called numerous times during query processing to check if processing should stop or continue. This gives you the option to cancel the query.

This is useful when used in multi-threaded environments. One scenario where this would be frequently used is when performing queries as the user types a search text. You are able to cancel the current query when the user enters new text.

For example, to automatically cancel the query inside a Kotlin coroutine when the coroutine is cancelled,

launch {
    withContext(coroutineContext) {
        val blockedNumbers = query.find { !isActive }
    }
}

Performing the query asynchronously

Queries are executed when the find 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 query 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.

Using the where function to specify matching criteria

Use the contacts.core.BlockedNumbersFields combined with the extensions from contacts.core.Where to form WHERE clauses.

ℹ️ This docs page will not provide a tutorial on database where clauses. It assumes that you know the basics. If you don't know the basics, then search for sqlite where clause.

For example, to find blocked numbers that contains "555",

.where { Number contains "555" }

To get a list of blocked numbers by IDs,

.where { Id `in` blockedNumberIds }