com.nttdocomo.system
クラス PhoneBook

Object
  com.nttdocomo.system.PhoneBook

すべての実装インタフェース:

MailConstants, PhoneBookConstants

public final class PhoneBook

extends Object

implements MailConstants, PhoneBookConstants

携帯電話のネイティブの電話帳管理機能にアクセスする手段を提供します。 このクラスのインスタンスは、 携帯電話のネイティブの電話帳の 1 つのエントリを表します。

このクラスに定義されているクラスメソッドの使い方や、 ネイティブのデータへのアクセス方法に関する規定の大原則は com.nttdocomo.system パッケージの記述を参照して下さい。 ただし、エントリ登録機能 (addEntry()) については、 下記の点が大原則と異なります。

addEntry() の戻り値について:

このクラスで定義されている addEntry() は、 登録された電話帳のエントリ ID の他に、 そのエントリが登録された電話帳グループのエントリ ID を返します。 詳細は、各メソッドの説明を参照して下さい。

エントリ登録時の文字列の扱いについて:

電話番号の配列、メールアドレスの配列、電話帳グループ名に限っては、 下記のように振る舞います。

ネイティブのデータとして登録できない文字が含まれている場合:

• メールアドレスの配列については、 配列中に、1つでもそのような要素が存在している場合には、例外が発生します。
• [DoJa-3.5 (900iC) まで]
  電話番号の配列については、 配列中に、1つでもそのような要素が存在している場合には、例外が発生します。
  [DoJa-4.0 (901i) 以降]
  電話番号の配列については、配列中に、 下記のいずれかの文字列が要素として存在している場合には例外が発生します。
  • Phone.call(String) で例外が発生するような文字列
  • '/' が含まれている文字列
  • ',' が含まれている文字列
  そうでない場合(例外が発生するような文字列ではないが、 ネイティブのデータとして登録できない文字が含まれている場合)は、 そのような文字は取り除かれた上でネイティブに渡されます。 空白や '?' に置換されることは有りません。
• 電話帳グループ名の、既存のグループとの一致判定については、 登録できない文字を取り除いたり空白か'?'に置換してから行うかどうかは機種依存です。 その判定の結果、既存のグループと一致せずに、 ユーザ操作による電話帳グループ作成処理へ移行した場合には、 大原則通り、 登録できない文字を全て取り除いた文字列か、 全て空白に置換した文字列か、 全て '?' に置換した文字列がネイティブ機能へ渡されます。

ネイティブのデータとして登録できる最大バイト数を超える文字列が指定された場合:

• 電話番号の配列、メールアドレスの配列については、 配列中に、1つでもそのような要素が存在している場合には、例外が発生します。
• 電話帳グループ名の、既存のグループとの一致判定については、 超過分の文字を削除してから行うかどうかは機種依存です。 その判定の結果、 既存のグループと一致せずに、 ユーザ操作による電話帳グループ作成処理へ移行した場合には、 大原則通り、超過分の文字が削除された文字列がネイティブ機能へ渡されます。

null や空文字列("")が指定された場合:

• 電話番号の配列、メールアドレスの配列については、配列の代わりに null や長さ 0 の配列を指定することは可能です。 その場合には、その項目には何も入力されていない状態で登録画面が表示されます。 配列中のいずれかの要素に null を指定した場合には例外が発生します。 配列中に空文字列の要素が指定された場合には、 その要素が無いものとして扱われます。その結果、 空文字列が設定されている要素の数だけ短かい配列が渡されることとなります。
• 電話帳グループ名に null や空文字列を指定した場合の動作については、それぞれ addEntry(String, String, String[], String[], String)、 addEntry(PhoneBookParam) を参照して下さい。

位置情報の扱いについて:

電話帳エントリ内の位置情報をサポートしていない実装では、 単に位置情報は無視されます。 電話帳エントリ内の位置情報をサポートしている実装では、以下の通りとなります。

• 位置情報オブジェクトとして null が指定されていた場合には、 位置情報の項目には何も入力されていない状態で登録画面が表示されます。
• 位置情報オブジェクトは設定されているが、 精度として 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) で、 それぞれ取得することができます。

ミニマムスペック:

• ミニマムスペックでは、 電話番号、メールアドレスはそれぞれ1件あたり3つまで登録できます。
• ミニマムスペックでは、 メールアドレスは1つあたり50バイトまで登録できます。 バイト数は、デフォルトのエンコーディングで評価されます。
• ミニマムスペックでは、名前は姓と名を分けられる必要はありません。
• [DoJa-5.0 (903i) 以降] ミニマムスペックでは、 電話帳エントリ内の位置情報の取得・設定が可能です。 ただし、測位時刻を保持することはできません。

導入されたバージョン:

DoJa-3.0 (505i)

関連項目:

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)を取得します。