com.nttdocomo.system.PhoneBook
Object
携帯電話のネイティブの電話帳管理機能にアクセスする手段を提供します。 このクラスのインスタンスは、 携帯電話のネイティブの電話帳の 1 つのエントリを表します。
このクラスに定義されているクラスメソッドの使い方や、
ネイティブのデータへのアクセス方法に関する規定の大原則は
com.nttdocomo.system パッケージの記述を参照して下さい。
ただし、エントリ登録機能 (addEntry()) については、
下記の点が大原則と異なります。
addEntry() の戻り値について:addEntry() は、
登録された電話帳のエントリ ID の他に、
そのエントリが登録された電話帳グループのエントリ
ID を返します。
詳細は、各メソッドの説明を参照して下さい。
Phone.call(String) で例外が発生するような文字列
addEntry(String, String, String[], String[], String)、
addEntry(PhoneBookParam)
を参照して下さい。
Location.ACCURACY_UNKNOWN が指定されていた場合には、
登録画面の測位レベルに何が設定されているかは機種依存です。
電話帳エントリからは、電話帳のエントリ ID の他、 名前 (XString)、読み仮名 (XString)、 電話番号(XString)、メールアドレス(XString)、電話帳グループ名(XString)、 電話帳グループのエントリ ID が、それぞれ取得できます。
名前と読み仮名を姓と名に区別して登録できるかどうかは機種依存です。 以下のことに注意してください。
PhoneBookParam.setName(String) メソッド、
PhoneBookParam.setKana(String) メソッド、
PhoneBookParam
クラスの各コンストラクタを用いて名前や読み仮名を設定した場合、
設定した文字列は姓として登録されます。
PhoneBookParam.setName(int, String) メソッドや
PhoneBookParam.setKana(int, String)
メソッドを用いて名前や読み仮名を設定した場合、
設定された文字列の姓と名の文字列を結合し、一つの文字列として登録されます。
その場合、登録された文字列は、
名前の場合は
getName() や getName(FAMILY_NAME) で、
読み仮名の場合は
getKana() や getKana(FAMILY_NAME) で、
それぞれ取得することができます。
PhoneBookGroup,
PhoneBookParam| フィールドの概要 |
| インタフェース com.nttdocomo.system.MailConstants から継承したフィールド |
ADDRESS_DOMAIN, ADDRESS_FULL, ADDRESS_USER, RECEIVED, SENT, UNSENT |
| インタフェース com.nttdocomo.system.PhoneBookConstants から継承したフィールド |
FAMILY_NAME, GIVEN_NAME |
| メソッドの概要 | |
static int[] |
addEntry(PhoneBookParam param)
ユーザ操作により電話帳エントリを新規登録します。 |
static int[] |
addEntry(String name,
String kana,
String[] phoneNumbers,
String[] mailAddresses,
int groupId)
ユーザ操作により電話帳エントリを新規登録します。 |
static int[] |
addEntry(String name,
String kana,
String[] phoneNumbers,
String[] mailAddresses,
String groupName)
ユーザ操作により電話帳エントリを新規登録します。 |
static PhoneBook |
getEntry(int id)
電話帳のエントリ ID を指定して、 ユーザ操作なしに電話帳のエントリを取得します。 |
int |
getGroupId()
電話帳エントリの電話帳グループのエントリ ID を取得します。 |
XString |
getGroupName()
電話帳エントリの電話帳グループ名(XString)を取得します。 |
int |
getId()
電話帳のエントリ ID を取得します。 |
XString |
getKana()
電話帳エントリの読み仮名(XString)を取得します。 |
XString |
getKana(int part)
電話帳エントリの姓や名の読み仮名(XString)を取得します。 |
Location |
getLocation() [iアプリオプションAPI]
電話帳エントリ内に登録されている位置情報を取得します。 |
XString |
getMailAddress(int index,
int part)
電話帳エントリのメールアドレス(XString)の1つを取得します。 |
XString[] |
getMailAddresses(int part)
電話帳エントリのメールアドレス(XString)を取得します。 |
XString |
getName()
電話帳エントリの名前(XString)を取得します。 |
XString |
getName(int part)
電話帳エントリの姓や名(XString)を取得します。 |
XString |
getPhoneNumber(int index)
電話帳エントリの電話番号(XString)の1つを取得します。 |
XString[] |
getPhoneNumbers()
電話帳エントリの電話番号(XString)を取得します。 |
static PhoneBook |
selectEntry()
ユーザ操作により電話帳のエントリを取得します。 |
| クラス Object から継承したメソッド |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| メソッドの詳細 |
public static PhoneBook selectEntry()
throws InterruptedOperationException
取得されたエントリの電話番号やメールアドレスの配列は、 未登録部分は取り除いて設定されています。 例えば、電話番号が3つ保持できる実装において、 1つ目と3つ目の電話番号が未登録であった場合には、 2つ目に登録されている電話番号だけからなる配列が設定されます。
パーミッションとして携帯電話情報の参照が許可されている
トラステッドiアプリのみこのメソッドを呼び出すことができます。
上記以外の動作の詳細については、このクラスの説明、
ならびにその説明から引用されている
com.nttdocomo.system パッケージに記述されている
「エントリ取得時の振る舞い」の説明を参照して下さい。
IllegalStateException - 待ち受け実行時の非活性化状態で呼び出された場合に発生します。
SecurityException - パーミッションとして携帯電話情報の参照が許可されているが、
iアプリ個別のユーザ設定により許可されない場合に発生します。
SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、
電話帳エントリを取得できない場合に発生します。
IllegalStateException -
[DoJa-4.0 (901i) 以降] FOMA端末で、UIM読み込み中の場合に発生します。
InterruptedOperationException - 競合条件などにより、選択操作が異常終了した場合に発生します。
public static PhoneBook getEntry(int id)
throws StoreException
取得されたエントリの電話番号やメールアドレスの配列は、 未登録部分は取り除いて設定されています。 例えば、電話番号が3つ保持できる実装において、 1つ目と3つ目の電話番号が未登録であった場合には、 2つ目に登録されている電話番号だけからなる配列が設定されます。
パーミッションとして携帯電話情報の参照が許可されている
トラステッドiアプリのみこのメソッドを呼び出すことができます。
上記以外の動作の詳細については、このクラスの説明、
ならびにその説明から引用されている
com.nttdocomo.system パッケージに記述されている
「エントリ取得時の振る舞い」の説明を参照して下さい。
id - 電話帳のエントリ ID を指定します。
SecurityException - パーミッションとして携帯電話情報の参照が許可されているが、
iアプリ個別のユーザ設定により許可されない場合に発生します。
SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、
電話帳エントリを取得できない場合に発生します。
StoreException - 指定したIDのエントリが存在しない場合に発生します(NOT_FOUND)。
シークレット設定された電話帳エントリをシークレット解除された状態で取得しようとした場合にも発生します。
IllegalStateException -
[DoJa-4.0 (901i) 以降] FOMA端末で、UIM読み込み中の場合に発生します。
CallRecord.getPhoneBookID(),
MessageReceived.getPhoneBookID(),
addEntry(String, String, String[], String[], String),
addEntry(String, String, String[], String[], int),
addEntry(PhoneBookParam),
getId()
public static int[] addEntry(String name,
String kana,
String[] phoneNumbers,
String[] mailAddresses,
String groupName)
throws InterruptedOperationException
登録が成功した場合、戻り値は長さ2の int の配列です。
配列の0番目の要素には、
登録された電話帳のエントリ ID が設定されています。
配列の1番目の要素には、
そのエントリの電話帳グループのエントリ ID が設定されています。
すなわち、戻り値を ids とすると、
PhoneBook.getEntry(ids[0]).getGroupId() == ids[1]
となります。
トラステッドiアプリでない場合、
電話帳のエントリ ID には、ダミーの ID が返ります。
電話帳グループのエントリ ID には、
トラステッドiアプリ、一般アプリの区別によらず、
実際に登録されたグループの ID が設定されています。
電話帳グループ名として null を指定すると、 電話帳グループを指定しないことを表し、 ネイティブ電話帳新規登録機能をグループ指定せずに起動した場合と同様の動作になります。 指定されたグループ名の電話帳グループが存在しない場合、 ユーザ操作による電話帳グループ作成処理が行われます。 電話帳グループ名に空文字列を指定した場合、 空文字列の電話帳グループに登録することを表し、 電話帳グループ名を指定して登録を行う場合と同様の動作になります。 なお、電話帳グループが存在する場合とは、 大文字小文字の区別も含め電話帳グループ名が完全一致する場合とします。
ADFにAccessUserInfoキーの指定が必要です。
上記以外の動作の詳細については、このクラスの説明、
ならびに、その説明から引用されている
com.nttdocomo.system
パッケージに記述されている説明を参照して下さい。
[DoJa-4.0 (901i) 以降]
データ保存領域の容量を超えているために登録できない場合は、
ユーザが登録操作をキャンセルした場合と同様の値を返します。
電話帳グループを新規登録する場合も同様です。
FOMA 端末において、
このメソッドでは位置情報を登録することはできません(位置情報には
null
が指定されているものとして扱われます)。
位置情報を登録したい場合には、
addEntry(PhoneBookParam) メソッドの引数に、
位置情報を設定した PhoneBookParam
オブジェクトを指定して下さい。
name - 名前(通常文字列)を指定します。
姓と名が区別可能な場合、姓として登録されます。kana - 読み仮名(通常文字列)を指定します。
姓と名が区別可能な場合、姓として登録されます。phoneNumbers - 電話番号(通常文字列)を配列で指定します。mailAddresses - メールアドレス(通常文字列)を配列で指定します。groupName - 電話帳グループ名(通常文字列)を指定します。
電話帳グループを指定しない場合には、null を指定します。
IllegalStateException - ダウンロード即起動アプリがこのメソッドを呼び出した場合に発生します。
IllegalStateException - 待ち受け実行時の非活性化状態で呼び出された場合に発生します。
NullPointerException - 引数 phoneNumbers, mailAddresses がそれぞれ null でない場合に、
配列中に null の要素があった場合に発生します。
IllegalArgumentException - 電話番号として登録できない文字列が指定された場合、
実装がサポートしている長さ以上の電話番号が指定された場合、
実装がサポートしている数以上の電話番号が指定された場合に発生します。
IllegalArgumentException - メールアドレスとして登録できない文字列が指定された場合、
実装がサポートしている長さ以上のメールアドレスが指定された場合、
実装がサポートしている数以上のメールアドレスが指定された場合に発生します。
SecurityException - ADFにAccessUserInfoキーの指定がないアプリケーションが
このメソッドを呼び出した場合に発生します。
SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、
電話帳への登録ができない場合に発生します。
IllegalStateException -
[DoJa-4.0 (901i) 以降] FOMA端末で、UIM読み込み中の場合に発生します。
InterruptedOperationException - 競合条件などにより、登録操作が異常終了した場合に発生します。
public static int[] addEntry(String name,
String kana,
String[] phoneNumbers,
String[] mailAddresses,
int groupId)
throws InterruptedOperationException,
StoreException
登録が成功した場合、戻り値は長さ2の int の配列です。
配列の0番目の要素には、
登録された電話帳のエントリ ID が設定されています。
配列の1番目の要素には、
そのエントリの電話帳グループのエントリ ID が設定されています。
すなわち、戻り値を ids とすると、
PhoneBook.getEntry(ids[0]).getGroupId() == ids[1]
となります。
トラステッドiアプリでない場合、
電話帳のエントリ ID には、ダミーの ID が返ります。
電話帳グループのエントリ ID には、
トラステッドiアプリ、一般アプリの区別によらず、
実際に登録された電話帳グループの エントリ ID
(引数 groupId に指定した値ではない)
が設定されています。
電話帳グループのエントリ IDとして -1 を指定すると、 電話帳グループを指定しないことを表し、 ネイティブ電話帳新規登録機能をグループ指定せずに起動した場合と同様の動作になります。 指定されたエントリ ID の電話帳グループが存在しない場合、 例外が発生します。
ADFにAccessUserInfoキーの指定が必要です。
上記以外の動作の詳細については、このクラスの説明、
ならびに、その説明から引用されている
com.nttdocomo.system
パッケージに記述されている説明を参照して下さい。
[DoJa-4.0 (901i) 以降]
データ保存領域の容量を超えているために登録できない場合は、
ユーザが登録操作をキャンセルした場合と同様の値を返します。
FOMA 端末において、
このメソッドでは位置情報を登録することはできません(位置情報には
null
が指定されているものとして扱われます)。
位置情報を登録したい場合には、
addEntry(PhoneBookParam) メソッドの引数に、
位置情報を設定した PhoneBookParam
オブジェクトを指定して下さい。
name - 名前(通常文字列)を指定します。
姓と名が区別可能な場合、姓として登録されます。kana - 読み仮名(通常文字列)を指定します。
姓と名が区別可能な場合、姓として登録されます。phoneNumbers - 電話番号(通常文字列)を配列で指定します。mailAddresses - メールアドレス(通常文字列)を配列で指定します。groupId - 電話帳グループのエントリ ID を指定します。
電話帳グループを指定しない場合には、-1 を指定します。
IllegalStateException - ダウンロード即起動アプリがこのメソッドを呼び出した場合に発生します。
IllegalStateException - 待ち受け実行時の非活性化状態で呼び出された場合に発生します。
NullPointerException - 引数 phoneNumbers, mailAddresses がそれぞれ null でない場合に、
配列中に null の要素があった場合に発生します。
IllegalArgumentException - 電話番号として登録できない文字列が指定された場合、
実装がサポートしている長さ以上の電話番号が指定された場合、
実装がサポートしている数以上の電話番号が指定された場合に発生します。
IllegalArgumentException - メールアドレスとして登録できない文字列が指定された場合、
実装がサポートしている長さ以上のメールアドレスが指定された場合、
実装がサポートしている数以上のメールアドレスが指定された場合に発生します。
SecurityException - ADFにAccessUserInfoキーの指定がないアプリケーションが
このメソッドを呼び出した場合に発生します。
SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、
電話帳への登録ができない場合に発生します。
StoreException - 指定したエントリ ID
の電話帳グループが存在しない場合に発生します(NOT_FOUND)。
IllegalStateException -
[DoJa-4.0 (901i) 以降] FOMA端末で、UIM読み込み中の場合に発生します。
InterruptedOperationException - 競合条件などにより、登録操作が異常終了した場合に発生します。
public static int[] addEntry(PhoneBookParam param)
throws InterruptedOperationException,
StoreException
登録が成功した場合、戻り値は長さ2の int の配列です。
配列の0番目の要素には、
登録された電話帳エントリのエントリ ID が設定されています。
配列の1番目の要素には、
そのエントリの電話帳グループのエントリ ID が設定されています。
すなわち、戻り値を ids とすると、
PhoneBook.getEntry(ids[0]).getGroupId() == ids[1]
となります。
トラステッドiアプリでない場合、
電話帳エントリのエントリ ID には、ダミーの ID が返ります。
電話帳グループのエントリ ID には、
トラステッドiアプリ、一般アプリの区別によらず、
実際に登録された電話帳グループのエントリ ID
(引数に指定した電話帳グループのエントリ ID ではない)
が設定されています。
引数 param の PhoneBookParam オブジェクトに電話帳グループ名が指定されており、 その電話帳グループが存在しない場合、 ユーザ操作による電話帳グループ作成処理が行われます。 電話帳グループのエントリ ID が指定されていてその電話帳グループが存在しない場合、 例外が発生します。 電話帳グループのエントリ ID -1 電話帳とグループ名 null はそれぞれ電話帳グループを指定しないことを表し、 ネイティブ電話帳新規登録機能をグループ指定せずに起動した場合と同様の動作になります。 電話帳グループ名に空文字列を指定した場合、 空文字列の電話帳グループに登録することを表し、 電話帳グループ名を指定して登録を行う場合と同様の動作になります。 なお、電話帳グループが存在する場合とは、 大文字小文字の区別も含め電話帳グループ名が完全一致する場合とします。
ADFにAccessUserInfoキーの指定が必要です。
上記以外の動作の詳細については、このクラスの説明、
ならびに、その説明から引用されている
com.nttdocomo.system
パッケージに記述されている説明を参照して下さい。
[DoJa-4.0 (901i) 以降]
データ保存領域の容量を超えているために登録できない場合は、
ユーザが登録操作をキャンセルした場合と同様の値を返します。
電話帳グループを新規登録する場合も同様です。
param - 電話帳エントリのパラメータを指定します。
IllegalStateException - ダウンロード即起動アプリがこのメソッドを呼び出した場合に発生します。
IllegalStateException - 待ち受け実行時の非活性化状態で呼び出された場合に発生します。
NullPointerException - 引数 param が null の場合に発生します。
SecurityException - ADFにAccessUserInfoキーの指定がないアプリケーションが
このメソッドを呼び出した場合に発生します。
SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、
電話帳への登録ができない場合に発生します。
StoreException - 電話帳グループのエントリ ID が指定されているときに、
指定したエントリ ID
の電話帳グループが存在しない場合に発生します(NOT_FOUND)。
IllegalStateException -
[DoJa-4.0 (901i) 以降] FOMA端末で、UIM読み込み中の場合に発生します。
InterruptedOperationException - 競合条件などにより、登録操作が異常終了した場合に発生します。
public int getId()
public XString getName()
public XString getName(int part)
getName()で返る名前)
が返ります。
名を指定した場合、nullが返ります。
part - 姓、名の区別を指定します。
FAMILY_NAME、
GIVEN_NAME
のいずれかを指定します。
IllegalArgumentException - 引数 part の値が不正な場合に発生します。
public XString getKana()
public XString getKana(int part)
getKana()で返る読み仮名)
が返ります。
名を指定した場合、nullが返ります。
part - 姓、名の区別を指定します。
FAMILY_NAME、
GIVEN_NAME
のいずれかを指定します。
IllegalArgumentException - 引数 part の値が不正な場合に発生します。
public XString[] getPhoneNumbers()
電話帳エントリに空文字列の電話番号が登録されている場合、 その電話番号は無視され、 このメソッドの戻り値には含まれません。
public XString getPhoneNumber(int index)
index - 電話番号のインデックスを指定します。
ArrayIndexOutOfBoundsException - 指定されたインデックスの電話番号が存在しない場合に発生します。
public XString[] getMailAddresses(int part)
電話帳エントリに空文字列のメールアドレスが登録されている場合、 そのメールアドレスは無視され、 このメソッドの戻り値には含まれません。
part - アドレス中の取得する部分を指定します。
ADDRESS_FULL、
ADDRESS_USER、
ADDRESS_DOMAIN
のいずれかを指定します。
IllegalArgumentException - 引数 part の値が不正な場合に発生します。
public XString getMailAddress(int index,
int part)
index - メールアドレスのインデックスを指定します。part - アドレス中の取得する部分を指定します。
ADDRESS_FULL、
ADDRESS_USER、
ADDRESS_DOMAIN
のいずれかを指定します。
ArrayIndexOutOfBoundsException - 指定されたインデックスのメールアドレスが存在しない場合に発生します。
IllegalArgumentException - 引数 part の値が不正な場合に発生します。
public XString getGroupName()
public int getGroupId()
public Location getLocation() [iアプリオプションAPI]
電話帳エントリ内に登録されている位置情報を取得します。
パーミッションとして位置情報APIの利用が許可されているトラステッド i アプリのみこのメソッドを呼び出すことができます。 (PhoneBook オブジェクトを取得するためには、パーミッションとして携帯電話情報の 参照が許可されている必要があるため、 結果的にこのメソッドを呼び出すためにはこれら二つの パーミッションが両方とも許可されている必要があります。)
取得した位置情報の各項目は、それぞれ以下のように初期化されています。
Location.ACCURACY_UNKNOWN
で初期化されています。
Location.ALTITUDE_UNKNOWN で初期化されています。
なお、以下の場合には
null が返されます。