Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update javadoc for BlockedNumberContract.

Browse Source 
BUG: 26232372
Change-Id: I57330782fa439bed52c595986916eb24bfbceab0
This commit is contained in:
Abhijith Shastry
2016-02-04 16:33:32 -08:00
parent f9ef97936c
commit dc4535ebda
1 changed files with 105 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

119
core/java/android/provider/BlockedNumberContract.java
View File

@@ -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.
* <p>
* The contract between the blockednumber provider and applications. Contains definitions for
* the supported URIs and columns.
* </p>
*
* TODO javadoc
* - Proper javadoc tagging.
* - Code sample?
* - Describe who can access it.
* <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>
*
* <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.
* </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). The provider enforces uniqueness constraint on this column.
* 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>
* </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>
* To check if a particular number is blocked, use the method
* {@link #isBlocked(Context, String)}.
* </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 an
* {@link UnsupportedOperationException}. 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 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);
}