BlockedNumberContract
open class BlockedNumberContract
kotlin.Any | |
↳ | android.provider.BlockedNumberContract |
The contract between the blockednumber provider and applications. Contains definitions for the supported URIs and columns.
Overview
The content provider exposes a table containing blocked numbers. The columns and URIs for accessing this table are defined by the BlockedNumbers
class. Messages, and calls from blocked numbers are discarded by the platform. Notifications upon provider changes can be received using a android.database.ContentObserver
.
The platform will not block messages, and calls from emergency numbers as defined by android.telephony.PhoneNumberUtils#isEmergencyNumber(String)
. If the user contacts emergency services, number blocking is disabled by the platform for a duration defined by android.telephony.CarrierConfigManager#KEY_DURATION_BLOCKING_DISABLED_AFTER_EMERGENCY_INT
.
Permissions
Only the system, the default SMS application, and the default phone app (See android.telecom.TelecomManager#getDefaultDialerPackage()
), and carrier apps (See android.service.carrier.CarrierService
) can read, and write to the blockednumber provider. However, canCurrentUserBlockNumbers(android.content.Context)
can be accessed by any application.
Data
Other than regular phone numbers, the blocked number provider can also store addresses (such as email) from which a user can receive messages, and calls. The blocked numbers are stored in the BlockedNumbers#COLUMN_ORIGINAL_NUMBER
column. A normalized version of phone numbers (if normalization is possible) is stored in BlockedNumbers#COLUMN_E164_NUMBER
column. The platform blocks calls, and messages from an address if it is present in in the BlockedNumbers#COLUMN_ORIGINAL_NUMBER
column or if the E164 version of the address matches the BlockedNumbers#COLUMN_E164_NUMBER
column.
Operations
- Insert
-
BlockedNumbers#COLUMN_ORIGINAL_NUMBER
is a required column that needs to be populated. Apps can optionally provide theBlockedNumbers#COLUMN_E164_NUMBER
which is the phone number's E164 representation. The provider automatically populates this column if the app does not provide it. Note that this column is not populated if normalization fails or if the address is not a phone number (eg: email).Attempting to insert an existing blocked number (same
BlockedNumbers#COLUMN_ORIGINAL_NUMBER
column) will result in replacing the existing blocked number.Examples:
ContentValues values = new ContentValues(); values.put(BlockedNumbers.COLUMN_ORIGINAL_NUMBER, "1234567890"); Uri uri = getContentResolver().insert(BlockedNumbers.CONTENT_URI, values);
ContentValues values = new ContentValues(); values.put(BlockedNumbers.COLUMN_ORIGINAL_NUMBER, "1234567890"); values.put(BlockedNumbers.COLUMN_E164_NUMBER, "+11234567890"); Uri uri = getContentResolver().insert(BlockedNumbers.CONTENT_URI, values);
ContentValues values = new ContentValues(); values.put(BlockedNumbers.COLUMN_ORIGINAL_NUMBER, "12345@abdcde.com"); Uri uri = getContentResolver().insert(BlockedNumbers.CONTENT_URI, values);
- Update
-
Updates are not supported. Use Delete, and Insert instead.
- Delete
-
Deletions can be performed as follows:
To check if a particular number is blocked, use the methodContentValues values = new ContentValues(); values.put(BlockedNumbers.COLUMN_ORIGINAL_NUMBER, "1234567890"); Uri uri = getContentResolver().insert(BlockedNumbers.CONTENT_URI, values); getContentResolver().delete(uri, null, null);
isBlocked(android.content.Context,java.lang.String)
. - Query
-
All blocked numbers can be enumerated as follows:
Cursor c = getContentResolver().query(BlockedNumbers.CONTENT_URI, new String[]{BlockedNumbers.COLUMN_ID, BlockedNumbers.COLUMN_ORIGINAL_NUMBER, BlockedNumbers.COLUMN_E164_NUMBER}, null, null, null);
- Unblock
-
Use the method
unblock(android.content.Context,java.lang.String)
to unblock numbers.
Multi-user
Apps must use the method canCurrentUserBlockNumbers(android.content.Context)
before performing any operation on the blocked number provider. If canCurrentUserBlockNumbers(android.content.Context)
returns false
, all operations on the provider will fail with a SecurityException
. The platform will block calls, and messages from numbers in the provider independent of the current user.
Summary
Nested classes | |
---|---|
open |
Constants to interact with the blocked numbers list. |
Constants | |
---|---|
static String |
The authority for the blocked number provider |
Public methods | |
---|---|
open static Boolean |
canCurrentUserBlockNumbers(context: Context!) Checks if blocking numbers is supported for the current user. |
open static Boolean |
Returns whether a given number is in the blocked list. |
open static Int |
Unblocks the |
Properties | |
---|---|
static Uri! |
A content:// style uri to the authority for the blocked number provider |
Constants
AUTHORITY
static val AUTHORITY: String
The authority for the blocked number provider
Value: "com.android.blockednumber"
Public methods
canCurrentUserBlockNumbers
open static fun canCurrentUserBlockNumbers(context: Context!): Boolean
Checks if blocking numbers is supported for the current user.
Typically, blocking numbers is only supported for one user at a time.
Return | |
---|---|
Boolean |
true if the current user can block numbers. |
isBlocked
open static fun isBlocked(
context: Context!,
phoneNumber: String!
): Boolean
Returns whether a given number is in the blocked list.
This matches the phoneNumber
against the BlockedNumbers#COLUMN_ORIGINAL_NUMBER
column, and the E164 representation of the phoneNumber
with the BlockedNumbers#COLUMN_E164_NUMBER
column.
Note that if the canCurrentUserBlockNumbers
is false
for the user context context
, this method will throw a SecurityException
.
This method may take several seconds to complete, so it should only be called from a worker thread.
Return | |
---|---|
Boolean |
true if the phoneNumber is blocked. |
unblock
open static fun unblock(
context: Context!,
phoneNumber: String!
): Int
Unblocks the phoneNumber
if it is blocked.
This deletes all rows where the phoneNumber
matches the BlockedNumbers#COLUMN_ORIGINAL_NUMBER
column or the E164 representation of the phoneNumber
matches the BlockedNumbers#COLUMN_E164_NUMBER
column.
To delete rows based on exact match with specific columns such as BlockedNumbers#COLUMN_ID
use android.content.ContentProvider#delete(Uri, String, String[])
with BlockedNumbers#CONTENT_URI
URI.
Note that if the canCurrentUserBlockNumbers
is false
for the user context context
, this method will throw a SecurityException
.
This method may take several seconds to complete, so it should only be called from a worker thread.
Return | |
---|---|
Int |
the number of rows deleted in the blocked number provider as a result of unblock. |
Properties
AUTHORITY_URI
static val AUTHORITY_URI: Uri!
A content:// style uri to the authority for the blocked number provider