SimPhonebookContract.SimRecords
public
static
final
class
SimPhonebookContract.SimRecords
extends Object
java.lang.Object | |
↳ | android.provider.SimPhonebookContract.SimRecords |
Constants for the contact records on a SIM card.
Data
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 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 ElementaryFiles#MAX_RECORDS
column.
The SimRecords#PHONE_NUMBER
column can only contain dialable characters and this
applies regardless of the SIM that is being used. See
PhoneNumberUtils.isDialable(char)
for more details. Additionally
the phone number can contain at most ElementaryFiles#PHONE_NUMBER_MAX_LENGTH
characters. The SimRecords#NAME
column can contain at most
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
SimRecords#getEncodedNameLength(ContentResolver, String)
.
Operations
- Insert
- Update
- Delete
- Query
Only ElementaryFiles#EF_ADN
supports inserts. 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 Data
section above an IllegalArgumentException
will be thrown. The
SimRecords#NAME
column may be omitted but if provided and it violates any of
the requirements discussed in the Data section above
an IllegalArgumentException
will be thrown.
If an insert is not possible because the elementary file is full then an
IllegalStateException
will be thrown.
Updates can only be performed for individual records on ElementaryFiles#EF_ADN
.
A specific record is referenced via the Uri returned by
SimRecords#getItemUri(int, int, int)
. Updates have the same constraints and
behavior for the SimRecords#PHONE_NUMBER
and SimRecords#NAME
as insert.
However, in the case of update the SimRecords#PHONE_NUMBER
may be omitted as
the existing record will already have a valid value.
Delete may only be performed for individual records on ElementaryFiles#EF_ADN
.
Deleting records will free up space for use by future inserts.
All the records stored on a specific elementary file can be read via a Uri returned by
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 SimRecords#getItemUri(int, int, int)
. Queries will throw an
IllegalArgumentException
when the SIM with the subscription ID or the elementary file
type are invalid or unavailable.
Summary
Constants | |
---|---|
String |
CONTENT_ITEM_TYPE
The MIME type of a CONTENT_URI subdirectory of a single SIM record. |
String |
CONTENT_TYPE
The MIME type of CONTENT_URI providing a directory of SIM records. |
String |
ELEMENTARY_FILE_TYPE
The type of the elementary file the record is from. |
int |
ERROR_NAME_UNSUPPORTED
Value returned from |
String |
NAME
The name for this record. |
String |
PHONE_NUMBER
The phone number for this record. |
String |
RECORD_NUMBER
The 1-based offset of the record in the elementary file that contains it. |
String |
SUBSCRIPTION_ID
The subscription ID of the SIM the record is from. |
Public methods | |
---|---|
static
Uri
|
getContentUri(int subscriptionId, int efType)
Returns the content Uri for the specified elementary file on the specified SIM. |
static
int
|
getEncodedNameLength(ContentResolver resolver, String name)
Returns the number of bytes required to encode the specified name when it is stored on the SIM. |
static
Uri
|
getItemUri(int subscriptionId, int efType, int recordNumber)
Content Uri for the specific SIM record with the provided |
Inherited methods | |
---|---|
Constants
CONTENT_ITEM_TYPE
public static final String CONTENT_ITEM_TYPE
The MIME type of a CONTENT_URI subdirectory of a single SIM record.
Constant Value: "vnd.android.cursor.item/sim-contact_v2"
CONTENT_TYPE
public static final String CONTENT_TYPE
The MIME type of CONTENT_URI providing a directory of SIM records.
Constant Value: "vnd.android.cursor.dir/sim-contact_v2"
ELEMENTARY_FILE_TYPE
public static final String ELEMENTARY_FILE_TYPE
The type of the elementary file the record is from.
See also:
Constant Value: "elementary_file_type"
ERROR_NAME_UNSUPPORTED
public static final int ERROR_NAME_UNSUPPORTED
Value returned from getEncodedNameLength(android.content.ContentResolver, java.lang.String)
when the name
length could not be determined because the name could not be encoded.
Constant Value: -1 (0xffffffff)
NAME
public static final String NAME
The name for this record.
An IllegalArgumentException
will be thrown by insert and update if this
exceeds the maximum supported length. Use
getEncodedNameLength(android.content.ContentResolver, java.lang.String)
to check how long the name
will be after encoding.
See also:
Constant Value: "name"
PHONE_NUMBER
public static final String PHONE_NUMBER
The phone number for this record.
Only dialable characters are supported.
An IllegalArgumentException
will be thrown by insert and update if this
exceeds the maximum supported length or contains unsupported characters.
See also:
Constant Value: "phone_number"
RECORD_NUMBER
public static final String RECORD_NUMBER
The 1-based offset of the record in the elementary file that contains it.
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 also:
Constant Value: "record_number"
SUBSCRIPTION_ID
public static final String SUBSCRIPTION_ID
The subscription ID of the SIM the record is from.
See also:
Constant Value: "subscription_id"
Public methods
getContentUri
public static Uri getContentUri (int subscriptionId, int efType)
Returns the content Uri for the specified elementary file on the specified SIM.
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 ElementaryFiles#CONTENT_URI
.
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 IllegalArgumentException
.
Parameters | |
---|---|
subscriptionId |
int : the subscriptionId of the SIM card that this Uri will reference |
efType |
int : the elementary file on the SIM that this Uri will reference
Value is SimPhonebookContract.ElementaryFiles.EF_UNKNOWN , SimPhonebookContract.ElementaryFiles.EF_ADN , SimPhonebookContract.ElementaryFiles.EF_FDN , or SimPhonebookContract.ElementaryFiles.EF_SDN |
Returns | |
---|---|
Uri |
This value cannot be null . |
getEncodedNameLength
public static int getEncodedNameLength (ContentResolver resolver, String name)
Returns the number of bytes required to encode the specified name when it is stored on the SIM.
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.
This method may take several seconds to complete, so it should
only be called from a worker thread.
Parameters | |
---|---|
resolver |
ContentResolver : This value cannot be null . |
name |
String : This value cannot be null . |
Returns | |
---|---|
int |
the number of bytes required by the encoded name or
ERROR_NAME_UNSUPPORTED if the name could not be encoded.
Value is 0 or greater |
Throws | |
---|---|
IllegalStateException |
if the provider fails to return the length. |
getItemUri
public static Uri getItemUri (int subscriptionId, int efType, int recordNumber)
Content Uri for the specific SIM record with the provided RECORD_NUMBER
.
When queried this will return the record identified by the provided arguments.
For a non-existent record:
- query will return an empty cursor
- update will return 0
- delete will return 0
Parameters | |
---|---|
subscriptionId |
int : 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 |
efType |
int : 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.
Value is SimPhonebookContract.ElementaryFiles.EF_UNKNOWN , SimPhonebookContract.ElementaryFiles.EF_ADN , SimPhonebookContract.ElementaryFiles.EF_FDN , or SimPhonebookContract.ElementaryFiles.EF_SDN |
recordNumber |
int : 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.
Value is 1 or greater |
Returns | |
---|---|
Uri |
This value cannot be null . |