| /* |
| * Copyright (C) 2020 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 static android.provider.SimPhonebookContract.ElementaryFiles.EF_ADN; |
| import static android.provider.SimPhonebookContract.ElementaryFiles.EF_FDN; |
| import static android.provider.SimPhonebookContract.ElementaryFiles.EF_SDN; |
| import static android.provider.SimPhonebookContract.ElementaryFiles.PATH_SEGMENT_EF_ADN; |
| import static android.provider.SimPhonebookContract.ElementaryFiles.PATH_SEGMENT_EF_FDN; |
| import static android.provider.SimPhonebookContract.ElementaryFiles.PATH_SEGMENT_EF_SDN; |
| |
| import android.annotation.IntDef; |
| import android.annotation.IntRange; |
| import android.annotation.NonNull; |
| import android.annotation.SystemApi; |
| import android.annotation.WorkerThread; |
| import android.content.ContentResolver; |
| import android.content.ContentValues; |
| import android.net.Uri; |
| import android.os.Bundle; |
| import android.telephony.SubscriptionInfo; |
| import android.telephony.TelephonyManager; |
| |
| import com.android.internal.util.Preconditions; |
| |
| import java.lang.annotation.Retention; |
| import java.lang.annotation.RetentionPolicy; |
| import java.util.Objects; |
| |
| /** |
| * The contract between the provider of contact records on the device's SIM cards and applications. |
| * Contains definitions of the supported URIs and columns. |
| * |
| * <h3>Permissions</h3> |
| * <p> |
| * Querying this provider requires {@link android.Manifest.permission#READ_CONTACTS} and writing |
| * to this provider requires {@link android.Manifest.permission#WRITE_CONTACTS} |
| * </p> |
| */ |
| public final class SimPhonebookContract { |
| |
| /** The authority for the SIM phonebook provider. */ |
| public static final String AUTHORITY = "com.android.simphonebook"; |
| /** The content:// style uri to the authority for the SIM phonebook provider. */ |
| @NonNull |
| public static final Uri AUTHORITY_URI = Uri.parse("content://com.android.simphonebook"); |
| /** |
| * The Uri path element used to indicate that the following path segment is a subscription ID |
| * for the SIM card that will be operated on. |
| * |
| * @hide |
| */ |
| public static final String SUBSCRIPTION_ID_PATH_SEGMENT = "subid"; |
| |
| private SimPhonebookContract() { |
| } |
| |
| /** |
| * Returns the Uri path segment used to reference the specified elementary file type for Uris |
| * returned by this API. |
| * |
| * @hide |
| */ |
| @NonNull |
| public static String getEfUriPath(@ElementaryFiles.EfType int efType) { |
| switch (efType) { |
| case EF_ADN: |
| return PATH_SEGMENT_EF_ADN; |
| case EF_FDN: |
| return PATH_SEGMENT_EF_FDN; |
| case EF_SDN: |
| return PATH_SEGMENT_EF_SDN; |
| default: |
| throw new IllegalArgumentException("Unsupported EfType " + efType); |
| } |
| } |
| |
| /** |
| * Constants for the contact records on a SIM card. |
| * |
| * <h3 id="simrecords-data">Data</h3> |
| * <p> |
| * Data is stored in a specific elementary file on a specific SIM card and these are isolated |
| * from each other. SIM cards are identified by their subscription ID. SIM cards may not support |
| * all or even any of the elementary file types. A SIM will have constraints on |
| * the values of the data that can be stored in each elementary file. The available SIMs, |
| * their supported elementary file types and the constraints on the data can be discovered by |
| * querying {@link ElementaryFiles#CONTENT_URI}. Each elementary file has a fixed capacity |
| * for the number of records that may be stored. This can be determined from the value |
| * of the {@link ElementaryFiles#MAX_RECORDS} column. |
| * </p> |
| * <p> |
| * The {@link SimRecords#PHONE_NUMBER} column can only contain dialable characters and this |
| * applies regardless of the SIM that is being used. See |
| * {@link android.telephony.PhoneNumberUtils#isDialable(char)} for more details. Additionally |
| * the phone number can contain at most {@link ElementaryFiles#PHONE_NUMBER_MAX_LENGTH} |
| * characters. The {@link SimRecords#NAME} column can contain at most |
| * {@link ElementaryFiles#NAME_MAX_LENGTH} bytes when it is encoded for storage on the SIM. |
| * Encoding is done internally and so the name should be provided to these provider APIs as a |
| * Java String but the number of bytes required to encode it for storage will vary depending on |
| * the characters it contains. This length can be determined by calling |
| * {@link SimRecords#getEncodedNameLength(ContentResolver, String)}. |
| * </p> |
| * <h3>Operations </h3> |
| * <dl> |
| * <dd><b>Insert</b></dd> |
| * <p> |
| * Only {@link ElementaryFiles#EF_ADN} supports inserts. {@link SimRecords#PHONE_NUMBER} |
| * is a required column. If the value provided for this column is missing, null, empty |
| * or violates the requirements discussed in the <a href="#simrecords-data">Data</a> |
| * section above an {@link IllegalArgumentException} will be thrown. The |
| * {@link SimRecords#NAME} column may be omitted but if provided and it violates any of |
| * the requirements discussed in the <a href="#simrecords-data">Data</a> section above |
| * an {@link IllegalArgumentException} will be thrown. |
| * </p> |
| * <p> |
| * If an insert is not possible because the elementary file is full then an |
| * {@link IllegalStateException} will be thrown. |
| * </p> |
| * <dd><b>Update</b></dd> |
| * <p> |
| * Updates can only be performed for individual records on {@link ElementaryFiles#EF_ADN}. |
| * A specific record is referenced via the Uri returned by |
| * {@link SimRecords#getItemUri(int, int, int)}. Updates have the same constraints and |
| * behavior for the {@link SimRecords#PHONE_NUMBER} and {@link SimRecords#NAME} as insert. |
| * However, in the case of update the {@link SimRecords#PHONE_NUMBER} may be omitted as |
| * the existing record will already have a valid value. |
| * </p> |
| * <dd><b>Delete</b></dd> |
| * <p> |
| * Delete may only be performed for individual records on {@link ElementaryFiles#EF_ADN}. |
| * Deleting records will free up space for use by future inserts. |
| * </p> |
| * <dd><b>Query</b></dd> |
| * <p> |
| * All the records stored on a specific elementary file can be read via a Uri returned by |
| * {@link SimRecords#getContentUri(int, int)}. This query always returns all records; there |
| * is no support for filtering via a selection. An individual record can be queried via a Uri |
| * returned by {@link SimRecords#getItemUri(int, int, int)}. Queries will throw an |
| * {@link IllegalArgumentException} when the SIM with the subscription ID or the elementary file |
| * type are invalid or unavailable. |
| * </p> |
| * </dl> |
| */ |
| public static final class SimRecords { |
| |
| /** |
| * The subscription ID of the SIM the record is from. |
| * |
| * @see SubscriptionInfo#getSubscriptionId() |
| */ |
| public static final String SUBSCRIPTION_ID = "subscription_id"; |
| /** |
| * The type of the elementary file the record is from. |
| * |
| * @see ElementaryFiles#EF_ADN |
| * @see ElementaryFiles#EF_FDN |
| * @see ElementaryFiles#EF_SDN |
| */ |
| public static final String ELEMENTARY_FILE_TYPE = "elementary_file_type"; |
| /** |
| * The 1-based offset of the record in the elementary file that contains it. |
| * |
| * <p>This can be used to access individual SIM records by appending it to the |
| * elementary file URIs but it is not like a normal database ID because it is not |
| * auto-incrementing and it is not unique across SIM cards or elementary files. Hence, care |
| * should be taken when using it to ensure that it is applied to the correct SIM and EF. |
| * |
| * @see #getItemUri(int, int, int) |
| */ |
| public static final String RECORD_NUMBER = "record_number"; |
| /** |
| * The name for this record. |
| * |
| * <p>An {@link IllegalArgumentException} will be thrown by insert and update if this |
| * exceeds the maximum supported length. Use |
| * {@link #getEncodedNameLength(ContentResolver, String)} to check how long the name |
| * will be after encoding. |
| * |
| * @see ElementaryFiles#NAME_MAX_LENGTH |
| * @see #getEncodedNameLength(ContentResolver, String) |
| */ |
| public static final String NAME = "name"; |
| /** |
| * The phone number for this record. |
| * |
| * <p>Only dialable characters are supported. |
| * |
| * <p>An {@link IllegalArgumentException} will be thrown by insert and update if this |
| * exceeds the maximum supported length or contains unsupported characters. |
| * |
| * @see ElementaryFiles#PHONE_NUMBER_MAX_LENGTH |
| * @see android.telephony.PhoneNumberUtils#isDialable(char) |
| */ |
| public static final String PHONE_NUMBER = "phone_number"; |
| |
| /** The MIME type of a CONTENT_URI subdirectory of a single SIM record. */ |
| public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/sim-contact_v2"; |
| /** The MIME type of CONTENT_URI providing a directory of SIM records. */ |
| public static final String CONTENT_TYPE = "vnd.android.cursor.dir/sim-contact_v2"; |
| |
| /** |
| * Value returned from {@link #getEncodedNameLength(ContentResolver, String)} when the name |
| * length could not be determined because the name could not be encoded. |
| */ |
| public static final int ERROR_NAME_UNSUPPORTED = -1; |
| |
| /** |
| * The method name used to get the encoded length of a value for {@link SimRecords#NAME} |
| * column. |
| * |
| * @hide |
| * @see #getEncodedNameLength(ContentResolver, String) |
| * @see ContentResolver#call(String, String, String, Bundle) |
| */ |
| public static final String GET_ENCODED_NAME_LENGTH_METHOD_NAME = "get_encoded_name_length"; |
| |
| /** |
| * Extra key used for an integer value that contains the length in bytes of an encoded |
| * name. |
| * |
| * @hide |
| * @see #getEncodedNameLength(ContentResolver, String) |
| * @see #GET_ENCODED_NAME_LENGTH_METHOD_NAME |
| */ |
| public static final String EXTRA_ENCODED_NAME_LENGTH = |
| "android.provider.extra.ENCODED_NAME_LENGTH"; |
| |
| |
| /** |
| * Key for the PIN2 needed to modify FDN record that should be passed in the Bundle |
| * passed to {@link ContentResolver#insert(Uri, ContentValues, Bundle)}, |
| * {@link ContentResolver#update(Uri, ContentValues, Bundle)} |
| * and {@link ContentResolver#delete(Uri, Bundle)}. |
| * |
| * <p>Modifying FDN records also requires either |
| * {@link android.Manifest.permission#MODIFY_PHONE_STATE} or |
| * {@link TelephonyManager#hasCarrierPrivileges()} |
| * |
| * @hide |
| */ |
| @SystemApi |
| public static final String QUERY_ARG_PIN2 = "android:query-arg-pin2"; |
| |
| private SimRecords() { |
| } |
| |
| /** |
| * Returns the content Uri for the specified elementary file on the specified SIM. |
| * |
| * <p>When queried this Uri will return all of the contact records in the specified |
| * elementary file on the specified SIM. The available subscriptionIds and efTypes can |
| * be discovered by querying {@link ElementaryFiles#CONTENT_URI}. |
| * |
| * <p>If a SIM with the provided subscription ID does not exist or the SIM with the provided |
| * subscription ID doesn't support the specified entity file then all operations will |
| * throw an {@link IllegalArgumentException}. |
| * |
| * @param subscriptionId the subscriptionId of the SIM card that this Uri will reference |
| * @param efType the elementary file on the SIM that this Uri will reference |
| * @see ElementaryFiles#EF_ADN |
| * @see ElementaryFiles#EF_FDN |
| * @see ElementaryFiles#EF_SDN |
| */ |
| @NonNull |
| public static Uri getContentUri(int subscriptionId, @ElementaryFiles.EfType int efType) { |
| return buildContentUri(subscriptionId, efType).build(); |
| } |
| |
| /** |
| * Content Uri for the specific SIM record with the provided {@link #RECORD_NUMBER}. |
| * |
| * <p>When queried this will return the record identified by the provided arguments. |
| * |
| * <p>For a non-existent record: |
| * <ul> |
| * <li>query will return an empty cursor</li> |
| * <li>update will return 0</li> |
| * <li>delete will return 0</li> |
| * </ul> |
| * |
| * @param subscriptionId the subscription ID of the SIM containing the record. If no SIM |
| * with this subscription ID exists then it will be treated as a |
| * non-existent record |
| * @param efType the elementary file type containing the record. If the specified |
| * SIM doesn't support this elementary file then it will be treated |
| * as a non-existent record. |
| * @param recordNumber the record number of the record this Uri should reference. This |
| * must be greater than 0. If there is no record with this record |
| * number in the specified entity file then it will be treated as a |
| * non-existent record. |
| * @see ElementaryFiles#SUBSCRIPTION_ID |
| * @see ElementaryFiles#EF_TYPE |
| * @see #RECORD_NUMBER |
| */ |
| @NonNull |
| public static Uri getItemUri( |
| int subscriptionId, @ElementaryFiles.EfType int efType, |
| @IntRange(from = 1) int recordNumber) { |
| // Elementary file record indices are 1-based. |
| Preconditions.checkArgument(recordNumber > 0, "Invalid recordNumber"); |
| |
| return buildContentUri(subscriptionId, efType) |
| .appendPath(String.valueOf(recordNumber)) |
| .build(); |
| } |
| |
| /** |
| * Returns the number of bytes required to encode the specified name when it is stored |
| * on the SIM. |
| * |
| * <p>{@link ElementaryFiles#NAME_MAX_LENGTH} is specified in bytes but the encoded name |
| * may require more than 1 byte per character depending on the characters it contains. So |
| * this method can be used to check whether a name exceeds the max length. |
| * |
| * @return the number of bytes required by the encoded name or |
| * {@link #ERROR_NAME_UNSUPPORTED} if the name could not be encoded. |
| * @throws IllegalStateException if the provider fails to return the length. |
| * @see SimRecords#NAME |
| * @see ElementaryFiles#NAME_MAX_LENGTH |
| */ |
| @WorkerThread |
| @IntRange(from = 0) |
| public static int getEncodedNameLength( |
| @NonNull ContentResolver resolver, @NonNull String name) { |
| Objects.requireNonNull(name); |
| Bundle result = resolver.call(AUTHORITY, GET_ENCODED_NAME_LENGTH_METHOD_NAME, name, |
| null); |
| if (result == null || !result.containsKey(EXTRA_ENCODED_NAME_LENGTH)) { |
| throw new IllegalStateException("Provider malfunction: no length was returned."); |
| } |
| int length = result.getInt(EXTRA_ENCODED_NAME_LENGTH, ERROR_NAME_UNSUPPORTED); |
| if (length < 0 && length != ERROR_NAME_UNSUPPORTED) { |
| throw new IllegalStateException( |
| "Provider malfunction: invalid length was returned."); |
| } |
| return length; |
| } |
| |
| private static Uri.Builder buildContentUri( |
| int subscriptionId, @ElementaryFiles.EfType int efType) { |
| return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT) |
| .authority(AUTHORITY) |
| .appendPath(SUBSCRIPTION_ID_PATH_SEGMENT) |
| .appendPath(String.valueOf(subscriptionId)) |
| .appendPath(getEfUriPath(efType)); |
| } |
| |
| } |
| |
| /** |
| * Constants for metadata about the elementary files of the SIM cards in the phone. |
| * |
| * <h3>Operations </h3> |
| * <dl> |
| * <dd><b>Insert</b></dd> |
| * <p>Insert is not supported for the Uris defined in this class.</p> |
| * <dd><b>Update</b></dd> |
| * <p>Update is not supported for the Uris defined in this class.</p> |
| * <dd><b>Delete</b></dd> |
| * <p>Delete is not supported for the Uris defined in this class.</p> |
| * <dd><b>Query</b></dd> |
| * <p> |
| * The elementary files for all the inserted SIMs can be read via |
| * {@link ElementaryFiles#CONTENT_URI}. Unsupported elementary files are omitted from the |
| * results. This Uri always returns all supported elementary files for all available SIMs; it |
| * does not support filtering via a selection. A specific elementary file can be queried |
| * via a Uri returned by {@link ElementaryFiles#getItemUri(int, int)}. If the elementary file |
| * referenced by this Uri is unsupported by the SIM then the query will return an empty cursor. |
| * </p> |
| * </dl> |
| */ |
| public static final class ElementaryFiles { |
| |
| /** {@link SubscriptionInfo#getSimSlotIndex()} of the SIM for this row. */ |
| public static final String SLOT_INDEX = "slot_index"; |
| /** {@link SubscriptionInfo#getSubscriptionId()} of the SIM for this row. */ |
| public static final String SUBSCRIPTION_ID = "subscription_id"; |
| /** |
| * The elementary file type for this row. |
| * |
| * @see ElementaryFiles#EF_ADN |
| * @see ElementaryFiles#EF_FDN |
| * @see ElementaryFiles#EF_SDN |
| */ |
| public static final String EF_TYPE = "ef_type"; |
| /** The maximum number of records supported by the elementary file. */ |
| public static final String MAX_RECORDS = "max_records"; |
| /** Count of the number of records that are currently stored in the elementary file. */ |
| public static final String RECORD_COUNT = "record_count"; |
| /** The maximum length supported for the name of a record in the elementary file. */ |
| public static final String NAME_MAX_LENGTH = "name_max_length"; |
| /** |
| * The maximum length supported for the phone number of a record in the elementary file. |
| */ |
| public static final String PHONE_NUMBER_MAX_LENGTH = "phone_number_max_length"; |
| |
| /** |
| * A value for an elementary file that is not recognized. |
| * |
| * <p>Generally this should be ignored. If new values are added then this will be used |
| * for apps that target SDKs where they aren't defined. |
| */ |
| public static final int EF_UNKNOWN = 0; |
| /** |
| * Type for accessing records in the "abbreviated dialing number" (ADN) elementary file on |
| * the SIM. |
| * |
| * <p>ADN records are typically user created. |
| */ |
| public static final int EF_ADN = 1; |
| /** |
| * Type for accessing records in the "fixed dialing number" (FDN) elementary file on the |
| * SIM. |
| * |
| * <p>FDN numbers are the numbers that are allowed to dialed for outbound calls when FDN is |
| * enabled. |
| * |
| * <p>FDN records cannot be modified by applications. Hence, insert, update and |
| * delete methods operating on this Uri will throw UnsupportedOperationException |
| */ |
| public static final int EF_FDN = 2; |
| /** |
| * Type for accessing records in the "service dialing number" (SDN) elementary file on the |
| * SIM. |
| * |
| * <p>Typically SDNs are preset numbers provided by the carrier for common operations (e.g. |
| * voicemail, check balance, etc). |
| * |
| * <p>SDN records cannot be modified by applications. Hence, insert, update and delete |
| * methods operating on this Uri will throw UnsupportedOperationException |
| */ |
| public static final int EF_SDN = 3; |
| /** |
| * The Uri path segment used to target the ADN elementary file for SimPhonebookProvider |
| * content operations. |
| * |
| * @hide |
| */ |
| public static final String PATH_SEGMENT_EF_ADN = "adn"; |
| /** |
| * The Uri path segment used to target the FDN elementary file for SimPhonebookProvider |
| * content operations. |
| * |
| * @hide |
| */ |
| public static final String PATH_SEGMENT_EF_FDN = "fdn"; |
| /** |
| * The Uri path segment used to target the SDN elementary file for SimPhonebookProvider |
| * content operations. |
| * |
| * @hide |
| */ |
| public static final String PATH_SEGMENT_EF_SDN = "sdn"; |
| /** The MIME type of CONTENT_URI providing a directory of ADN-like elementary files. */ |
| public static final String CONTENT_TYPE = "vnd.android.cursor.dir/sim-elementary-file"; |
| /** The MIME type of a CONTENT_URI subdirectory of a single ADN-like elementary file. */ |
| public static final String CONTENT_ITEM_TYPE = |
| "vnd.android.cursor.item/sim-elementary-file"; |
| /** |
| * The Uri path segment used to construct Uris for the metadata defined in this class. |
| * |
| * @hide |
| */ |
| public static final String ELEMENTARY_FILES_PATH_SEGMENT = "elementary_files"; |
| |
| /** Content URI for the ADN-like elementary files available on the device. */ |
| @NonNull |
| public static final Uri CONTENT_URI = AUTHORITY_URI |
| .buildUpon() |
| .appendPath(ELEMENTARY_FILES_PATH_SEGMENT).build(); |
| |
| private ElementaryFiles() { |
| } |
| |
| /** |
| * Returns a content uri for a specific elementary file. |
| * |
| * <p>If a SIM with the specified subscriptionId is not present an exception will be thrown. |
| * If the SIM doesn't support the specified elementary file it will return an empty cursor. |
| */ |
| @NonNull |
| public static Uri getItemUri(int subscriptionId, @EfType int efType) { |
| return CONTENT_URI.buildUpon().appendPath(SUBSCRIPTION_ID_PATH_SEGMENT) |
| .appendPath(String.valueOf(subscriptionId)) |
| .appendPath(getEfUriPath(efType)) |
| .build(); |
| } |
| |
| /** |
| * Annotation for the valid elementary file types. |
| * |
| * @hide |
| */ |
| @Retention(RetentionPolicy.SOURCE) |
| @IntDef( |
| prefix = {"EF"}, |
| value = {EF_UNKNOWN, EF_ADN, EF_FDN, EF_SDN}) |
| public @interface EfType { |
| } |
| } |
| } |
