From dc4535ebdae321ee64d4e6ff9933863d2609df7c Mon Sep 17 00:00:00 2001 From: Abhijith Shastry Date: Thu, 4 Feb 2016 16:33:32 -0800 Subject: [PATCH] Update javadoc for BlockedNumberContract. BUG: 26232372 Change-Id: I57330782fa439bed52c595986916eb24bfbceab0 --- .../provider/BlockedNumberContract.java | 119 +++++++++++++++--- 1 file changed, 105 insertions(+), 14 deletions(-) diff --git a/core/java/android/provider/BlockedNumberContract.java b/core/java/android/provider/BlockedNumberContract.java index 7a9d0625c199a..ea54f9203873c 100644 --- a/core/java/android/provider/BlockedNumberContract.java +++ b/core/java/android/provider/BlockedNumberContract.java @@ -20,35 +20,126 @@ import android.net.Uri; import android.os.Bundle; /** - * Constants and methods to access blocked phone numbers for incoming calls and texts. + *

+ * The contract between the blockednumber provider and applications. Contains definitions for + * the supported URIs and columns. + *

* - * TODO javadoc - * - Proper javadoc tagging. - * - Code sample? - * - Describe who can access it. + *

Overview

+ *

+ * 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}. + *

+ * + *

Permissions

+ *

+ * 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. + *

+ * + *

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 {@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. + *

+ * + *

Operations

+ *
+ *
Insert
+ *
+ *

+ * {@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). The provider enforces uniqueness constraint on this column. + * 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: + * 

+ * ContentValues values = new ContentValues();
+ * values.put(BlockedNumbers.COLUMN_ORIGINAL_NUMBER, "1234567890");
+ * Uri uri = getContentResolver().insert(BlockedNumbers.CONTENT_URI, values);
+ * getContentResolver().delete(uri, null, null);
+ *
+ *

+ *
+ *
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);
+ *
+ * To check if a particular number is blocked, use the method + * {@link #isBlocked(Context, String)}. + *

+ *
+ * + *

Multi-user

+ *

+ * 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 an + * {@link UnsupportedOperationException}. The platform will block calls, and messages from numbers + * in the provider independent of the current user. + *

*/ public class BlockedNumberContract { private BlockedNumberContract() { } - /** The authority for the contacts provider */ + /** The authority for the blocked number provider */ public static final String AUTHORITY = "com.android.blockednumber"; - /** A content:// style uri to the authority for the contacts provider */ + /** A content:// style uri to the authority for the blocked number provider */ public static final Uri AUTHORITY_URI = Uri.parse("content://" + AUTHORITY); /** - * TODO javadoc - * - * Constants to interact with the blocked phone number list. + * Constants to interact with the blocked numbers list. */ public static class BlockedNumbers { private BlockedNumbers() { } /** - * TODO javadoc - * * Content URI for the blocked numbers. * * Supported operations @@ -117,8 +208,8 @@ public class BlockedNumberContract { * context {@code context}, this method will throw an {@link UnsupportedOperationException}. */ public static boolean isBlocked(Context context, String phoneNumber) { - final Bundle res = context.getContentResolver().call(AUTHORITY_URI, - METHOD_IS_BLOCKED, phoneNumber, null); + final Bundle res = context.getContentResolver().call( + AUTHORITY_URI, METHOD_IS_BLOCKED, phoneNumber, null); return res != null && res.getBoolean(RES_NUMBER_IS_BLOCKED, false); }