概要  パッケージ   クラス  階層ツリー  非推奨 API  索引  ヘルプ 
 前のクラス   次のクラス フレームあり    フレームなし    
概要:  入れ子 | フィールド | コンストラクタ | メソッド 詳細:  フィールド | コンストラクタ | メソッド

com.nttdocomo.system
クラス PhoneBook

Object
  |
  +--com.nttdocomo.system.PhoneBook
すべての実装インタフェース:
MailConstants, PhoneBookConstants
public final class PhoneBook
extends Object
implements MailConstants, PhoneBookConstants

携帯電話のネイティブの電話帳機能にアクセスする手段を提供します。

電話帳データの取得および新規登録機能を提供します。 ネイティブデータへのアクセス機能およびそのXObjectとの関係の基本については、 XObjectクラスの説明を参照してください。

selectEntry() メソッドを実行することにより、 ネイティブのユーザインタフェースを介して、 端末に登録されている電話帳データの一覧から 電話帳のエントリを取得することができます。 取得されたエントリには、 電話帳エントリのID、 名前(XString)、 読み仮名(XString)、 電話番号(XString)、 メールアドレス(XString)、 グループ名(XString)、 グループIDが設定されています。 また、電話帳エントリのIDを指定して、 getEntry(int)メソッドにより ユーザ操作によらずにエントリを取得することもできます。

電話帳データを新規に登録するためには、 addEntry(String, String, String[], String[], String)メソッドまたは addEntry(String, String, String[], String[], int)メソッドを直接呼び出すか、 PhoneBookParamオブジェクトに対して電話帳情報を設定して addEntry(PhoneBookParam) メソッドを呼び出します。 登録はネイティブのユーザインタフェースを介して行われ、 addEntryメソッドは戻り値として 登録された電話帳エントリのIDとそのエントリが登録されたグループのID を返します。 戻り値のグループIDは、実際に登録されたグループのIDであり、 addEntryメソッドの引数により指定したグループIDと同じであるとは限りません。

グループ名を指定して電話帳データの登録を行ったときに そのグループ名のグループが存在しない場合、 グループ作成画面に移行し、 グループ作成が終了してから電話帳データの登録が行われます。 グループIDを指定して電話帳データの登録を行ったときに そのグループIDのグループが存在しない場合、 例外が発生します。 グループID -1 とグループ名 null はそれぞれグループを指定しないことを表し、 ネイティブの標準のグループが指定されたことになります。

ミニマムスペック:

導入されたバージョン:
DoJa-3.0
関連項目:
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)を取得します。
 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
 

メソッドの詳細

selectEntry

public static PhoneBook selectEntry()
                             throws InterruptedOperationException
ユーザ操作により電話帳のエントリを取得します。

取得されたエントリには、 ID、 名前(XString)、 読み仮名(XString)、 電話番号(XString)、 メールアドレス(XString)、 グループID、 グループ名(XString)が設定されています。

パーミッションとして携帯電話情報の参照が許可されている トラステッドiアプリのみこのメソッドを呼び出すことができます。 このメソッドを呼び出すとサスペンドします。

戻り値:
取得した電話帳のエントリを返します。 ユーザが選択操作をキャンセルするとnullを返します。 また、選択可能なエントリが存在しない場合にもnullを返します。
例外:
IllegalStateException - 待ち受け実行時の非活性化状態で呼び出された場合に発生します。
SecurityException - パーミッションとして携帯電話情報の参照が許可されているが、 iアプリ個別のユーザ設定により許可されない場合に発生します。
SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、 電話帳エントリを取得できない場合に発生します。
InterruptedOperationException - 競合条件などにより、選択操作が異常終了した場合に発生します。

getEntry

public static PhoneBook getEntry(int id)
                          throws StoreException
電話帳エントリのIDを指定して、 ユーザ操作なしに電話帳のエントリを取得します。

取得されたエントリには、 ID、 名前(XString)、 読み仮名(XString)、 電話番号(XString)、 メールアドレス(XString)、 グループID、 グループ名(XString)が設定されています。

パーミッションとして携帯電話情報の参照が許可されている トラステッドiアプリのみこのメソッドを呼び出すことができます。

パラメータ:
id - 電話帳エントリのIDを指定します。
戻り値:
取得した電話帳のエントリを返します。
例外:
SecurityException - パーミッションとして携帯電話情報の参照が許可されているが、 iアプリ個別のユーザ設定により許可されない場合に発生します。
SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、 電話帳エントリを取得できない場合に発生します。
StoreException - 指定したIDのエントリが存在しない場合に発生します(NOT_FOUND)。 シークレット設定された電話帳エントリをシークレット解除された状態で取得しようとした場合にも発生します。
関連項目:
CallRecord.getPhoneBookID(), MessageReceived.getPhoneBookID(), addEntry(String, String, String[], String[], String), addEntry(String, String, String[], String[], int), addEntry(PhoneBookParam), getId()

addEntry

public static int[] addEntry(String name,
                             String kana,
                             String[] phoneNumbers,
                             String[] mailAddresses,
                             String groupName)
                      throws InterruptedOperationException
ユーザ操作により電話帳エントリを新規登録します。 各引数はnullや長さ0の配列でもかまいません。

登録が成功した場合、戻り値は長さ2のintの配列です。 配列の0番目の要素には、登録された電話帳エントリのIDが設定されています。 配列の1番目の要素には、そのエントリの電話帳グループのIDが設定されています。 すなわち、戻り値を ids とすると、
PhoneBook.getEntry(ids[0]).getGroupId() == ids[1]
となります。
トラステッドiアプリでない場合、 電話帳エントリのIDには、ダミーのIDが返ります。 電話帳グループのIDには、トラステッドiアプリ、一般アプリの区別によらず、実際に登録されたグループのIDが設定されています。

グループ名として null を指定すると、 グループを指定しないことを表し、 ネイティブの標準のグループが指定されたことになります。 指定されたグループ名のグループが存在しない場合、 ユーザ操作によるグループ作成処理が行われます。

ADFにAccessUserInfoキーの指定が必要です。 このメソッドを呼び出すとサスペンドします。

パラメータ:
name - 名前(通常文字列)を指定します。 姓と名が区別可能な場合、姓として登録されます。
kana - 読み仮名(通常文字列)を指定します。 姓と名が区別可能な場合、姓として登録されます。
phoneNumbers - 電話番号(通常文字列)を配列で指定します。
mailAddresses - メールアドレス(通常文字列)を配列で指定します。
groupName - グループ名(通常文字列)を指定します。 グループを指定しない場合には、null を指定します。
戻り値:
登録されたエントリのIDおよびグループIDを返します。 ユーザが登録操作をキャンセルした場合、null を返します。
例外:
IllegalStateException - ダウンロード即起動アプリがこのメソッドを呼び出した場合に発生します。
IllegalStateException - 待ち受け実行時の非活性化状態で呼び出された場合に発生します。
NullPointerException - 引数 phoneNumbers, mailAddresses がそれぞれ null でない場合に、 配列中に null の要素があった場合に発生します。
IllegalArgumentException - 電話番号として登録できない文字列が指定された場合、 端末がサポートしている長さ以上の電話番号が指定された場合、 端末がサポートしている数以上の電話番号が指定された場合に発生します。
IllegalArgumentException - メールアドレスとして登録できない文字列が指定された場合、 端末がサポートしている長さ以上のメールアドレスが指定された場合、 端末がサポートしている数以上のメールアドレスが指定された場合に発生します。
SecurityException - ADFにAccessUserInfoキーの指定がないアプリケーションが このメソッドを呼び出した場合に発生します。
SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、 電話帳への登録ができない場合に発生します。
InterruptedOperationException - 競合条件などにより、登録操作が異常終了した場合に発生します。

addEntry

public static int[] addEntry(String name,
                             String kana,
                             String[] phoneNumbers,
                             String[] mailAddresses,
                             int groupId)
                      throws InterruptedOperationException,
                             StoreException
ユーザ操作により電話帳エントリを新規登録します。 各引数(groupId以外)はnullや長さ0の配列でもかまいません。

登録が成功した場合、戻り値は長さ2のintの配列です。 配列の0番目の要素には、登録された電話帳エントリのIDが設定されています。 配列の1番目の要素には、そのエントリの電話帳グループのIDが設定されています。 すなわち、戻り値を ids とすると、
PhoneBook.getEntry(ids[0]).getGroupId() == ids[1]
となります。
トラステッドiアプリでない場合、 電話帳エントリのIDには、ダミーのIDが返ります。 電話帳グループのIDには、トラステッドiアプリ、一般アプリの区別によらず、実際に登録されたグループのIDが設定されています。

グループIDとして -1 を指定すると、 グループを指定しないことを表し、 ネイティブの標準のグループが指定されたことになります。 指定されたグループIDのグループが存在しない場合、 例外が発生します。

ADFにAccessUserInfoキーの指定が必要です。 このメソッドを呼び出すとサスペンドします。

パラメータ:
name - 名前(通常文字列)を指定します。 姓と名が区別可能な場合、姓として登録されます。
kana - 読み仮名(通常文字列)を指定します。 姓と名が区別可能な場合、姓として登録されます。
phoneNumbers - 電話番号(通常文字列)を配列で指定します。
mailAddresses - メールアドレス(通常文字列)を配列で指定します。
groupId - グループIDを指定します。 グループを指定しない場合には、-1 を指定します。
戻り値:
登録されたエントリのIDおよびグループIDを返します。 ユーザが登録操作をキャンセルした場合、null を返します。
例外:
IllegalStateException - ダウンロード即起動アプリがこのメソッドを呼び出した場合に発生します。
IllegalStateException - 待ち受け実行時の非活性化状態で呼び出された場合に発生します。
NullPointerException - 引数 phoneNumbers, mailAddresses がそれぞれ null でない場合に、 配列中に null の要素があった場合に発生します。
IllegalArgumentException - 電話番号として登録できない文字列が指定された場合、 端末がサポートしている長さ以上の電話番号が指定された場合、 端末がサポートしている数以上の電話番号が指定された場合に発生します。
IllegalArgumentException - メールアドレスとして登録できない文字列が指定された場合、 端末がサポートしている長さ以上のメールアドレスが指定された場合、 端末がサポートしている数以上のメールアドレスが指定された場合に発生します。
SecurityException - ADFにAccessUserInfoキーの指定がないアプリケーションが このメソッドを呼び出した場合に発生します。
SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、 電話帳への登録ができない場合に発生します。
StoreException - 指定したIDのグループが存在しない場合に発生します(NOT_FOUND)。
InterruptedOperationException - 競合条件などにより、登録操作が異常終了した場合に発生します。

addEntry

public static int[] addEntry(PhoneBookParam param)
                      throws InterruptedOperationException,
                             StoreException
ユーザ操作により電話帳エントリを新規登録します。 引数 param の各要素は、nullや長さ0の配列でもかまいません。

登録が成功した場合、戻り値は長さ2のintの配列です。 配列の0番目の要素には、登録された電話帳エントリのIDが設定されています。 配列の1番目の要素には、そのエントリの電話帳グループのIDが設定されています。 すなわち、戻り値を ids とすると、
PhoneBook.getEntry(ids[0]).getGroupId() == ids[1]
となります。
トラステッドiアプリでない場合、 電話帳エントリのIDには、ダミーのIDが返ります。 電話帳グループのIDには、トラステッドiアプリ、一般アプリの区別によらず、実際に登録されたグループのIDが設定されています。

引数 param のPhoneBookParamオブジェクトにグループ名が指定されており、 そのグループが存在しない場合、 ユーザ操作によるグループ作成処理が行われます。 グループIDが指定されていてそのグループが存在しない場合、 例外が発生します。

ADFにAccessUserInfoキーの指定が必要です。 このメソッドを呼び出すとサスペンドします。

パラメータ:
param - 電話帳エントリのパラメータを指定します。
戻り値:
登録されたエントリのIDおよびグループIDを返します。 ユーザが登録操作をキャンセルした場合、null を返します。
例外:
IllegalStateException - ダウンロード即起動アプリがこのメソッドを呼び出した場合に発生します。
IllegalStateException - 待ち受け実行時の非活性化状態で呼び出された場合に発生します。
NullPointerException - 引数 param が null の場合に発生します。
SecurityException - ADFにAccessUserInfoキーの指定がないアプリケーションが このメソッドを呼び出した場合に発生します。
SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、 電話帳への登録ができない場合に発生します。
StoreException - グループIDが指定されているときに、 指定したIDのグループが存在しない場合に発生します(NOT_FOUND)。
InterruptedOperationException - 競合条件などにより、登録操作が異常終了した場合に発生します。

getId

public int getId()
電話帳エントリのIDを取得します。

戻り値:
電話帳エントリのIDを返します。

getName

public XString getName()
電話帳エントリの名前(XString)を取得します。
姓と名に分かれて登録されている場合、両者を結合して返します。 結合方法は機種依存ですが、端末のネイティブの電話帳機能と同じです。

戻り値:
名前を返します。 登録されていない場合、空文字列のXStringを返します。

getName

public XString getName(int part)
電話帳エントリの姓や名(XString)を取得します。
名前を姓や名に分けて登録する機能がない場合、 姓を指定したときに名前(getName()で返る名前) が返ります。 それ以外の区別に対しては、null を返します。

パラメータ:
part - 姓、名の区別を指定します。 FAMILY_NAME、 GIVEN_NAME のいずれかを指定します。
戻り値:
名前を返します。 登録されていない場合、空文字列のXStringを返します。
例外:
IllegalArgumentException - 引数 part の値が不正な場合に発生します。

getKana

public XString getKana()
電話帳エントリの読み仮名(XString)を取得します。
姓と名に分かれて登録されている場合、両者を結合して返します。 結合方法は機種依存ですが、端末のネイティブの電話帳機能と同じです。

戻り値:
読み仮名を返します。 登録されていない場合、空文字列のXStringを返します。

getKana

public XString getKana(int part)
電話帳エントリの姓や名の読み仮名(XString)を取得します。
名前を姓や名に分けて登録する機能がない場合、 姓を指定したときに名前の読み仮名(getKana()で返る読み仮名) が返ります。 それ以外の区別に対しては、null を返します。

パラメータ:
part - 姓、名の区別を指定します。 FAMILY_NAME、 GIVEN_NAME のいずれかを指定します。
戻り値:
読み仮名を返します。 登録されていない場合、空文字列のXStringを返します。
例外:
IllegalArgumentException - 引数 part の値が不正な場合に発生します。

getPhoneNumbers

public XString[] getPhoneNumbers()
電話帳エントリの電話番号(XString)を取得します。

電話帳エントリに空文字列の電話番号が登録されている場合、 その電話番号は無視され、 このメソッドの戻り値には含まれません。

戻り値:
登録されているすべての電話番号(XString)を配列で返します。 登録されていない場合、nullを返します。 配列の要素が null あるいは空文字列のXStringになることはありません。 返される配列は、このオブジェクトが内部で保持している配列のコピーです。

getPhoneNumber

public XString getPhoneNumber(int index)
電話帳エントリの電話番号(XString)の1つを取得します。
getPhoneNumbers()[index] と同じ値が返ります。

パラメータ:
index - 電話番号のインデックスを指定します。
戻り値:
指定されたインデックスの電話番号(XString)を返します。
例外:
ArrayIndexOutOfBoundsException - 指定されたインデックスの電話番号が存在しない場合に発生します。

getMailAddresses

public XString[] getMailAddresses(int part)
電話帳エントリのメールアドレス(XString)を取得します。

電話帳エントリに空文字列のメールアドレスが登録されている場合、 そのメールアドレスは無視され、 このメソッドの戻り値には含まれません。

パラメータ:
part - アドレス中の取得する部分を指定します。 ADDRESS_FULL、 ADDRESS_USER、 ADDRESS_DOMAIN のいずれかを指定します。
戻り値:
登録されているすべてのメールアドレス(XString)を配列で返します。 登録されていない場合、nullを返します。 引数 part が ADDRESS_FULL の場合には、 戻り値の配列の要素が null あるいは空文字列のXStringになることはありません。 返される配列は、このオブジェクトが内部で保持している配列のコピーです。
例外:
IllegalArgumentException - 引数 part の値が不正な場合に発生します。

getMailAddress

public XString getMailAddress(int index,
                              int part)
電話帳エントリのメールアドレス(XString)の1つを取得します。
getMailAddresses(part)[index] と同じ値が返ります。

パラメータ:
index - メールアドレスのインデックスを指定します。
part - アドレス中の取得する部分を指定します。 ADDRESS_FULL、 ADDRESS_USER、 ADDRESS_DOMAIN のいずれかを指定します。
戻り値:
指定されたインデックスのメールアドレス(XString)を返します。
例外:
ArrayIndexOutOfBoundsException - 指定されたインデックスのメールアドレスが存在しない場合に発生します。
IllegalArgumentException - 引数 part の値が不正な場合に発生します。

getGroupName

public XString getGroupName()
電話帳エントリのグループ名(XString)を取得します。
PhoneBookGroup.getEntry(getGroupId()).getName() と同じ値が返ります。

戻り値:
グループ名を返します。

getGroupId

public int getGroupId()
電話帳エントリのグループIDを取得します。

戻り値:
グループIDを返します。
概要  パッケージ   クラス  階層ツリー  非推奨 API  索引  ヘルプ 
 前のクラス   次のクラス フレームあり    フレームなし    
概要:  入れ子 | フィールド | コンストラクタ | メソッド 詳細:  フィールド | コンストラクタ | メソッド

NTT DoCoMo,Inc.

本製品または文書は著作権法により保護されており、その使用、複製、再頒布および逆コンパイルを制限するライセンスのもとにおいて頒布されます。NTTドコモ（その他に許諾者がある場合は当該許諾者も含めて）の書面による事前の許可なく、本製品および関連する文書のいかなる部分も、いかなる方法によっても複製することが禁じられます。フォントを含む第三者のソフトウェアは、著作権法により保護されており、その提供者からライセンスを受けているものです。

Sun、Sun Microsystems、Java、J2MEおよびJ2SEは、米国およびその他の国における米国 Sun Microsystems,Inc.の商標または登録商標です。サンのロゴマークは、米国 Sun Microsystems, Inc.の登録商標です。

「ｉモード」、「ｉアプリ／アイアプリ」、「ｉ-αppli」ロゴ、「DoJa」はNTTドコモの商標または登録商標です。