| /* |
| * Copyright (C) 2016 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License |
| */ |
| package android.provider; |
| |
| import android.annotation.WorkerThread; |
| import android.content.Context; |
| import android.net.Uri; |
| import android.os.Bundle; |
| |
| /** |
| * <p> |
| * The contract between the blockednumber provider and applications. Contains definitions for |
| * the supported URIs and columns. |
| * </p> |
| * |
| * <h3> Overview </h3> |
| * <p> |
| * The content provider exposes a table containing blocked numbers. The columns and URIs for |
| * accessing this table are defined by the {@link BlockedNumbers} class. Messages, and calls from |
| * blocked numbers are discarded by the platform. Notifications upon provider changes can be |
| * received using a {@link android.database.ContentObserver}. |
| * </p> |
| * <p> |
| * The platform will not block messages, and calls from emergency numbers as defined by |
| * {@link android.telephony.PhoneNumberUtils#isEmergencyNumber(String)}. If the user contacts |
| * emergency services, number blocking is disabled by the platform for a duration defined by |
| * {@link android.telephony.CarrierConfigManager#KEY_DURATION_BLOCKING_DISABLED_AFTER_EMERGENCY_INT}. |
| * </p> |
| * |
| * <h3> Permissions </h3> |
| * <p> |
| * Only the system, the default SMS application, and the default phone app |
| * (See {@link android.telecom.TelecomManager#getDefaultDialerPackage()}), and carrier apps |
| * (See {@link android.service.carrier.CarrierService}) can read, and write to the blockednumber |
| * provider. However, {@link #canCurrentUserBlockNumbers(Context)} can be accessed by any |
| * application. |
| * </p> |
| * |
| * <h3> Data </h3> |
| * <p> |
| * 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 {@link BlockedNumbers#COLUMN_ORIGINAL_NUMBER} column. A normalized version of phone |
| * numbers (if normalization is possible) is stored in {@link BlockedNumbers#COLUMN_E164_NUMBER} |
| * column. The platform blocks calls, and messages from an address if it is present in in the |
| * {@link BlockedNumbers#COLUMN_ORIGINAL_NUMBER} column or if the E164 version of the address |
| * matches the {@link BlockedNumbers#COLUMN_E164_NUMBER} column. |
| * </p> |
| * |
| * <h3> Operations </h3> |
| * <dl> |
| * <dt><b>Insert</b></dt> |
| * <dd> |
| * <p> |
| * {@link BlockedNumbers#COLUMN_ORIGINAL_NUMBER} is a required column that needs to be populated. |
| * Apps can optionally provide the {@link BlockedNumbers#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). |
| * <p> |
| * Attempting to insert an existing blocked number (same |
| * {@link BlockedNumbers#COLUMN_ORIGINAL_NUMBER} column) will result in replacing the existing |
| * blocked number. |
| * <p> |
| * Examples: |
| * <pre> |
| * ContentValues values = new ContentValues(); |
| * values.put(BlockedNumbers.COLUMN_ORIGINAL_NUMBER, "1234567890"); |
| * Uri uri = getContentResolver().insert(BlockedNumbers.CONTENT_URI, values); |
| * </pre> |
| * <pre> |
| * 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); |
| * </pre> |
| * <pre> |
| * ContentValues values = new ContentValues(); |
| * values.put(BlockedNumbers.COLUMN_ORIGINAL_NUMBER, "12345@abdcde.com"); |
| * Uri uri = getContentResolver().insert(BlockedNumbers.CONTENT_URI, values); |
| * </pre> |
| * </p> |
| * </dd> |
| * <dt><b>Update</b></dt> |
| * <dd> |
| * <p> |
| * Updates are not supported. Use Delete, and Insert instead. |
| * </p> |
| * </dd> |
| * <dt><b>Delete</b></dt> |
| * <dd> |
| * <p> |
| * Deletions can be performed as follows: |
| * <pre> |
| * ContentValues values = new ContentValues(); |
| * values.put(BlockedNumbers.COLUMN_ORIGINAL_NUMBER, "1234567890"); |
| * Uri uri = getContentResolver().insert(BlockedNumbers.CONTENT_URI, values); |
| * getContentResolver().delete(uri, null, null); |
| * </pre> |
| * To check if a particular number is blocked, use the method |
| * {@link #isBlocked(Context, String)}. |
| * </p> |
| * </dd> |
| * <dt><b>Query</b></dt> |
| * <dd> |
| * <p> |
| * All blocked numbers can be enumerated as follows: |
| * <pre> |
| * Cursor c = getContentResolver().query(BlockedNumbers.CONTENT_URI, |
| * new String[]{BlockedNumbers.COLUMN_ID, BlockedNumbers.COLUMN_ORIGINAL_NUMBER, |
| * BlockedNumbers.COLUMN_E164_NUMBER}, null, null, null); |
| * </pre> |
| * </p> |
| * </dd> |
| * <dt><b>Unblock</b></dt> |
| * <dd> |
| * <p> |
| * Use the method {@link #unblock(Context, String)} to unblock numbers. |
| * </p> |
| * </dd> |
| * |
| * <h3> Multi-user </h3> |
| * <p> |
| * Apps must use the method {@link #canCurrentUserBlockNumbers(Context)} before performing any |
| * operation on the blocked number provider. If {@link #canCurrentUserBlockNumbers(Context)} returns |
| * {@code false}, all operations on the provider will fail with a {@link SecurityException}. The |
| * platform will block calls, and messages from numbers in the provider independent of the current |
| * user. |
| * </p> |
| */ |
| public class BlockedNumberContract { |
| private BlockedNumberContract() { |
| } |
| |
| /** The authority for the blocked number provider */ |
| public static final String AUTHORITY = "com.android.blockednumber"; |
| |
| /** A content:// style uri to the authority for the blocked number provider */ |
| public static final Uri AUTHORITY_URI = Uri.parse("content://" + AUTHORITY); |
| |
| /** |
| * Constants to interact with the blocked numbers list. |
| */ |
| public static class BlockedNumbers { |
| private BlockedNumbers() { |
| } |
| |
| /** |
| * Content URI for the blocked numbers. |
| * <h3> Supported operations </h3> |
| * <p> blocked |
| * <ul> |
| * <li> query |
| * <li> delete |
| * <li> insert |
| * </ul> |
| * <p> blocked/ID |
| * <ul> |
| * <li> query (selection is not supported) |
| * <li> delete (selection is not supported) |
| * </ul> |
| */ |
| public static final Uri CONTENT_URI = Uri.withAppendedPath(AUTHORITY_URI, "blocked"); |
| |
| /** |
| * The MIME type of {@link #CONTENT_URI} itself providing a directory of blocked phone |
| * numbers. |
| */ |
| public static final String CONTENT_TYPE = "vnd.android.cursor.dir/blocked_number"; |
| |
| /** |
| * The MIME type of a blocked phone number under {@link #CONTENT_URI}. |
| */ |
| public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/blocked_number"; |
| |
| /** |
| * Auto-generated ID field which monotonically increases. |
| * <p>TYPE: long</p> |
| */ |
| public static final String COLUMN_ID = "_id"; |
| |
| /** |
| * Phone number to block. |
| * <p>Must be specified in {@code insert}. |
| * <p>TYPE: String</p> |
| */ |
| public static final String COLUMN_ORIGINAL_NUMBER = "original_number"; |
| |
| /** |
| * Phone number to block. The system generates it from {@link #COLUMN_ORIGINAL_NUMBER} |
| * by removing all formatting characters. |
| * <p>Optional in {@code insert}. When not specified, the system tries to generate it |
| * assuming the current country. (Which will still be null if the number is not valid.) |
| * <p>TYPE: String</p> |
| */ |
| public static final String COLUMN_E164_NUMBER = "e164_number"; |
| } |
| |
| /** @hide */ |
| public static final String METHOD_IS_BLOCKED = "is_blocked"; |
| |
| /** @hide */ |
| public static final String METHOD_UNBLOCK= "unblock"; |
| |
| /** @hide */ |
| public static final String RES_NUMBER_IS_BLOCKED = "blocked"; |
| |
| /** @hide */ |
| public static final String RES_NUM_ROWS_DELETED = "num_deleted"; |
| |
| /** @hide */ |
| public static final String METHOD_CAN_CURRENT_USER_BLOCK_NUMBERS = |
| "can_current_user_block_numbers"; |
| |
| /** @hide */ |
| public static final String RES_CAN_BLOCK_NUMBERS = "can_block"; |
| |
| /** |
| * Returns whether a given number is in the blocked list. |
| * |
| * <p> This matches the {@code phoneNumber} against the |
| * {@link BlockedNumbers#COLUMN_ORIGINAL_NUMBER} column, and the E164 representation of the |
| * {@code phoneNumber} with the {@link BlockedNumbers#COLUMN_E164_NUMBER} column. |
| * |
| * <p> Note that if the {@link #canCurrentUserBlockNumbers} is {@code false} for the user |
| * context {@code context}, this method will throw a {@link SecurityException}. |
| * |
| * @return {@code true} if the {@code phoneNumber} is blocked. |
| */ |
| @WorkerThread |
| public static boolean isBlocked(Context context, String phoneNumber) { |
| final Bundle res = context.getContentResolver().call( |
| AUTHORITY_URI, METHOD_IS_BLOCKED, phoneNumber, null); |
| return res != null && res.getBoolean(RES_NUMBER_IS_BLOCKED, false); |
| } |
| |
| /** |
| * Unblocks the {@code phoneNumber} if it is blocked. |
| * |
| * <p> This deletes all rows where the {@code phoneNumber} matches the |
| * {@link BlockedNumbers#COLUMN_ORIGINAL_NUMBER} column or the E164 representation of the |
| * {@code phoneNumber} matches the {@link BlockedNumbers#COLUMN_E164_NUMBER} column. |
| * |
| * <p>To delete rows based on exact match with specific columns such as |
| * {@link BlockedNumbers#COLUMN_ID} use |
| * {@link android.content.ContentProvider#delete(Uri, String, String[])} with |
| * {@link BlockedNumbers#CONTENT_URI} URI. |
| * |
| * <p> Note that if the {@link #canCurrentUserBlockNumbers} is {@code false} for the user |
| * context {@code context}, this method will throw a {@link SecurityException}. |
| * |
| * @return the number of rows deleted in the blocked number provider as a result of unblock. |
| */ |
| @WorkerThread |
| public static int unblock(Context context, String phoneNumber) { |
| final Bundle res = context.getContentResolver().call( |
| AUTHORITY_URI, METHOD_UNBLOCK, phoneNumber, null); |
| return res.getInt(RES_NUM_ROWS_DELETED, 0); |
| } |
| |
| /** |
| * Checks if blocking numbers is supported for the current user. |
| * <p> Typically, blocking numbers is only supported for one user at a time. |
| * |
| * @return {@code true} if the current user can block numbers. |
| */ |
| public static boolean canCurrentUserBlockNumbers(Context context) { |
| final Bundle res = context.getContentResolver().call( |
| AUTHORITY_URI, METHOD_CAN_CURRENT_USER_BLOCK_NUMBERS, null, null); |
| return res != null && res.getBoolean(RES_CAN_BLOCK_NUMBERS, false); |
| } |
| |
| /** |
| * <p> |
| * The contract between the blockednumber provider and the system. |
| * </p> |
| * <p>This is a wrapper over {@link BlockedNumberContract} that also manages the blocking |
| * behavior when the user contacts emergency services. See |
| * {@link #notifyEmergencyContact(Context)} for details. All methods are protected by |
| * {@link android.Manifest.permission#READ_BLOCKED_NUMBERS} and |
| * {@link android.Manifest.permission#WRITE_BLOCKED_NUMBERS} appropriately which ensure that |
| * only system can access the methods defined here. |
| * </p> |
| * @hide |
| */ |
| public static class SystemContract { |
| /** |
| * A protected broadcast intent action for letting components with |
| * {@link android.Manifest.permission#READ_BLOCKED_NUMBERS} know that the block suppression |
| * status as returned by {@link #getBlockSuppressionStatus(Context)} has been updated. |
| */ |
| public static final String ACTION_BLOCK_SUPPRESSION_STATE_CHANGED = |
| "android.provider.action.BLOCK_SUPPRESSION_STATE_CHANGED"; |
| |
| public static final String METHOD_NOTIFY_EMERGENCY_CONTACT = "notify_emergency_contact"; |
| |
| public static final String METHOD_END_BLOCK_SUPPRESSION = "end_block_suppression"; |
| |
| public static final String METHOD_SHOULD_SYSTEM_BLOCK_NUMBER = "should_system_block_number"; |
| |
| public static final String METHOD_GET_BLOCK_SUPPRESSION_STATUS = |
| "get_block_suppression_status"; |
| |
| public static final String RES_IS_BLOCKING_SUPPRESSED = "blocking_suppressed"; |
| |
| public static final String RES_BLOCKING_SUPPRESSED_UNTIL_TIMESTAMP = |
| "blocking_suppressed_until_timestamp"; |
| |
| /** |
| * Notifies the provider that emergency services were contacted by the user. |
| * <p> This results in {@link #shouldSystemBlockNumber} returning {@code false} independent |
| * of the contents of the provider for a duration defined by |
| * {@link android.telephony.CarrierConfigManager#KEY_DURATION_BLOCKING_DISABLED_AFTER_EMERGENCY_INT} |
| * the provider unless {@link #endBlockSuppression(Context)} is called. |
| */ |
| public static void notifyEmergencyContact(Context context) { |
| context.getContentResolver().call( |
| AUTHORITY_URI, METHOD_NOTIFY_EMERGENCY_CONTACT, null, null); |
| } |
| |
| /** |
| * Notifies the provider to disable suppressing blocking. If emergency services were not |
| * contacted recently at all, calling this method is a no-op. |
| */ |
| public static void endBlockSuppression(Context context) { |
| context.getContentResolver().call( |
| AUTHORITY_URI, METHOD_END_BLOCK_SUPPRESSION, null, null); |
| } |
| |
| /** |
| * Returns {@code true} if {@code phoneNumber} is blocked taking |
| * {@link #notifyEmergencyContact(Context)} into consideration. If emergency services have |
| * not been contacted recently, this method is equivalent to |
| * {@link #isBlocked(Context, String)}. |
| */ |
| public static boolean shouldSystemBlockNumber(Context context, String phoneNumber) { |
| final Bundle res = context.getContentResolver().call( |
| AUTHORITY_URI, METHOD_SHOULD_SYSTEM_BLOCK_NUMBER, phoneNumber, null); |
| return res != null && res.getBoolean(RES_NUMBER_IS_BLOCKED, false); |
| } |
| |
| /** |
| * Returns the current status of block suppression. |
| */ |
| public static BlockSuppressionStatus getBlockSuppressionStatus(Context context) { |
| final Bundle res = context.getContentResolver().call( |
| AUTHORITY_URI, METHOD_GET_BLOCK_SUPPRESSION_STATUS, null, null); |
| return new BlockSuppressionStatus(res.getBoolean(RES_IS_BLOCKING_SUPPRESSED, false), |
| res.getLong(RES_BLOCKING_SUPPRESSED_UNTIL_TIMESTAMP, 0)); |
| } |
| |
| /** |
| * Represents the current status of {@link #shouldSystemBlockNumber(Context, String)}. If |
| * emergency services have been contacted recently, {@link #isSuppressed} is {@code true}, |
| * and blocking is disabled until the timestamp {@link #untilTimestampMillis}. |
| */ |
| public static class BlockSuppressionStatus { |
| public final boolean isSuppressed; |
| /** |
| * Timestamp in milliseconds from epoch. |
| */ |
| public final long untilTimestampMillis; |
| |
| public BlockSuppressionStatus(boolean isSuppressed, long untilTimestampMillis) { |
| this.isSuppressed = isSuppressed; |
| this.untilTimestampMillis = untilTimestampMillis; |
| } |
| } |
| } |
| } |
